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 reads AGENTS.md. Claude Code reads CLAUDE.md. Keep both files byte-for-byte identical and write both on every change.

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 and an identical CLAUDE.md.

Done when both files exist, are identical, and every command and path in them exists in the repo.