field-guide
Which file does each coding agent read?
Six agents, six sets of rules. Each row is taken from the maker's own documentation, read on October 11, 2026. The short version: write one AGENTS.md, then add the one-line pointers for the agents that need them.
| Agent | Reads | Where it looks | To use one AGENTS.md | Watch out |
|---|---|---|---|---|
| CodexOpenAI | AGENTS.md (or AGENTS.override.md, which wins in the same folder) | Your Codex home (~/.codex), then every folder from the project root down to where you are working, at most one file per folder. Files closer to you come later and override. | Nothing to add: AGENTS.md is read as it is. | Codex stops adding instruction files once they reach project_doc_max_bytes, 32 KiB by default. A long file is cut off.Source: OpenAI: Codex documentation: AGENTS.md |
| Claude CodeAnthropic | CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md; AGENTS.md when there is no CLAUDE.md | The working folder and every folder above it at start-up; folders below it when Claude opens a file there. | A CLAUDE.md holding the line @AGENTS.md imports the rulebook. | If a CLAUDE.md or CLAUDE.local.md exists, Claude reads that instead of AGENTS.md. Reading AGENTS.md directly needs v2.1.277 or later; the @AGENTS.md import avoids both problems.Source: Anthropic: Claude Code documentation: How Claude remembers your project |
| GitHub CopilotGitHub | .github/copilot-instructions.md, .github/instructions/*.instructions.md, AGENTS.md, or a single CLAUDE.md or GEMINI.md at the root | AGENTS.md files can be anywhere in the repository; the nearest one in the folder tree takes precedence. | Nothing to add: AGENTS.md is read as it is. | Path-specific *.instructions.md files need an applyTo block, and on GitHub.com they currently work only for the Copilot cloud agent and code review.Source: GitHub: Docs: Adding repository custom instructions for GitHub Copilot |
| CursorCursor | .cursor/rules/*.mdc, and AGENTS.md | AGENTS.md in the project root and in sub-folders; nested files are combined, the more specific taking precedence. | Nothing to add: AGENTS.md is read as it is. | Rules in .cursor/rules must use the .mdc extension: a plain .md file there is ignored.Source: Cursor: Docs: Rules |
| Gemini CLIGoogle | GEMINI.md by default | ~/.gemini/GEMINI.md, then your workspace folders and their parents, then folders the CLI opens a file in. | .gemini/settings.json with context.fileName listing AGENTS.md (and GEMINI.md). | Without that setting Gemini CLI looks only for GEMINI.md, so an AGENTS.md on its own is not read.Source: Google: Gemini CLI documentation: GEMINI.md context files |
| AiderAider | Any conventions file you load: /read AGENTS.md, aider --read AGENTS.md, or read: in .aider.conf.yml | Wherever you point it. Files loaded this way are read-only in the chat. | .aider.conf.yml with the line read: AGENTS.md loads it in every session. | Loading it with /read or --read (not /add) keeps it read-only, and it is cached when prompt caching is on.Source: Aider: Docs: Specifying coding conventions |
Why one file
Copies drift. When the rules live in five files, one of them is always out of date and the agents start disagreeing. Keeping a single AGENTS.md and pointing the other agents at it means one edit changes what every agent reads.
The AGENTS.md project describes the format as “a simple, open format for guiding coding agents”, stewarded by the Agentic AI Foundation under the Linux Foundation. Its page lists support from Codex, Jules, Gemini CLI, Devin, Windsurf, Junie, the GitHub Copilot coding agent, Aider, Zed, Warp, VS Code, Cursor and others. Source: AGENTS.md project: AGENTS.md: a simple, open format for guiding coding agents.
Nested files
Large repositories can keep an AGENTS.md inside a sub-project. Codex, Copilot and Cursor all read the nearest one to the work, and Codex and Cursor combine it with the ones above it, the more specific coming last. Keep the root file for project-wide rules, and a short one per sub-project for its own commands.