A good AGENTS.md is short, scoped to always-true rules, and points to deeper context for everything specific. The eight practices below — clear structure, runnable commands, conventions over preferences, and a link to per-file context — are what separate an AGENTS.md that improves agent output from one the agent skims past.
AGENTS.md is the agent-readable counterpart to a README: the file an AI coding agent reads to learn how to work in your repo. Here is how to write one that actually changes what the agent does.
1. Lead with what to run
Put the concrete commands first — install, test, lint, build. An agent uses these on almost every task; burying them below prose means they get missed.
2. State conventions, not preferences
"Use the existing HTTP client in src/lib/http" is actionable. "Write clean code" is noise. Give rules an agent can check itself against.
3. Keep it to always-true, repo-wide rules
AGENTS.md is global. Reserve it for what is true everywhere; push area-specific knowledge to code-anchored context so the file stays short and readable (why: AGENTS.md isn’t enough on its own).
4. Be explicit about what NOT to do
Name the retired module, the deprecated pattern, the directory to never touch. Negative constraints prevent the confident, wrong change an agent makes when it cannot see history.
5. Point to where deeper context lives
The most valuable line in an AGENTS.md is often the one that tells the agent a context layer exists and how to pull from it before editing. Make the file the front door, not the whole house.
6. Keep it current — treat it like code
An AGENTS.md that describes a system two refactors out of date is worse than none, because the agent trusts it. Review it when the things it describes change, or it becomes a source of context drift.
7. Use clear structure
Headings, short sections, and lists. Agents, like humans, parse a scannable document better than a wall of text — one topic per section.
8. Don’t try to encode everything
A brief is not a repo memory. You cannot fit years of decisions and gotchas in a file read at the top of every session — and you shouldn’t try. Keep the brief lean; let the durable knowledge live where it can be retrieved per file.
FAQ
How long should AGENTS.md be?
Short enough that an agent reliably reads all of it — typically one screen. If it is growing past that, the overflow belongs in per-area context, not in the file.
What goes in AGENTS.md vs. a context layer?
Always-true and global → AGENTS.md. Specific to an area and likely to change → a code-anchored context layer.
Does every repo need one?
Any repo an AI agent touches benefits from one. It is the cheapest, highest-leverage step toward better agent output.
Driftless turns per-area knowledge into living, code-anchored context that complements your AGENTS.md. See how it works.