Humoud Al MunawerAR / EN

Founder note

AGENTS.md and CLAUDE.md: one instruction file for every coding agent

Claude Code now reads AGENTS.md, but only when no CLAUDE.md is in the way. A short setup that keeps every coding agent on the same instructions.

A repository that several coding agents work in tends to collect one instruction file per vendor: CLAUDE.md, Cursor rules, Copilot instructions, GEMINI.md. Each one starts as a copy of another. A few weeks later they disagree, and nobody can say which file is authoritative.

AGENTS.md is the open answer to that: one plain Markdown file at the repository root, read by OpenAI Codex, Cursor, the GitHub Copilot coding agent and many others, and now stewarded by the Agentic AI Foundation under the Linux Foundation. Since version 2.1.277, released on 18 September 2026, Claude Code reads it too.

What changed in Claude Code

In a project with no CLAUDE.md, Claude Code now reads AGENTS.md instead. The behaviour is controlled by the Project instructions setting in /config.

The first release had a gap: sessions on Amazon Bedrock, Google Vertex AI and Microsoft Foundry, and sessions with telemetry disabled, still read CLAUDE.md only. Version 2.1.281 (23 September 2026) closed it, and also covers LLM gateways. If your team runs Claude Code through a cloud provider, the fix is to update, not to wait.

The catch: CLAUDE.md still wins by default

By default Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. Keep a CLAUDE.md “just for overrides” without wiring it up, and Claude silently skips the shared file. A personal CLAUDE.local.md has the same effect.

Two setups keep one source of truth:

  1. Put @AGENTS.md on the first line of CLAUDE.md and add Claude-only instructions below it. Claude reads the shared file first, then the rest, and it never loads the same file twice.
  2. Or set Project instructions to claude-md-and-agents-md in /config, so both files load together.

If CLAUDE.md would hold nothing Claude-specific, delete it. A symlink to AGENTS.md also works, but avoid it if anyone clones the repository on Windows.

Three checks are enough

  1. Run claude --version. You need 2.1.277 or later, and 2.1.281 or later on Bedrock, Vertex AI, Foundry, a gateway, or with telemetry off.
  2. Run /memory and confirm the path to your AGENTS.md appears in the list.
  3. If any CLAUDE.md sits on the project path, confirm it imports @AGENTS.md.

Humoud’s take

Make AGENTS.md the root file. Treat CLAUDE.md as a thin layer: one import line plus the few rules only Claude needs, such as hooks or plan-mode habits. Rules duplicated across files are where drift starts, so delete the copies instead of keeping them in sync.

Do this week

  1. Open your main repository and list every instruction file: AGENTS.md, CLAUDE.md, CLAUDE.local.md, .cursor/rules, .github/copilot-instructions.md, GEMINI.md.
  2. Merge the shared rules into one AGENTS.md at the root.
  3. Cut CLAUDE.md down to @AGENTS.md plus Claude-specific lines, or remove it.
  4. Add one line to the README that names AGENTS.md as the source of truth.

Limits

This is hygiene, not a promise that every agent reads AGENTS.md the same way. Precedence differs by tool. Codex also reads AGENTS.override.md, which Claude Code ignores. Cursor and Copilot give the nearest nested AGENTS.md priority. Gemini CLI reads GEMINI.md unless you add AGENTS.md to its context.fileName setting. Check the tools you actually use.

Sources

Claude Code changelog (versions 2.1.277 and 2.1.281) and memory documentation; agents.md; OpenAI Codex AGENTS.md guide; Cursor rules documentation; GitHub Copilot repository instructions; Gemini CLI context files. Checked 6 October 2026.

Also see: Decision Models: when chat is the wrong layer · Meeting brain: a queryable decision log · Public work