To AGENT.md?

[markmandel]

We're getting so very many people coming through doing drive by contributions on our help-wanted and good-first-issue issues (👋🏻 if you see this, thanks!).

I expect most/all of them are doing AI code generation.

To get better results from that, a good AGENTS.md is probably a good idea -- just given the reality of the situation, and would mean there would be less review on the human side.

Anyone got experience putting together a particularly good AGENTS.md and wants to take a stab? Othewise, I can have a go.

[ayush-that]

Hi @markmandel, how's this? In one of Theo's videos he advised to not add architecture already discoverable in the code to AGENTS.md so i've kept it minimal.

AGENTS.md

Build, test, and lint: use the build Makefile, not host Go tools

There is no root Makefile. Builds, tests, and lint run through build/Makefile inside a Docker build image (the only host dependencies are Make and Docker), so invoke targets as make -C build <target> from the repo root.

• Validate Go changes with make -C build test-go and make -C build lint. The first run builds the image and is slow.
• make -C build test runs the local, non-e2e suite. See build/docs/make-reference.md for the documented targets.
• CI runs these targets in the build image with a pinned Go toolchain, so a passing raw go test, go build, or golangci-lint does not mean CI passes, and is not a substitute.
• Do not run the e2e targets (make -C build test-e2e...) unless asked. They need a live Kubernetes cluster and take a long time.

Do not hand-edit generated files

Edit the source and regenerate with the matching target. CI fails when generated output is stale.

• pkg/apis/**/zz_generated.deepcopy.go and pkg/client/**: edit the API types in pkg/apis/, then make -C build gen-crd-code.
• pkg/sdk/**/*.pb*.go (including the .pb.gw.go gateway files) and pkg/allocation/go/**: edit the .proto files in proto/, then make -C build gen-all-sdk-grpc or gen-allocation-grpc.
• install/yaml/install.yaml: edit the Helm templates under install/helm/, then make -C build gen-install.
• site/content/en/docs/Reference/agones_crd_api_reference.html: regenerate with make -C build gen-api-docs.

Dependencies

Dependencies are vendored in vendor/; do not edit it by hand. Change go.mod, then run go mod tidy and go mod vendor (see build/docs/dependencies.md).

New source files

Start new Go files with the Apache license header from build/boilerplate.go.txt (generated code gets it automatically).

Commits

Sign off every commit with git commit -s. DCO is bot-enforced, and an unsigned commit blocks the PR. Squash the branch to a single commit before it merges.

New features

A new feature usually sits behind a feature gate in pkg/util/runtime/features.go and moves through stages: alpha, then beta, then stable. Agree the design on a kind/design issue before writing code, and ship documentation under site/.

[markmandel]

https://github.com/kedacore/keda/blob/main/AGENTS.md has some interesting ideas - putting human-in-the-loop guidance in there, as well as no PR duplication guidance.

Probably something akin to as well "If there is outstanding discussions or questions on the backing issue, do not implement this feature, and instead go back to the issue to discuss".

[ayush-that]

Okie. Added human in the loop, no duplication and guardrails to stop LLMs from writing code blindly without discussion. Thoughts?

AGENTS.md

Rules for AI coding agents contributing to Agones. CONTRIBUTING.md and build/README.md are the source of truth for humans, and agents must follow them too. If anything here conflicts with CONTRIBUTING.md, follow CONTRIBUTING.md and note the discrepancy in the PR.

Before you write code

• Work only from an existing, open issue that asks for the change. No drive-by, speculative, or "while I was here" PRs.
• Before starting, check the issue is not already being worked on: no assignee, no linked PR, and no recent comment from someone else taking it. Do not open a competing or duplicate PR. If it was claimed long ago with no progress, ask on the issue before taking over.
• If the issue still has open questions or unresolved discussion, do not implement it. Go back to the issue, raise the questions, and wait for the maintainers before writing code.
• Stay inside the issue's scope. One issue, one PR. Surface unrelated problems in the PR description or a new issue rather than fixing them here.

Working with your human

• You are assisting the human contributor who is driving you, not acting on your own. When unsure, stop and ask them rather than guessing. Do not invent API names, fabricate behavior, or silence a failing check to make something pass. A clear question or a TODO beats a confident wrong guess.
• Keep changes minimal and match the surrounding code. Do not add comments that restate what the code does, introduce new abstractions or dependencies without justification, or reformat and rename code outside the change.

Build, test, and lint: use the build Makefile, not host Go tools

There is no root Makefile. Builds, tests, and lint run through build/Makefile inside a Docker build image (the only host dependencies are Make and Docker), so invoke targets as make -C build <target> from the repo root.

• Validate Go changes with make -C build test-go and make -C build lint before opening a PR, and do not claim they pass without running them. The first run builds the image and is slow.
• make -C build test runs the local, non-e2e suite. See build/docs/make-reference.md for the documented targets.
• CI runs these targets in the build image with a pinned Go toolchain, so a passing raw go test, go build, or golangci-lint does not mean CI passes, and is not a substitute.
• Do not run the e2e targets (make -C build test-e2e...) unless asked. They need a live Kubernetes cluster and take a long time.
• Do not disable or weaken checks (deleting tests, broad //nolint, skipping hooks) to get a PR green. Fix the underlying issue.

Do not hand-edit generated files

Edit the source and regenerate with the matching target. CI checks that several of these stay in sync with their source.

• pkg/apis/**/zz_generated.deepcopy.go and pkg/client/**: edit the API types in pkg/apis/, then make -C build gen-crd-code.
• gRPC and SDK code generated from the .proto files in proto/ (the *.pb*.go files, plus the per-language SDK outputs under sdks/ and test/sdk/): edit the .proto files, then make -C build gen-all-sdk-grpc, or gen-allocation-grpc for the allocator.
• install/yaml/install.yaml: edit the Helm templates under install/helm/, then make -C build gen-install.
• site/content/en/docs/Reference/agones_crd_api_reference.html: regenerate with make -C build gen-api-docs.
• CHANGELOG.md is updated from generated release notes at release time. Ordinary PRs should not edit it.

Dependencies

Dependencies are vendored in vendor/, so do not edit it by hand. Change go.mod, then run go mod tidy and go mod vendor (see build/docs/dependencies.md).

New source files

Start new Go files with the Apache license header, copied from an existing non-generated .go file. Do not copy build/boilerplate.go.txt, which appends an autogenerated marker and is only for generators.

Commits and the PR

• Sign off every commit with git commit -s. DCO is bot-enforced, and an unsigned commit blocks the PR.
• Squash the branch to a single commit before it merges.
• Fill in .github/pull_request_template.md: set one /kind label, describe what and why, and put Closes #<issue> for the issue it fixes.

New features

A new feature usually sits behind a feature gate in pkg/util/runtime/features.go and moves through stages: alpha, then beta, then stable. Agree the design on a kind/design issue before writing code, and ship documentation under site/.