A good AGENTS.md is a concise operating guide: repository map, commands, validation expectations, safety boundaries and the route to authoritative decisions. Keep historical rationale and detailed architecture choices in decision records instead of turning AGENTS.md into an unversioned encyclopedia.
What belongs in AGENTS.md
Use the file for instructions that apply whenever an agent works in its directory scope. Give exact commands and observable completion criteria. Explain unusual safety boundaries that are not apparent from the code, and point to the system that contains reviewed decisions.
- A short repository map and ownership boundaries.
- Canonical setup, test, lint and build commands.
- Files or generated artifacts that must not be edited directly.
- When to retrieve decisions and how to cite them.
A compact example
The most useful examples are specific enough to execute and short enough to remain visible in context. Replace placeholders with real commands and repository paths.
# Working in this repository
- Run `npm test` for behavioural changes.
- Do not edit generated files under `dist/`.
- Keep public API changes backward compatible.
## Decisions
Before changing architecture, persistence or public behaviour, query the repository decision record. Cite relevant IDs in your plan. If no record answers the question, flag the gap; do not infer approval.Use nested scope sparingly
Nested instruction files can express commands or boundaries that apply only to one part of a monorepo. Avoid repeating the root file. State only the local differences so agents can combine the hierarchy without resolving contradictory copies.
Common failure modes
Vague requests such as 'write clean code' are difficult to verify. Huge style guides crowd out task context. Architectural rules without rationale or lifecycle become stale bans. Prefer executable commands, scoped boundaries and links into reviewed authority.