A good AGENTS.md holds only the commands and gotchas an agent cannot infer from the code

Details

An instruction file is text that an agent loads into its context at the start of a session. Everything in it costs context on every task, and the Claude Code docs say bloated files cause Claude to ignore your actual instructions. There is no required format: agents.md says it is standard Markdown and you can use any headings.

What to include and exclude

Include	Exclude
Commands the agent cannot guess	Anything it can learn by reading the code
Code style rules that differ from defaults	Standard language conventions
Test instructions and preferred test runner	Detailed API documentation (link to it instead)
Branch naming and PR conventions	Information that changes often
Environment quirks, such as required env vars	File-by-file descriptions of the codebase
Non-obvious behaviours and gotchas	Self-evident advice such as "write clean code"

Worked example: a generic web project

Before, a bloated file. Each <- note says what to do with the line.

# Project guide
This is a web app built with TypeScript and React.        <- cut: visible in package.json
Write clean, readable, well-tested code.                  <- cut: self-evident
src/components/ contains the React components.            <- cut: visible in the tree
Use `const` instead of `var`.                             <- cut: standard convention
The users API returns id, name, email, created_at ...     <- cut: link to API docs instead
Run tests with `npm test`.                                <- keep, see below
Migrations need `npm run db:migrate` before tests.       <- keep: not guessable

After, a trimmed file:

# Commands
- Tests: `npm test -- <file>` runs one file (the full suite takes 10 minutes)
- Migrations: run `npm run db:migrate` before any test that touches the database

# Gotchas
- `.env.example` is the template. Never edit `.env`.
- API reference: docs/api.md (read only when changing endpoints)

The trimmed file has four lines of content, and each one would cause a wrong guess if it were missing. An agent could guess npm test, so the kept line adds how to run a single file and why it matters. If the agent still ignores one rule, the docs suggest adding emphasis such as "IMPORTANT" to that one line, not to many.

Self-review checklist

1. Could the agent learn this line from the code or the config files? If yes, cut it.
2. Would a wrong guess here cause a real mistake? If no, cut it.
3. Is it specific? "Use 2-space indentation" works better than "format code nicely" (memory page).
4. Does any line contradict another file? Claude may pick one arbitrarily.
5. Is the file under about 200 lines? The docs say longer files reduce adherence.

Generate, then prune

Run /init in Claude Code to generate a starter CLAUDE.md from the project. If one exists, it suggests improvements instead of overwriting it. For a checked-in file, /doctor proposes cuts for content Claude can derive from the codebase. Split growing files with @path/to/file imports, but the memory page notes imported files still load into context. For knowledge that only matters sometimes, the best-practices page suggests skills. To keep one file for several tools, see agents-md-vs-claude-md.

Common mistakes

• Pasting the README or an architecture tour into the file.
• Documenting rules the linter already enforces. Enforce them with a hook or the linter instead.
• Adding a rule after every mistake and never removing one.
• Marking many lines as important, so none stands out.
• Treating the file as a guarantee. It is advice, see instruction-file-ignored-by-agent.