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

AGENTS.md vs CLAUDE.md

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.

DecisionAGENTS.mdCLAUDE.md
Who reads it?Codex, Cursor and other coding agents. Claude Code has a conditional direct reader.Claude Code. GitHub also lists it for its cloud agent and GitHub.com code review.
Where does the shared file live?Start at the repository root.Project root or .claude/CLAUDE.md for Claude Code.
Can a package have its own rules?Yes. Discovery depends on the reader. Codex starts from the launch path. Cursor scopes nested rules to the directory tree.Yes. Claude loads ancestor instructions at launch and discovers files below the launch directory as it works.
Can it import another file?The format is plain Markdown. Import expansion belongs to the reader. Claude expands @path inside a directly loaded AGENTS.md.Claude expands @path relative to the file containing it.
How big should it be?Codex’s default combined instruction budget is 32 KiB. Leave room for package guidance.Anthropic recommends under 200 lines per file. Imported text still takes up context.

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.

AGENTS.md project site showing the shared instruction format and its adopters
AGENTS.md

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.

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

Anthropic documentation for Claude Code project instructions and memory
Claude Code

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

A library selector points to CLAUDE.md and an alternative passage leads to AGENTS.md
Under Claude’s default setting, even a checkout-local Claude instruction file can change which route the session takes.

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

Markdown
@AGENTS.md

Claude 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.

Separate copies of a book beside two reading windows onto one shared volume
A reviewer changes the test command in AGENTS.md. Direct readers and Claude’s import then use the same text.

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

Markdown
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.

Bash
ln -s AGENTS.md CLAUDE.md

Edit 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
Related Articles
Thunkable Review

Thunkable Review

Can one Thunkable app serve your business on iOS and Android? Compare its blocks, data connections, publishing plans and limits on team editing.Nov 18, 2026Build
LLM Wiki: Build a Knowledge Base Your AI Maintains

LLM Wiki: Build a Knowledge Base Your AI Maintains

Set up an LLM wiki in a folder of Markdown files. Follow one team decision from source memo to cited answer, then update it when the decision changes.Nov 18, 2026Build
Codex Alternatives in 2026: Claude Code, Cursor, GitHub Copilot and 5 More

Codex Alternatives in 2026: Claude Code, Cursor, GitHub Copilot and 5 More

Compare eight Codex alternatives by model, editor, billing and team controls. See when to switch agents and when to keep Codex.Nov 18, 2026Build
Paperclip Alternatives in 2026: OpenClaw, Hermes Agent, CrewAI, LangGraph, AutoGen and Vibe Kanban

Paperclip Alternatives in 2026: OpenClaw, Hermes Agent, CrewAI, LangGraph, AutoGen and Vibe Kanban

Compare six Paperclip alternatives by who directs the agents, what each tool costs, and whether you need a runtime, a workflow framework or a code review board.Nov 17, 2026Build
Docker Desktop Pricing: Who Pays and Which Plan Fits

Docker Desktop Pricing: Who Pays and Which Plan Fits

Docker Desktop prices, the exact free-use rule, and yearly bills for 5, 40 and 300 users. Compare plans, billing limits and free alternatives.Nov 17, 2026Build
Tailscale vs WireGuard

Tailscale vs WireGuard

Compare Tailscale and WireGuard for servers, remote dev machines and team laptops. Choose based on setup, access control and ongoing upkeep.Nov 17, 2026Build
Sentry Pricing: Plans, Usage Rates and Three Monthly Bills

Sentry Pricing: Plans, Usage Rates and Three Monthly Bills

Sentry plans, usage quotas and overage rates explained, with three worked monthly bills and the announced Seer billing change.Nov 17, 2026Build
T3 Code: Run Coding Agents From One Workspace

T3 Code: Run Coding Agents From One Workspace

Run coding agents in one workspace with T3 Code. Set up providers, isolate tasks with worktrees, connect your phone and understand nightly customization.Nov 16, 2026Build
Newsletter

One letter, every Sunday.Working systems, not hot takes.

Weekly. No spam. Unsubscribe anytime.