One AGENTS.md for Every Coding Agent You Use

If you run Claude Code next to Codex or Cursor, you probably keep two or three instruction files that say almost the same thing, and by now they disagree about at least one command. That drift just got easier to fix. In a post on X, @trq212 announced: “We’re adding support for AGENTS.md to Claude Code. Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md. You can toggle this behavior in /config.”

Claude Code has always wanted its own file. Now it will read the shared one. In this post you will learn exactly when Claude reads AGENTS.md (and the quiet ways it won’t), how to fold an existing CLAUDE.md into one shared file, what belongs at the root versus in subfolders, what to keep out entirely, and how to prove each agent actually loaded it.

What actually changed in Claude Code

The tweet is short. The Claude Code memory docs fill in the details that matter. By default, Claude reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. It is a fallback, not a merge. If both files exist, Claude reads CLAUDE.md and ignores AGENTS.md.

Your personal ~/.claude/CLAUDE.md, an organization’s managed CLAUDE.md and files in .claude/rules/ do not count for that check, so they keep loading alongside AGENTS.md. The toggle in /config is a setting called Project instructions. The default reads CLAUDE.md or AGENTS.md. You can also have Claude read both together, CLAUDE.md only, or only your organization’s managed instructions.

Three catches the tweet leaves out. First, some sessions cannot read AGENTS.md directly at all: the docs list Amazon Bedrock and other third-party providers, sessions with telemetry disabled, and the first session right after you upgrade. In those, Project instructions does not even appear in /config. Second, a CLAUDE.local.md counts as a CLAUDE.md, so adding one for personal notes quietly switches the fallback off. Third, Claude skips AGENTS.local.md, AGENTS.override.md and anything under an .agents/ folder. If another tool on your team relies on those, Claude will not see them.

Why one shared file is worth the migration

The case for AGENTS.md is boring, which is the point. The agents.md site calls it a README for agents: plain markdown, no required fields, one predictable place for build commands, conventions and gotchas. Its list of tools that read it includes Codex, Cursor, Gemini CLI, GitHub Copilot’s coding agent, Jules, Aider, Windsurf and Zed, among others.

When every agent reads the same file, you fix a wrong test command once. When each agent has its own file, you fix it in one, forget the other, and lose an afternoon wondering why a different agent keeps running the old script.

Be skeptical of the word “standard”, though. The format is shared. The loading rules are not. Codex walks from your Git root down to the directory you launched it in, combines every file it finds with the closer ones appearing later, and stops adding files once the total hits a default cap of 32 KiB. Cursor supports AGENTS.md at the root and in subdirectories, combining nested files with their parents and letting the more specific one win. Claude Code treats AGENTS.md as a fallback unless you change the setting. Same file, three slightly different readers. Write it so it survives all of them: short, flat, and not dependent on which file a tool happens to read last.

Consolidate CLAUDE.md and AGENTS.md in five steps

If you already have both files, do it in this order:

1. Inventory. List every instruction file in the repo and its parent folders: CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, AGENTS.md, .cursor/rules. A forgotten CLAUDE.md one level up hides AGENTS.md from Claude.
2. Merge into AGENTS.md. Move the shared material over: commands, layout, conventions. Delete duplicates instead of reconciling wording. Where two versions disagree, keep the one CI actually runs.
3. Set aside the Claude-only lines. Anything only Claude Code understands, like plan mode for a sensitive folder, stays out of the shared file.
4. Turn CLAUDE.md into a shim. First line: an @AGENTS.md import. Below it, a “Claude Code” heading with the lines you set aside. Claude reads the import first, then the rest, and never loads AGENTS.md twice.
5. Commit, then test. See the last section.

Why keep a CLAUDE.md when Claude now falls back on its own? The shim also works in sessions that cannot read AGENTS.md directly (older versions, Bedrock, telemetry off, the first run after an upgrade). It shows up under Memory files in /context, and it makes the CLAUDE.local.md trap irrelevant. My take: the fallback is great for repos you clone. For repos you own, the import is sturdier.

A CLAUDE.md symlinked to AGENTS.md also works, but the Claude docs flag two catches: the Edit and Write tools refuse to write through a symlink, and Git on Windows can check a committed symlink out as a one-line text file. If anyone on your team uses Windows, use the import.

What belongs in the root file, and what to keep out

The root AGENTS.md loads in every session of every tool, so every line competes for attention on every task. Anthropic’s guidance is to target under 200 lines per CLAUDE.md, and the same logic applies to a file several agents share. Keep it to facts an agent needs all the time:

• Exact install, build, test and lint commands.
• Where things live: which folder holds API handlers, which holds UI, which is generated.
• Conventions a reviewer would bounce a PR for, written so they can be checked. “Run the test suite before committing” beats “test your changes”.
• Hard boundaries: files never to edit by hand, migrations that need a human, folders that are off limits.

Keep these out:

• Secrets, tokens and internal URLs. The file is committed and read by tools from several vendors.
• Personal preferences. Those belong in your user-level file (~/.claude/CLAUDE.md for Claude, ~/.codex/AGENTS.md for Codex), not the repo.
• Long procedures. A ten-step release checklist belongs in a skill or a doc the agent loads on demand.
• Anything a linter or formatter already enforces. Let the tool do it.
• Rules that must never be broken. Instructions are context, not configuration, and the Claude docs say plainly there is no guarantee of strict compliance. If something has to happen before every commit, make it a hook or a CI check.

Push everything else down the tree

The fix for a bloated root file is not a better organized bloated root file. It is loading less. Gábor Mészáros at Reporails calls this progressive disclosure and splits it into three controls: what loads (a procedure packaged as a skill the agent pulls in when needed), where it loads (a rule that governs the payments code lives next to the payments code), and when it loads (tie a rule to a moment, like session start). His image sticks: with a hundred always-on rules, the one that matters for this turn is “a single voice in a crowded room, shouting over ninety-nine others.”

AGENTS.md handles the where part natively. Put a short AGENTS.md in each package or app folder that has its own commands or conventions. agents.md says agents read the nearest file in the directory tree and the closest one takes precedence. Claude Code loads a subdirectory’s AGENTS.md when it opens a file there, as long as that folder has no CLAUDE.md of its own. Codex’s docs describe a chain from the Git root down to your working directory, so launch it inside the package when that package’s file matters.

Two rules for nested files. Make each one self-contained for its folder. And never contradict the parent silently: if a subfolder uses a different test runner, say so explicitly. Claude’s docs warn that when two rules conflict, it may pick one arbitrarily. Tool-specific scoping (path-matched .claude/rules/ files, Cursor’s .cursor/rules) is fine for genuinely tool-specific material.

Prove each agent actually read it

Never assume an instruction file loaded. Check each tool after every restructure.

Claude Code. When it reads AGENTS.md directly, an interactive session shows a line like “no CLAUDE.md found; AGENTS.md loaded:” followed by the path. A directly read AGENTS.md does not appear in /memory or in the Memory files list in /context. With the import shim, CLAUDE.md does. If nothing shows up, run claude --version to confirm 2.1.277 or later, look for a CLAUDE.md or CLAUDE.local.md on the path, and open /config to check Project instructions. If that setting is missing, your session is one that cannot load AGENTS.md directly, and the shim is your answer.

Codex. Its docs suggest prompts like “Show which instruction files are active.” Run it from the repo root and again from a subfolder, and compare.

Any agent. Plant a canary. Add a harmless line to the root file, such as a made-up project codename, start a fresh session and ask for the codename without mentioning any file. If the agent answers without opening anything, the file was in its context. If it reaches for a file-read tool first, it is reading on demand, which is not the same thing. Delete the canary afterwards, or keep it as a cheap regression test for the next time someone reshuffles the repo.

Practical takeaways

• Make AGENTS.md the single source of truth. Every other instruction file points to it instead of repeating it.
• Keep a small CLAUDE.md that imports @AGENTS.md and holds only Claude-specific lines. It works in every Claude Code session, including ones that cannot read AGENTS.md directly.
• Search the whole path, parent folders included, for stray CLAUDE.md or CLAUDE.local.md files. Either one switches the fallback off.
• Keep the root file short and checkable. Anthropic’s guidance for CLAUDE.md is under 200 lines, and less is better when several agents share it.
• Move folder-specific rules into nested AGENTS.md files and multi-step procedures into skills.
• Never put secrets or personal preferences in a file every vendor’s agent reads.
• If Claude Code is in your mix, do not rely on AGENTS.override.md or AGENTS.local.md. Claude ignores them.
• Use hooks or CI for anything that must happen. Instructions are advice.
• Verify with a canary after every restructure, in every tool you use.

One file, fewer surprises

AGENTS.md is not magic. It is a markdown file with a good name and broad adoption. The win is that you stop maintaining parallel copies of the same knowledge, and Claude Code no longer forces you to. Spend half an hour consolidating, plant a canary, and your agents will at least be working from the same page.

Want a practical brief like this every week? Subscribe to the HelloBuilder newsletter at read.hellobuilder.ai.