One instruction file for every coding agent in your repo

If you use more than one coding agent, your repository probably has more than one instruction file. CLAUDE.md for Claude Code. AGENTS.md for Codex, Cursor and the rest. They start as copies, then drift, and one day an agent runs a build command you removed a month ago.

Last week that got easier to fix.

What changed

Claude Code 2.1.277, released September 18 according to DevOps.com, reads a project’s AGENTS.md when there is no CLAUDE.md. By default, the rule is one or the other, not both:

• If there is no CLAUDE.md in the working directory or any directory above it, Claude Code reads AGENTS.md.
• If both exist, it reads CLAUDE.md and ignores AGENTS.md.
• If your CLAUDE.md imports AGENTS.md, the import still works.

A “Project instructions” setting in /config changes that. The default is claude-md-or-agents-md. claude-md-and-agents-md loads both, CLAUDE.md first. claude-md ignores AGENTS.md, and managed-only loads only the organization’s managed CLAUDE.md and auto memory.

AGENTS.md is not one vendor’s format. DevOps.com notes that OpenAI contributed it to the Agentic AI Foundation, part of the Linux Foundation, in December 2025, and that the AGENTS.md site counts more than 60,000 open-source projects using it and more than 30 compatible tools.

The catches

The fallback is narrower than the file name suggests. Read these before you delete a symlink.

1. Parent folders count. DevelopersIO points out that CLAUDE.md is searched in parent directories as well. A CLAUDE.md higher up (in a monorepo root, or a folder above your checkout) stops AGENTS.md from loading below it.
2. CLAUDE.local.md counts as a CLAUDE.md. Per DevOps.com, a personal CLAUDE.local.md is enough to switch the fallback off. The documented fix is the claude-md-and-agents-md setting.
3. Not everywhere yet. The changelog says it is not on Bedrock, Vertex or Foundry. Sessions that do not fetch feature flags, including ones with telemetry disabled, cannot read it, and neither can the first session after an install or upgrade. Fresh CI runners are exactly that case.
4. Less visible. An AGENTS.md loaded through the setting does not show in /memory or in the memory files list in /context, and InstructionsLoaded hooks do not fire for it. They do fire when a CLAUDE.md imports it or symlinks to it.
5. Only the main file. Claude Code does not read AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory.

A decision rule for a team of one

Pick one of three setups, in this order:

• One AGENTS.md, no CLAUDE.md. Use this when you work locally with a normal install, keep no CLAUDE.md anywhere above the repo, and do not rely on hooks to audit what loaded.
• AGENTS.md plus a one-line CLAUDE.md that imports it. Use this if any catch above applies: CI runners, Bedrock, Vertex or Foundry, a parent CLAUDE.md, or hooks you watch. DevOps.com says the docs tell you to import AGENTS.md from a CLAUDE.md when a session cannot read the fallback, including sessions that do not fetch feature flags and the first session after an install or upgrade. Hooks fire for an imported or symlinked file, and the content still lives in one file.
• Keep both, on purpose. Use this only when Claude Code genuinely needs instructions no other agent should see. Put those in CLAUDE.md, set claude-md-and-agents-md, and keep everything shared in AGENTS.md.

For most solo engineers the second setup is the safe default. It costs one line and removes the guessing.

What belongs in the shared file

A merged file is only useful if every agent can act on it. A checklist for AGENTS.md:

• The exact commands to install, build, test, lint and type-check, copied from CI so they cannot drift.
• What “done” means: tests pass, types check, no new warnings, a short summary in the pull request.
• Commands the agent must never run: production deploys, destructive migrations, anything touching secrets.
• Where tests live, and the rule that behavior changes come with a test.
• The house style an agent cannot infer from the code: naming, error handling, which libraries are preferred or banned.
• Nothing tool-specific. If a line only makes sense to one agent, it belongs in that agent’s own file.

Then treat the file like code. It tells an autonomous agent what it may run in your repository, so changes to it go through review like any other change that affects the build.

What to do this week

1. Search your repo and the folders above it for CLAUDE.md, CLAUDE.local.md and AGENTS.md. Write down which ones exist and where.
2. Diff your CLAUDE.md against your AGENTS.md. Move everything shared into AGENTS.md and fix whatever has drifted.
3. Replace CLAUDE.md with a single line that imports AGENTS.md, unless you truly need tool-specific rules.
4. Run the checklist above against the merged file, and check the build and test commands in it against your CI config.
5. Start a fresh Claude Code session and ask it which build command it will use. If it answers from the old file, check your parent folders again.

One file will not make an agent careful. It does mean that when you fix an instruction, every agent in your repo gets the fix.