AGENTS.md

AGENTS.md is loaded into every session, so each line costs attention on every task. It earns its place only if an agent would get something wrong or waste time without it, and could not find it by reading the repo. Overviews, directory tours, stack lists and anything a linter or config file already enforces fail that test: studies of these files found they add cost without improving results, while specific, non-obvious instructions do get followed.

Codex, Claude Code and most other coding agents read AGENTS.md, so it is the only file. Claude Code reads AGENTS.md only when it finds no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it (docs). When a teammate's Claude Code can't read AGENTS.md, for example on an old version or with Project instructions set to claude-md, add a CLAUDE.md whose only line is @AGENTS.md.

Create

Use this for a new project, or a repo without AGENTS.md.

1. Copy assets/AGENTS.md.
2. Fill in the name and the one or two sentence description. On an empty project, ask the user for them. On an existing repo, take them from README.md and confirm.
3. If the repo already has a CLAUDE.md or other agent instructions, carry over only the lines that pass the test above, sorted into the template's sections (see Edit). List what you left out and why, so the user can object.
4. On an existing repo, fill Commands with the commands the build files, scripts and CI actually define, narrowest first. Run the cheap ones to confirm they work.
5. Keep the section comments. They guide whoever adds the next line, and Claude Code strips HTML comments before loading the file.
6. Write AGENTS.md. Delete the CLAUDE.md files you carried lines from, so Claude Code reads AGENTS.md.

Done when AGENTS.md exists, no CLAUDE.md at the root or in .claude/ hides it, and every command and path in it exists in the repo.