What belongs in the file
Facts an agent cannot infer by reading the repository: which package manager, the exact test command, which folders are generated, which API cannot change shape. Everything else it can see for itself.
AGENTS.md generator
The file a coding agent reads when it opens your repository. Answer what it cannot work out on its own - the package manager, the test command, what it must not touch - and take the file in whichever format your tool expects.
- Formats4, from one answer set
- Presets4 stacks
- Read by the agentEvery session
What the agent cannot guess
Everything here ends up in the file. Leave a field empty to leave the line out.
Project
Stack
Commands
The exact line you would type, not a description of it.
Rules
A rule worth writing is one that has already gone wrong.
The file
Save as AGENTS.md (repository root). Read by most coding agents, including Claude Code and Cursor. Write this one first.
52 lines · 1,409 characters · ≈ 376 tokens per session
What to leave out
“Write clean code”, “follow best practices”, “use meaningful names”. They cost context and change nothing - no agent was about to write deliberately bad code. A rule worth writing is one that has already gone wrong.
Keeping it short
This file is read on every session, so every line is paid for repeatedly - the token count under the file is the recurring cost. Two hundred useful lines beat a thousand hedged ones, and a rule that stops being true should be deleted rather than left to mislead.
Frequently asked questions
- What is AGENTS.md?
- It is a plain Markdown file at the root of a repository that tells a coding agent how to work in it: which package manager to use, the exact test command, which directories are generated, and what it must not touch. Agents read it at the start of a session, the way a new colleague would read a contributing guide.
- What should go in an AGENTS.md file?
- Only facts an agent cannot work out by reading the code. The package manager, the real test command, the folders that are generated and will be overwritten, the API whose shape cannot change. Anything it can see for itself is wasted context.
- What should I leave out?
- Instructions like "write clean code", "follow best practices" or "use meaningful names". They cost tokens on every session and change nothing, because no agent was about to write deliberately bad code. A rule worth writing is one describing something that has already gone wrong.
- Is AGENTS.md the same as CLAUDE.md or .cursorrules?
- The content is largely the same; the filename and a few conventions differ per tool. Pick the format your tool expects at the top of the page and the file is emitted accordingly, so the same answers produce whichever of the four you need.