AGENTS.md vs CLAUDE.md: which file each coding agent reads

AGENTS.md vs CLAUDE.md now comes down to which file wins in each tool. Claude Code 2.1.277, released on 18 September 2026, reads AGENTS.md in a folder that has no CLAUDE.md, and by default still reads only CLAUDE.md when both exist.¹² Codex, Cursor, GitHub Copilot, Amp and Zed’s agent all read AGENTS.md, and Gemini CLI reads it once you name it in its settings. For a repository with both files, the fix is one line. Keep the shared instructions in AGENTS.md and start CLAUDE.md with @AGENTS.md.

A personal CLAUDE.local.md switches Claude Code’s fallback off for whoever adds one, and the setting that loads both files only works from user or managed settings. A third-party count from 24 September found a CLAUDE.md beside the AGENTS.md in 161 of 283 popular repositories that ship one.³

This post covers the fix, Claude Code’s rules, a compatibility table for seven agents, what to put in the file, a template and a checklist. Sources are vendor documentation and changelogs dated on or before 20 October 2026, and we haven’t run tests of our own.

The one-line fix for repositories with both files

Make AGENTS.md the file every tool shares, and give Claude Code a CLAUDE.md that imports it.

@AGENTS.md

## Claude Code only
- Use plan mode before changing anything under `db/migrations/`.

Anthropic documents this pattern. Claude reads the imported file first, then the rest of CLAUDE.md. Relative paths resolve from the importing file, imports can nest four hops deep, and an @path inside backticks or a code block isn’t imported. The import never makes Claude read AGENTS.md twice, and it works on versions and providers that can’t load AGENTS.md directly.² Keep the Claude-only lines short, because Cursor applies a root CLAUDE.md to every conversation as well.⁴

A symlink, ln -s AGENTS.md CLAUDE.md, works when Claude needs nothing extra, with two constraints that Anthropic lists. Claude’s Edit and Write tools won’t write through a symlink. On Windows, creating one needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, so that clone gets a one-line CLAUDE.md holding a path.² Git’s own docs confirm the plain-file checkout.⁵ If anyone on the team or in CI uses Windows, use the import.

Monorepos need one more step. Anthropic’s docs describe Claude loading a subfolder’s AGENTS.md only when no CLAUDE.md counts, and a root CLAUDE.md with the import counts.² Either add a CLAUDE.md containing @AGENTS.md beside each nested AGENTS.md, or delete CLAUDE.md and move the Claude-only lines into .claude/rules/, which doesn’t count. The second route relies on the fallback, so every machine needs a version that supports it on your provider.

How Claude Code reads AGENTS.md since version 2.1.277

Thariq Shihipar announced the change for the Claude Code team on 18 September, as quoted by Simon Willison. From version 2.1.277, when a folder has no CLAUDE.md, “Claude will check for and use AGENTS.md”.⁶¹ Anthropic’s docs list which files switch that fallback off.²

• Counted, so AGENTS.md is skipped: CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it.
• Not counted, and loaded alongside AGENTS.md: your ~/.claude/CLAUDE.md, your organisation’s managed CLAUDE.md and .claude/rules/ files.
• Never read: AGENTS.local.md, AGENTS.override.md and anything under .agents/.

CLAUDE.local.md is meant for personal, gitignored notes, but Anthropic warns that adding one to a project that relies on AGENTS.md stops Claude reading AGENTS.md for that developer. To keep one, Anthropic suggests the claude-md-and-agents-md setting below.

With the fallback active, Claude reads every AGENTS.md from the working directory upwards at the start of a session. It reads a subfolder’s AGENTS.md when it opens a file there, unless that subfolder has a CLAUDE.md of its own.²

The Project instructions setting in /config has four values.²

Teams can’t commit this setting. Claude Code reads it from user settings, a --settings file or managed settings, and ignores it in project and local settings files. An administrator who wants one behaviour for everyone sets it in managed settings, under pluginConfigs for cc-plugin-agents-md@builtin.²

Cloud providers followed five days later. The 2.1.277 release notes said the fallback was “not yet on Bedrock, Vertex or Foundry”.⁷ Version 2.1.281, released on 23 September, extended it to Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry disabled.¹⁸ On older versions those sessions read CLAUDE.md only, so check the versions pinned in CI images and dev containers.

An interactive session confirms the fallback with a line starting no CLAUDE.md found; AGENTS.md loaded:. From version 2.1.280, /memory and /context also list an AGENTS.md that Claude read directly.²

AGENTS.md vs CLAUDE.md across seven coding agents

This table summarises each vendor’s documentation as of 20 October 2026. “Not documented” means the vendor’s page doesn’t say.

Sources are each vendor’s documentation, and GitHub’s changelog for the cloud agent’s name.^{2910411121314151617}

Claude Code prefers CLAUDE.md, Amp and Zed prefer AGENTS.md, and Copilot in VS Code combines both, so if the two files disagree, the agents get different instructions. With the import in place, they all read the same text. Zed’s agent stops at its first match, so a forgotten .cursorrules or a stub .github/copilot-instructions.md hides AGENTS.md entirely.¹⁶ Codex reads CLAUDE.md only if you list it in project_doc_fallback_filenames, and then only in folders without an AGENTS.md.⁹

Since 18 June 2026, Gemini CLI no longer serves Google AI Pro and Ultra subscribers or free Gemini Code Assist users, who move to Antigravity CLI. Code Assist Standard and Enterprise customers and paid API keys keep Gemini CLI.¹⁸ Antigravity reads AGENTS.md or GEMINI.md in any folder and truncates a rule file over 24,000 bytes.¹⁹

How many repositories have both files

Decoding AI, writing on Towards AI on 24 September, measured how often the fallback can fire. It took the top 100 repositories by stars in ten languages from the Github-Ranking project, kept the 815 with a commit in the previous 90 days, and fetched each default branch’s instruction files.³

Of the 815, 283 (34.7%) ship an AGENTS.md. In 161 of those 283 (56.9%), a root CLAUDE.md or a .claude/CLAUDE.md sits beside it, so Claude Code’s default never falls back to AGENTS.md. The other 122 (43.1%) are where version 2.1.277 changed anything. A first pass that checked only the root found 157.³

This is a third-party snapshot of the most-starred projects. The author counted files without running Claude Code and notes that gitignored CLAUDE.local.md files are invisible, which makes 161 a floor. The article doesn’t say whether those CLAUDE.md files import or link to AGENTS.md, and one that does still gives Claude the AGENTS.md content, so 161 counts the repositories where the fallback can’t fire.

How to write AGENTS.md: what belongs in it

Anthropic, OpenAI and the agents.md site agree on the core.

• Commands the agent can’t guess. Install, build, a single test, the full suite, lint and type checks. All three sources list them.²⁰²¹²²
• A few lines on layout. OpenAI asks for the important directories. Anthropic excludes file-by-file descriptions, and its /doctor check proposes cutting directory layouts Claude can work out, so name the folders that aren’t obvious and skip the tree.²¹²²²
• Conventions that differ from defaults. Anthropic asks for code style rules that differ from defaults, plus branch naming and PR conventions. OpenAI asks for engineering conventions and PR expectations.²²²¹
• Boundaries. OpenAI lists “constraints and do-not rules”, and its sample file asks for confirmation before new production dependencies are added.²¹⁹ “Ask before running a migration” goes here. The file is advice, so Anthropic says to block anything that must never happen with a hook or a permission rule.²
• What done means. OpenAI lists “what done means and how to verify work”. The agents.md FAQ says an agent will try to run the checks the file lists and fix failures before it finishes.²¹²⁰

Write lines a reviewer can check. Anthropic’s example prefers “Run npm test before committing” to “Test your changes”.² Keep the file short. OpenAI says a short, accurate AGENTS.md is more useful than a long file of vague rules, and Anthropic suggests under 200 lines. Both, like Cursor, suggest adding a rule when the agent repeats a mistake.²¹²¹⁰

What to keep out of AGENTS.md

• Secrets. The file is committed, and each tool sends it to a model provider in every session. Gemini CLI, for example, sends its context files with every prompt.¹⁵² Point the agent to .env.example and keep values out.
• Long documents the agent can open itself. Anthropic, OpenAI and Cursor all say to link or reference documentation instead of pasting it.²²²¹¹⁰ In Claude Code an @ import still loads at launch, so write the path in backticks and Claude opens the file when it needs it.²
• Rules a linter or test already enforces. VS Code says to skip conventions that linters and formatters enforce, OpenAI to reserve formatting and lint checks for CI, and Cursor to use a linter instead of copying a style guide.¹⁴⁹¹⁰ Keep the lint command in AGENTS.md and the rule in the linter’s config, where it can fail a build.

Cursor rules, copilot-instructions.md and GEMINI.md

Cursor rules vs AGENTS.md

Cursor reads AGENTS.md in the root and in subfolders, so always-on rules can move there.¹⁰ Keep .cursor/rules/*.mdc files for rules that need a glob or a manual trigger, which is the extra control Cursor says project rules are for.⁴ Delete .cursorrules. Cursor calls it legacy, and Zed reads it before AGENTS.md.⁴¹⁶ Our post on Cursor alternatives has a fuller checklist for moving rules between tools.

copilot-instructions.md

Copilot reads AGENTS.md too, and it gets every instruction file that applies, so text kept in both is sent twice.¹¹ Move the shared text into AGENTS.md and keep .github/copilot-instructions.md for Copilot-only notes, or delete it, remembering that Zed reads it ahead of AGENTS.md.¹⁶ Path-specific .instructions.md files with applyTo globs can stay, since AGENTS.md has no glob scoping.¹¹

GEMINI.md

Move the shared text into AGENTS.md and tell Gemini CLI to read both files in .gemini/settings.json.¹⁵²³

{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

With folder trust on, Gemini CLI ignores a project’s .gemini/settings.json until the folder is trusted.²⁴ Antigravity reads both files without a setting.¹⁹

An AGENTS.md template to start from

This AGENTS.md example suits a repository with a TypeScript front end and a Python API. Swap in your own commands, and delete any line your agents wouldn’t miss. At 40 lines it sits well inside every limit in the table.

# AGENTS.md

Web app in `apps/web` (Next.js) and API in `services/api` (FastAPI).

## Commands
- Install: `pnpm install` and `uv sync --project services/api`
- Run locally: `pnpm dev`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- API tests: `uv run --project services/api pytest -q`
- Before you finish: `pnpm lint && pnpm typecheck`

## Layout
- Shared UI components live in `packages/ui/`, never inside the app
- API endpoints: `services/api/app/routers/`; schemas: `services/api/app/schemas/`
- `db/migrations/` is generated. Never edit an existing migration.
- `services/api/AGENTS.md` adds API-only rules

## Conventions
- TypeScript strict mode. No `any` without a comment saying why.
- API errors use the helpers in `services/api/app/errors.py`
- Branches are `type/short-description`; one logical change per PR

## Ask before you
- Create or run a database migration
- Add, remove or upgrade a dependency
- Change CI workflows or anything under `infra/`
- Delete a file you didn't create in this task

## Never
- Commit `.env` files or secrets. Add new variables to `.env.example`.
- Skip, disable or loosen a test or lint rule to get a check passing

## Done means
- Lint, type checks and the tests for the code you touched pass
- New behaviour has a test
- The PR description says what changed and how you checked it

## Read when relevant
- Architecture decisions: `docs/adr/`
- API conventions: `docs/api.md`

In a monorepo, give each package a short AGENTS.md with only its own commands and rules. Cursor, Copilot cloud agent and Amp pick it up when they work in that folder, and Codex when you start it there.^1011179 For Claude Code, see the monorepo step in the fix above.

Treat AGENTS.md changes as code under review

Agents try to run the checks these files list, so editing one command changes what agents run.²⁰ Anthropic tells teams to treat CLAUDE.md like code, reviewing and pruning it and checking that a change actually shifts Claude’s behaviour.²² We’d put every instruction file through pull request review, the same as CI config.

• Give the files an owner. List them in CODEOWNERS and require that owner’s review. Our post on agent config files that run code has a CODEOWNERS block for these paths and covers the security side.
• Run the listed commands in CI. A renamed script then fails a build before an agent follows the stale line.
• Audit for drift. In Claude Code 2.1.283 or later, /doctor prompt-audit reports references to missing files or commands and contradictions across CLAUDE.md, CLAUDE.local.md and AGENTS.md files. It changes nothing until you ask.²

Checklist for one repository this week

1. Find every instruction file, subfolders included. Look for AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, GEMINI.md, .cursorrules, .cursor/rules/, .github/copilot-instructions.md and .github/instructions/, and ask developers about gitignored CLAUDE.local.md files.
2. Merge the shared content into AGENTS.md and delete the duplicates.
3. Start CLAUDE.md with @AGENTS.md, beside each nested AGENTS.md too, or replace CLAUDE.md with .claude/rules/ once every install runs 2.1.281 or later.
4. Clear out leftovers. Delete .cursorrules, trim copilot-instructions.md to Copilot-only notes and set context.fileName for Gemini CLI.
5. Cut the file down to commands, layout pointers, conventions, boundaries and a definition of done, in under 200 lines.
6. Back hard boundaries with permission rules or hooks.
7. Check what each tool loaded, using the last column of the table.
8. Add a code owner and a CI job that runs the commands the file lists.

Frequently asked questions