AGENTS.md vs CLAUDE.md
Which file should your coding agents read? See how Claude Code, Codex, Cursor and Copilot load instructions and how one import keeps team rules in sync.
Published

For a repository used by several coding agents, keep shared instructions in AGENTS.md. The AGENTS.md vs CLAUDE.md decision gets simpler with Claude Code v2.1.277: eligible sessions can read the shared file directly. If your team already uses CLAUDE.md, one import lets you keep both filenames and edit the test command in one place.
AGENTS.md vs CLAUDE.md: which file should you keep?
If your developers switch between OpenAI Codex, Cursor and Anthropic’s Claude Code, choose AGENTS.md. Put the build command, test command and repository conventions there. In a new project, start with that file alone. For a team with a mix of Claude versions, local preferences or Claude-specific instructions, commit a sibling CLAUDE.md containing @AGENTS.md. That’s the setup I’d choose for a shared repository where you don’t control every developer’s machine.
If everyone works in Claude Code, keep CLAUDE.md. A working set of team instructions, personal preferences and package rules is worth keeping. Move the shared content when another agent needs it. If GitHub Copilot drives the decision, identify where people use it. A pull request delegated to the cloud agent and a question typed into Chat on GitHub.com have different instruction support.
Verified against the format and vendor documentation on November 18, 2026. The deciding criteria are which file your tools discover, which directory’s instructions apply to a task, and how many places a reviewer must edit when a command changes.
Which tools read AGENTS.md?
AGENTS.md is an open convention for giving a coding agent the information a maintainer would otherwise repeat in chat. It has no mandatory headings. A root file can be as small as the command that reproduces CI locally and a note about which files the build generates. AGENTS.md wins on portability. The filename travels well. The rules for finding it vary by tool.
OpenAI Codex builds its instruction chain before it starts work. It checks its home directory, normally ~/.codex, then walks from the project root to its current working directory. At each project level it takes at most one file, trying AGENTS.override.md before AGENTS.md, then any configured fallback names. More local guidance appears later. If a service has its own test command, starting Codex in that service directory puts its file on the startup path. Starting at the root gives a different chain. OpenAI’s instruction discovery guide
Cursor supports the root file and nested AGENTS.md files that apply to their directories and descendants. If the whole team needs a convention for a frontend package, a nested file can express it in ordinary Markdown. Use Cursor’s structured project rules when you need Cursor-specific matching or metadata. Cursor’s rules documentation
GitHub Copilot has separate readers. On GitHub.com, its cloud agent and code review support both filenames. For Chat on GitHub.com, the documented repository-wide file is .github/copilot-instructions.md. Copilot Chat in Visual Studio Code lists AGENTS.md. If someone says “Copilot ignored our file,” ask where they opened the chat before changing the repository. GitHub’s support matrix · Visual Studio Code’s project instruction guide
Which other agents can use the shared file?
For a repository that several agents visit, keep the directions everyone needs in the root file. Add a package exception only after checking the reader that needs it.
- Root discovery. Google Jules looks in the repository root. Kilo Code and Roo Code document root files too. JetBrains Junie CLI checks
.junie/AGENTS.mdfirst, so look there if a change to the root appears to have no effect. Jules setup · Kilo’s file guide · Roo’s instruction guide · Junie’s discovery order - Directory-specific guidance. Factory Droid and Ona document nested files. Amp adds subtree guidance when it reads a file there. Warp automatically applies its root and current-directory rules. Augment Code discovers both filenames along the path to the file being worked on. Factory’s project guide · Ona’s codebase guide · Amp’s discovery rules · Warp’s project rules · Augment’s hierarchy
- Other documented readers. Zed Agent uses
AGENTS.mdas its primary instruction file. OpenCode uses it for persistent project guidance. goose checks for bothAGENTS.mdand.goosehintsby default. Phoenix.new’s maintainer identifies/workspace/AGENTS.mdas its project file. Zed’s instruction reference · OpenCode’s instructions · goose’s context files · Phoenix.new maintainer’s usage note - Readers you can configure. In Aider, set
read: AGENTS.mdin.aider.conf.ymlto load it as read-only context. In Google Gemini CLI, includeAGENTS.mdincontext.fileNamein settings. A team adopting either tool should review that configuration alongside the shared file. Aider’s conventions setup · Gemini CLI’s context settings
The directory also lists Devin, Windsurf, UiPath and Semgrep. Windsurf’s linked documentation now leads to Devin Local, which reads project rules from the workspace root down to the working directory. UiPath documents generating both instruction files during project initialization. That tells you what will appear in the repository. It leaves the read order open. For Semgrep, the directory listing alone gives no basis for relying on startup or nested-file behavior. Devin Local’s customization guide · UiPath’s generated files
CLAUDE.md vs AGENTS.md in a Claude Code session
CLAUDE.md wins when you need Claude-specific control over what loads. It holds instructions you write for Claude Code. Your organization can supply managed instructions, ~/.claude/CLAUDE.md holds your preferences across projects, and the repository’s CLAUDE.md or .claude/CLAUDE.md holds team guidance. A gitignored CLAUDE.local.md holds preferences for your checkout. Auto memory is a separate feature where Claude writes its own notes. Anthropic’s memory guide
Claude adds the applicable instructions to the session in order. Along the path from ancestor directories to the launch directory, the closer file comes later. Within a directory, local instructions follow project instructions. Both texts remain in context, so resolve contradictory test commands in the files themselves. Below the launch directory, Claude discovers more specific instructions on demand.
The default direct-read rule has a condition. With the built-in reader available, Claude looks for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the launch directory or any ancestor. If it finds one, it selects the Claude files. Otherwise it can load AGENTS.md directly. Managed instructions, your user-level ~/.claude/CLAUDE.md and .claude/rules/ can still load alongside the shared file. Anthropic’s file selection rules

Imagine two developers on the same commit. One has added an untracked CLAUDE.local.md for a preferred test fixture. The other has a clean checkout. Direct loading can give them different project context. A committed import gives both a path to the shared instructions in an ordinary project session. An organization using the managed-only setting excludes repository instructions at launch, including imports from a project file. A developer who wants both files loaded directly can also select claude-md-and-agents-md under Project instructions in /config. For version checks and session diagnostics, see how to make Claude Code read AGENTS.md.
There is another reason to keep the import even on a current version. If your tooling uses Anthropic’s InstructionsLoaded hook, an event fired when instructions load, a directly discovered AGENTS.md does not fire it. Loading the same content through a CLAUDE.md import or symlink does. That distinction matters if your team uses the event to record which rules a session received. Anthropic’s hook and loading differences
How to keep both filenames without copying the rules
Use the import for a mixed team. Put the shared text in the root AGENTS.md and the following single line in the adjacent CLAUDE.md. Write it as ordinary file content, outside a code block in the file itself. Anthropic’s shared-file recipe
@AGENTS.mdClaude expands the import when it loads project instructions. Add Claude-only directions underneath it. Relative paths start at the importing file, so the equivalent line inside .claude/CLAUDE.md is @../AGENTS.md. Keeping both files at the root makes their relationship easier to see in a pull request.

A pointer file is a request to open the source. The following is valid prose for CLAUDE.md. It keeps the command in one place, but Claude must decide to open the other file. The mere presence of the pointer can also suppress default direct loading. Replace a pointer like this with the import if the build instructions must be available at startup. Anthropic’s guidance on prose pointers
Read AGENTS.md before making changes to this repository.Use a symlink when both names should expose exactly the same text. A symlink is a filesystem entry pointing to another file. From the repository root, with the shared file in place and the destination name available, run the following command. It follows the format project’s documented migration pattern.
ln -s AGENTS.md CLAUDE.mdEdit the target, AGENTS.md. A symlink leaves nowhere to append a Claude-only rule without sharing it with everyone. On Windows, a clone with Git symlink support disabled can contain a plain file holding the target’s name. Choose the import if contributors work across operating systems.
What to move when you switch
Move instructions according to who needs them. If a clean checkout requires a particular bootstrap command, every agent needs it. If your repository uses Claude-specific rule files or hooks, leave those directions on the Claude side. For an existing Claude-only setup, the team memory guide covers how to organize that layer.
CLAUDE.md file best practices for a shared repository
Read your existing files side by side. For each build or test command, compare it with the repository’s scripts and the job CI runs. Resolve stale variants before moving the surviving line into AGENTS.md. Keep package exceptions beside the package when the relevant agents support that scope. In the same change, replace copied shared text in the Claude file with the import. Simply renaming a file can strand a developer who launches an older Claude session.
A useful rule names a decision the reader could get wrong. For a project that generates its API client, “Edit the schema, then regenerate the client with the repository’s generation script” tells the agent where to make the change. Include the actual script name for your project. “Write clean code” gives a reviewer nothing to check. Keep onboarding history in the README, long procedures in their own docs and credentials outside committed files. Put mandatory checks in CI or permissions. A line of Markdown gives the agent context, while a failing check can block the merge.
Before retiring an old file, open a fresh session from the directory people normally use. In current Claude Code, run /memory and look for the expected path. For a directly loaded AGENTS.md, that listing requires v2.1.280 or later. In Codex, start in the package and ask which instruction files and test command apply. Repeat from the root if people launch there too. A change is ready when the documented paths explain what each developer sees.
Frequently asked questions
Does CLAUDE follow Agents MD?
Claude Code can read AGENTS.md directly from v2.1.277 when the built-in reader is available and the project settings and file layout allow it. If a project or local Claude instruction file takes precedence, import the shared file or enable loading both. Check which file loaded before diagnosing the quality of the instructions.
Can you provide an example of an agent.md file?
For the shared convention, name the file AGENTS.md, plural. In a project with a working pnpm test script and a generated API client, a useful entry would be “Run pnpm test from the repository root. Change the API schema before regenerating the client.” Substitute your repository’s actual command and source paths.
Does Claude look at AGENTS.md?
To check a particular session, open /memory and look for the file path. If it is missing on a current version, inspect the launch directory and its parents for a Claude project or local file, then check Project instructions in /config. A developer’s local file can explain why the same commit behaves differently on another machine.
Get the AI Business Workflow Audit Checklist to map which parts of your coding workflow need a written instruction, an automated check or a human review.
- Published
- Category
- Build









