AGENTS.md, CLAUDE.md and GEMINI.md: project instructions for coding agents

Which agent reads which file

• CLAUDE.md — Claude Code. It also supports imports, so a CLAUDE.md can pull in another file with an @path line.
• AGENTS.md — Codex and a growing list of other agents and editors that adopted it as a shared convention.
• GEMINI.md — Gemini CLI, which can also be configured to read other file names.
• Most agents also read the same kind of file in subfolders or in your home directory, for rules that apply to one package or to every project.

Keep one source of truth

Three files with the same content drift apart within a week. Pick AGENTS.md as the real file, and make the others point at it: a CLAUDE.md that contains only @AGENTS.md, and a GEMINI.md configured or written the same way. Every agent then reads the same instructions and you edit one file.

What belongs in it

Short and specific beats long and general. The things an agent cannot infer from the code:

• How to build, test and lint — the exact commands, including the one test command that is fast.
• Layout — where the app, the shared library and the generated code live, and what must not be edited by hand.
• Conventions that are not obvious — naming, error handling, which library to use for dates or HTTP.
• Hard rules — no new dependencies without asking, never touch migrations, run the formatter before finishing.
• Environment quirks — the platform, the shell, anything that differs from a default setup.

What to leave out

Anything the agent can read from the code, long style essays, and secrets. The file is loaded into every session, so every line costs context; a 40-line file that is all signal outperforms a 400-line one.