Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (60 loc) · 6.55 KB

AGENTS.md

File metadata and controls

87 lines (60 loc) · 6.55 KB
Raw

Instructions for AI Agents

This file gives AI coding agents (Claude Code, Codex, Cursor, Copilot, Aider, etc.) the rules they must follow when contributing to this repository. It complements CONTRIBUTING.md, which remains the source of truth for humans. Agents must respect every rule there as well.

If a rule here conflicts with CONTRIBUTING.md, follow CONTRIBUTING.md and flag the discrepancy in the PR description.

Zero-spam & PR authorization policy

  • Require an issue: DO NOT create a Pull Request unless there is an existing, open, and approved GitHub Issue that explicitly requests this work. Drive-by PRs, speculative refactors, "found a typo" PRs, and unsolicited feature work are not accepted.
  • Require assignment: DO NOT start work on an issue unless it is assigned to the human user driving you. An unassigned issue is not an invitation to start coding. If the human has not been assigned, ask them to request assignment from a maintainer first and wait.
  • Respect claimed issues: If someone has commented that they intend to work on the issue, or has been assigned to it, do not open a competing PR, push commits, or start a draft PR. However, if there has been no visible progress for an extended period, it is acceptable to politely ask whether they are still actively working on it before taking further action.
  • Stay inside the issue's scope: Implement only what the issue describes. If you discover related problems, mention them in the PR description or open a separate issue. Do not silently expand the scope.
  • One issue, one PR: Do not bundle multiple issues into a single PR, and do not split a single issue across multiple PRs without coordinating in the issue first.
  • No PR for chores that already have automation: Dependency bumps (Renovate/Dependabot), changelog regeneration, generated-file refreshes, and similar housekeeping are handled by bots or release tooling. Do not open PRs that duplicate that work.

Pull request rules

  • Do not delete or modify the checklist in .github/PULL_REQUEST_TEMPLATE.md. When opening a PR, keep every checklist item and tick off only the boxes that genuinely apply to the change.
  • Keep the Fixes # / Relates to # lines and fill them in when there is a related issue or PR.
  • Write a clear description of what changed and why. Do not leave the template description empty.
  • One logical change per PR. Do not bundle unrelated refactors with feature work or bug fixes.

Required local checks before opening a PR

Run these from the repo root and make sure they all pass. CI will run them too, but agents must verify locally first.

Check Command When
Code formatting make fmt (wraps go fmt) Always
Static analysis make vet (wraps go vet) Always
Linter make golangci Always
Unit tests make test Always
Generated code make generate When you change anything under apis/, mocks, or protobuf
Scalers schema make generate-scalers-schema When you add or change a scaler's metadata, fields, or annotations
Schema verification make verify-scalers-schema After running generate-scalers-schema
Manifest verification make verify-manifests When you change CRDs or RBAC

Optionally install pre-commit and run pre-commit run --all-files. This executes go fmt, trailing-whitespace, end-of-file fixer, doctoc, golangci-lint, the scaler-sort check, and the changelog validator in one go. See .pre-commit-config.yaml.

Do not skip, disable, or bypass these checks (e.g. --no-verify, commenting out linters, adding broad //nolint directives) to make a PR pass. Fix the underlying issue.

Tests

  • New scalers must ship with end-to-end (e2e) tests. See tests/README.md.
  • Bug fixes should add a regression test that fails without the fix.
  • New behavior in existing code should be covered by unit tests.
  • Do not delete existing tests to make a build green. If a test is genuinely wrong, explain why in the PR description.
  • Do not weaken assertions (e.g. replacing exact checks with assert.NotNil) just to make a flaky test pass.

Release notes metadata

Release notes are generated automatically from merged PR metadata via the release-notes workflows.

Rules (from CONTRIBUTING.md#release-notes):

  • PR titles must follow Component: Description. The release notes renderer bolds the component automatically.
  • PRs must include exactly one valid release-notes label unless skip-changelog is explicitly used.
  • Use skip-changelog only for changes that should be excluded from generated release notes.

Commit hygiene

  • Every commit must be signed off (DCO). Use git commit -s. The Signed-off-by: trailer must match the author. CI rejects PRs with unsigned commits.
  • Never set --no-verify, --no-gpg-sign, or otherwise skip hooks unless the human user explicitly asks.
  • Do not commit generated files that are not produced by the documented make targets above.
  • Do not commit secrets, credentials, .env files, or large binaries.

Code style

Scope discipline

  • Do not "drive-by" reformat, rename, or restructure code outside the scope of the requested change.
  • Do not bump dependencies unless the task requires it.
  • Do not change CI workflows, release tooling, or governance files unless explicitly asked.
  • If you encounter unrelated issues while working, mention them in the PR description rather than fixing them in the same PR.

Documentation

  • Behavior or UX changes require a matching docs PR against kedacore/keda-docs. Link it in the PR template's Relates to line.
  • Manifest changes that affect deployment require a matching PR against kedacore/charts.

When in doubt

Stop and ask the human reviewer rather than guessing. It is better to leave a TODO and surface the question in the PR description than to invent behaviour, fabricate API names, or silence failing checks.