Guides · Go
How to write an AGENTS.md for a Go project
Measured across 77 of the most-starred Go repositories on GitHub. The median scores 70 out of 100.
What Go repos get wrong
Go scores well because its toolchain removes most of the decisions: go.sum pins dependencies, go test ./... is universal, and the compiler type checks every build. That last point matters for how this is scored, because a separate type checker is not applicable to Go and is excluded rather than counted against it. What is left is instructions. Half of Go repositories ship none, and among those that do, half never name a command.
Most common failures
share of 77 Go repositories scoring zero on each
Lower is better here. These are failures, not scores.
A working example
Commands first, conventions second, none of the persuasion a README carries. The test is whether a capable stranger could make a small change and verify it using only this file.
Save it at the root of the repository
as AGENTS.md. Tool-specific files like CLAUDE.md or .cursorrules still work, but
AGENTS.md is the one every tool reads.
# AGENTS.md ## Setup go mod download ## Commands go test ./... # full suite, must pass before any commit go build ./... golangci-lint run ## Conventions - Tests sit beside the code they cover, as *_test.go. - Errors are wrapped with %w, never swallowed. ## Gotchas - Anything under internal/ is not importable from outside this module.
The two lines that matter most
If you write nothing else, write these. An agent that cannot install the project cannot start, and one that cannot run the tests cannot tell whether it broke something.
# installgo mod download# verifygo test ./...
Have it drafted instead
Point the tool at a repository and it writes the file from what is already there, rather than from a template.
For private code, the same rubric runs on your machine and sends nothing anywhere:
$ npx agentreadme --write-agents
Other ecosystems