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

> Put in an AGENTS.md or CLAUDE.md the commands, style rules and gotchas the agent cannot derive from the code, and cut every line whose removal would not cause a mistake.

## Answer

Write down what an agent cannot work out by reading your code: commands it would not guess, style rules that differ from defaults, and non-obvious gotchas. Leave out anything derivable from the code, standard conventions, long explanations and detailed API documentation. For every line ask: "Would removing this cause Claude to make mistakes?" If not, cut it. This follows the Claude Code best-practices page, checked 2026-09-28. The advice applies equally to `AGENTS.md`.

## 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.

```markdown
# 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:

```markdown
# 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]].

## See also

- [[agents-md-vs-claude-md]]
- [[instruction-file-ignored-by-agent]]
- [[claude-code-skills-vs-subagents-vs-hooks]]
- [[mcp-too-many-tools-context-bloat]]

## Sources

- [Claude Code — Best practices (Write an effective CLAUDE.md)](https://code.claude.com/docs/en/best-practices)
- [Claude Code — How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [AGENTS.md — a simple, open format for guiding coding agents](https://agents.md)

## Sources

- [Claude Code — Best practices (Write an effective CLAUDE.md)](https://code.claude.com/docs/en/best-practices)
- [Claude Code — How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [AGENTS.md — a simple, open format for guiding coding agents](https://agents.md)