For operators running Claude Code alongside Codex, Cursor, Amp, or Aider — and tired of maintaining two instruction files
Independent operator field guide, updated 2026-06-03. MIT-licensed prose. ~3,000 words.
Claude Code reads CLAUDE.md, not AGENTS.md. That is stated verbatim in the
official memory docs(checked 2026-06-03). A claim circulating in several third-party guides — that Claude Code "reads AGENTS.md as a fallback when no CLAUDE.md exists" — is
not in the official documentation and does not match observed behavior. Don't rely on it.
The two methods Anthropic actually documents to make Claude Code use a repo's AGENTS.md
:
Import it from Put a one-line import at the top ofCLAUDE.md
(recommended — and the only option that works on Windows without extra privileges).CLAUDE.md
:Claude loads the imported file at session start, then appends any Claude-specific notes you add below it.
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Symlink, if you don't need Claude-specific content: On Windows a symlink needs Administrator privileges or Developer Mode, so prefer the
ln -s AGENTS.md CLAUDE.md
@AGENTS.md
import there.
(/init
in a repo that already has an AGENTS.md
also reads it and folds the relevant parts into the generated CLAUDE.md
.)
That one line solves the single most-requested feature in the tracker. The harder part is keeping the two files honest over months — that's what the five patterns below are for.
Feature request #6235 on anthropics/claude-code — "Support AGENTS.md" — has accumulated 5,200+ reactions and 300+ comments since 2025-08-21. It is, by a 4x margin, the largest unmet feature request in the entire Claude Code issue tracker. A related request, #31005, adds 220 more reactions. Across the tracker, 173 distinct issues mention AGENTS.md.
The shape of the ask:
Codex, Amp, Cursor, and others are converging on AGENTS.md (
[https://agents.md/]) — a unified Markdown file that coding agents use to understand a codebase. CLAUDE.md is too Claude-specific; it doesn't work when collaborating with developers who don't use Claude Code.
Anthropic has not committed to native support. As of 2026-05-26, the issue is open with no roadmap signal. This guide is the operator-side workaround set: five patterns that let Claude Code consume AGENTS.md without waiting for the harness layer to fix it.
If you're an individual developer juggling multiple AI tools, a team where some members use Claude Code and others use Codex/Cursor, or an open-source maintainer who wants one instruction file that works for every visitor's tooling — one of these patterns will fit your shape.
When Claude Code starts in a directory, it reads CLAUDE.md
(plus ~/.claude/CLAUDE.md
for global rules). When Codex starts, it reads AGENTS.md
. When Cursor starts, it reads .cursorrules
. When Amp starts, it reads AGENTS.md too (Amp converged from its own AGENT.md to the shared standard).
The pain shows up in three places:
Team friction. Your teammate uses Cursor. You use Claude Code. You both want to encode the project's testing conventions, security rules, and code style. You write CLAUDE.md. They write AGENTS.md. The two files drift. Someone forgets to update the other. Six weeks later, your pytest
setup and their vitest
setup disagree about how to mock the database — because the instruction files diverged.
Maintenance burn. You personally use Claude Code AND Codex (for the o1 access). You write the same project conventions twice. You forget to update one. The drift compounds across 20 repos.
Open-source unfriendliness. You maintain an open-source project. Contributors arrive using whatever AI tool they prefer. If your repo only has CLAUDE.md, Codex users get no guidance. If it only has AGENTS.md, Claude Code users get no guidance. If it has both, you maintain two copies of the same content.
The operator-side workarounds below address all three.
The 5,200+-reaction cluster maps to three operator shapes:
Persona A — Solo Developer, Multiple Tools. You use Claude Code as your primary, but occasionally switch to Codex (for o1) or Cursor (for the UI). You want one source of truth that all of them read.
Persona B — Mixed-Tool Team. Your team has 3-10 engineers. Some use Claude Code, some use Codex, some use Cursor. You want one shared instruction file that everyone's tool respects.
Persona C — Open-Source Maintainer. You maintain a public repo. You can't control what AI tool contributors use. You want one instruction file that gives consistent guidance regardless of tooling.
Before the five patterns below, there is one approach the official Claude Code docs now recommend as the default — the @AGENTS.md
import (Pattern 0). For most repos it is the right first choice; the five copy/duplicate-based patterns are alternatives for when the import does not fit. They scale up in operational overhead: Pattern 1 is the lightest, Pattern 5 the heaviest. Pick the smallest approach that fits your persona; only escalate if you outgrow it.
This is the method the official Claude Code memory docs now recommend, and for most repos it is the right default. Claude Code reads CLAUDE.md
, not AGENTS.md
— but a CLAUDE.md
can import your AGENTS.md
with a one-line directive, so there is only ever one real instruction file:
@AGENTS.md
## Claude Code
(optional: Claude-specific instructions, appended after the import)
Claude loads the imported AGENTS.md
at session start, then appends anything you write below it. You get one source of truth in AGENTS.md
, plus a place for Claude-only additions the other tools never see.
Strengths: No second copy, so drift is structurally impossible. No special privileges — unlike a symlink, the import works on Windows without Admin/Developer Mode (the docs explicitly prefer the import over a symlink there). Keeps Claude-specific instructions separate from the shared file.
Constraints: The first time Claude Code encounters an external import it shows a one-time approval dialog; if you decline, imports stay disabled. The imported file loads in full at launch (same as any CLAUDE.md), so keep AGENTS.md
reasonably sized.
Related: running /init
in a repo that already has an AGENTS.md
reads it and folds the relevant parts into the generated CLAUDE.md
(it also reads .cursorrules
/ .windsurfrules
) — handy for a one-time consolidation.
The patterns below are the copy/duplicate-based alternatives, for cases where the import does not fit (you want two genuinely separate files, AGENTS.md
is auto-generated, you need programmatic merging, etc.).
The lightest possible solution. Make CLAUDE.md
and AGENTS.md
literally the same file via a filesystem symlink.
ln -sf AGENTS.md CLAUDE.md
git add CLAUDE.md # commits the symlink, not duplicate content
Now any edit to AGENTS.md
is immediately visible to Claude Code, plus every tool that reads AGENTS.md
natively (Codex, Amp, Copilot, Cursor, Windsurf, Cline).
Strengths: Five seconds to set up. Zero divergence possible. Single source of truth.
Constraints: Some Windows environments don't handle git symlinks gracefully (requires core.symlinks = true
). Some tools may resolve the symlink and complain about content type. Test on every platform your team uses.
If symlinks aren't viable (Windows team members, or you want both files as real files in git history), use a pre-commit hook that copies the canonical file to the other.
#!/bin/bash
if git diff --cached --name-only | grep -q "^AGENTS\.md$"; then
cp AGENTS.md CLAUDE.md
git add CLAUDE.md
fi
if git diff --cached --name-only | grep -q "^CLAUDE\.md$"; then
cp CLAUDE.md AGENTS.md
git add AGENTS.md
fi
The hook runs at commit time and mirrors changes in either direction.
Strengths: Works on all platforms. Both files exist as real files. The duplication is automated, so drift is impossible (except during in-progress edits before the next commit).
Constraints: Requires every team member to install the hook. The pre-commit framework (https://pre-commit.com) helps with installation enforcement.
If you can't or don't want to physically duplicate the file (e.g., AGENTS.md is auto-generated, or contains content that's irrelevant to Claude Code), use a SessionStart hook that programmatically merges relevant AGENTS.md content into Claude Code's context.
#!/bin/bash
if [ -f "AGENTS.md" ] && [ ! -f "CLAUDE.md" ]; then
cp AGENTS.md CLAUDE.md
echo "Generated CLAUDE.md from AGENTS.md (SessionStart hook)" >&2
elif [ -f "AGENTS.md" ] && [ -f "CLAUDE.md" ]; then
if ! diff -q AGENTS.md CLAUDE.md > /dev/null 2>&1; then
echo "WARNING: AGENTS.md and CLAUDE.md differ. Consider syncing." >&2
echo "Run: diff AGENTS.md CLAUDE.md" >&2
fi
fi
The hook fires on session start. If only AGENTS.md exists, it generates CLAUDE.md from it. If both exist, it warns on drift.
Strengths: Lazy generation (CLAUDE.md only created when needed). Drift detection at session start. No git history changes for the generated file.
Constraints: Generated CLAUDE.md should be added to .gitignore
if you want AGENTS.md as the only committed source. The hook must be installed per-machine via cc-safe-setup or manual config.
If you have a mix of projects (some AGENTS.md primary, some CLAUDE.md primary, some both), use direnv to declare the canonical source per project.
export CLAUDE_PROJECT_INSTRUCTION_SOURCE=AGENTS.md
export CLAUDE_PROJECT_INSTRUCTION_SOURCE=CLAUDE.md
Then a SessionStart hook reads the variable and routes the merge logic:
#!/bin/bash
SOURCE="${CLAUDE_PROJECT_INSTRUCTION_SOURCE:-CLAUDE.md}"
if [ "$SOURCE" = "AGENTS.md" ] && [ -f "AGENTS.md" ]; then
cp AGENTS.md CLAUDE.md
fi
The combination gives you per-project policy without changing any per-project files beyond .envrc
.
Strengths: Centralizes the policy decision (which file is canonical) in .envrc
rather than scattered logic. Works well for solo developers managing 20+ repos with different conventions.
Constraints: Requires direnv installed. Requires per-project .envrc
files (which need direnv allow
on first encounter).
For teams or open-source maintainers who want to detect drift even when no AI session is active (e.g., as part of CI), run a periodic diff tool.
#!/bin/bash
for repo in $(find ~/projects -maxdepth 2 -name ".git" -exec dirname {} \;); do
cd "$repo" || continue
if [ -f AGENTS.md ] && [ -f CLAUDE.md ]; then
if ! diff -q AGENTS.md CLAUDE.md > /dev/null 2>&1; then
echo "DRIFT: $repo"
diff -u AGENTS.md CLAUDE.md | head -20
fi
fi
done
Schedule this in cron (0 9 * * 1
for Monday morning) or wire it to CI (.github/workflows/instruction-sync.yml
).
Strengths: Independent of session lifecycle. Catches drift introduced by tools other than Claude Code. Provides team-wide visibility.
Constraints: Cron requires per-machine setup. CI requires repo-by-repo configuration. The diff alone doesn't fix anything — it just surfaces the problem.
| Persona | Recommended default | Heavier escalation |
|---|---|---|
| A (Solo, Multiple Tools) | Pattern 0 (@AGENTS.md import) |
|
| Pattern 0 + Pattern 4 (per-project routing) | ||
| B (Mixed-Tool Team) | Pattern 0 (@AGENTS.md import), or Pattern 2 (pre-commit) if you need two real files |
|
| Pattern 2 + Pattern 5 (CI drift detection) | ||
| C (Open-Source Maintainer) | Pattern 0 (@AGENTS.md import) |
|
| Pattern 0 + Pattern 5 (CI), with Pattern 2 documented in CONTRIBUTING.md |
For nearly everyone the answer is now Pattern 0 — it is officially documented, needs no tooling, and cannot drift. Reach for Patterns 1–5 only when you genuinely need two separate files or programmatic merging.
Initial setup cost: Pattern 1 (5 minutes) → Pattern 2 (15 minutes) → Pattern 3 (10 minutes, extends Pattern 1 or 2) → Pattern 4 (30 minutes) → Pattern 5 (20 minutes). Total 60-90 minutes for the full operator-side stack.
Native Claude Code support for AGENTS.md. The actual fix is harness-layer. Anthropic needs to make Claude Code read AGENTS.md as a fallback when CLAUDE.md is absent, or alongside it when both exist. Keep upvoting #6235 to make the case.
Skills-folder interop (.agents/skills/). A separate ask in #31005. Claude Code's hooks and skills are stored under .claude/
, while AGENTS.md proposes .agents/skills/
. Patterns 1-5 above cover the file-level interop; the skills directory interop needs a different approach (symlinking .claude/skills/ → .agents/skills/
).
Content-level interop. AGENTS.md and CLAUDE.md are both Markdown, but the conventions for what goes where differ slightly across tools. A future operator-side pattern could lint for tool-specific phrases that don't translate.
The AGENTS.md/CLAUDE.md interop space already has direct OSS tooling. The five patterns in this guide complement these tools — they're the lighter-weight operator-side equivalents:
(258★, Apache 2.0) — Linter and LSP for AI coding assistants. Validates CLAUDE.md, AGENTS.md, SKILL.md, hooks, MCP. IDE plugin focus.agent-sh/agnix
(125★, MIT) — Keep AGENTS.md and CLAUDE.md in sync across your projects.iannuttall/source-agents
(17★, CC0) — Claude Code plugin that syncs AGENTS.md → CLAUDE.md.intellectronica/claude-agentsmd
(1,593★) — AGENTS.md rules/skills content library for Codex, Cursor, and Claude Code.ciembor/agent-rules-books
The five patterns above use only Bash, git, and direnv — no new tooling. Use whichever fits your team's tolerance for additional dependencies.
The 5,200+-reaction cluster is large enough that the harness team has visibility, but not large enough to displace the existing roadmap. Operators who can't wait need operator-side patterns now. This guide is the consolidated reference so the next operator landing here from search can pick a pattern in five minutes instead of reconstructing it from scratch.
If the AGENTS.md interop gap intersects with other Claude Code operational pain you're facing — for example, the multi-account workflow gap (1,178 cumulative reactions across #18435, #27302, #36151) — there's a parallel field guide for that cluster. The Sub-Agent Observability Handbook (shipped) covers the subagent silent-failure cluster (8 cases, 4 patterns). The CC Safety Lab Founder Membership ships monthly continuing-evidence reports including new operator-side techniques as they surface — the July 2026 issue will center on the AGENTS.md cluster covered here.
Free Claude Code safety material:
cc-safe-setup— 751+ MIT-licensed safety hooksMulti-Account Operator Field Guide(日本語版)Multi-Account Self-Audit— 7-question interactive diagnostic
Want these patterns as a complete, ready-to-use kit? The ** AGENTS.md × Claude Code Interop Handbook** (English, $12, 21 pages) collects the verified 9-tool setup matrix, all six paths in one place, copy-paste templates per tool, a rollback-safe migration runbook, and a team drift guard. This free guide covers the concepts; the handbook is the practical kit. (A longer Japanese edition is on
Zenn.)
*Independent operator field guide, 2026-05-26 03:55 UTC. MIT-licensed prose. Patterns derived from running Claude Code alongside Codex and Cursor across 800+ hours of autonomous operation. Updates and corrections welcome — comment on *#6235 or file an issue against cc-safe-setup.
#6235or file an issue against
Single-page interactive 6-question diagnostic: https://gist.github.com/yurukusa/bb22e61a75904771e0c88a0335f5fbfa (browser-rendered: https://htmlpreview.github.io/?https://gist.githubusercontent.com/yurukusa/bb22e61a75904771e0c88a0335f5fbfa/raw/agents-md-self-audit.html) #
Maps your shape (Persona A solo / Persona B mixed-tool team / Persona C OSS maintainer) to the recommended combination of the five patterns above, factoring in drift severity, scale, platform constraints (Windows vs unix-only), and tooling appetite. ~3 minutes. No signup, no telemetry, zero external requests.
A Japanese-language version of this guide is also available: https://gist.github.com/yurukusa/8402b4672147381721dffed6d21a4148 (~3,500 characters, MIT-licensed prose, same five patterns adapted for Japanese-speaking operators). #
Update (2026-06): Cursor, Windsurf, and Cline have all added native support for a project-root AGENTS.md
— they now read it directly, with no symlink or extra config. This makes the interop story much simpler than it was when this guide was first written.
Per their own docs — Cursor, Windsurf, and Cline — each auto-discovers an AGENTS.md
at the repo root and feeds it into its rules engine. Each also keeps a newer per-tool directory format (.cursor/rules/
, .windsurf/rules/
, .clinerules/
); use those only for genuinely tool-specific rules and keep everything shared in AGENTS.md
.
So for a project that wants Claude Code, Codex, Amp, Copilot, Cursor, Windsurf, and Cline to share one source of truth, only Claude Code needs a bridge — every other tool reads AGENTS.md
as-is:
ln -sf AGENTS.md CLAUDE.md # …or put `@AGENTS.md` as the first line of CLAUDE.md (Windows-friendly, no Admin)
Tool-specific behavior (Windsurf Cascade hooks, Claude Code's settings.json
permissions, Cline-specific rules in .clinerules/
) lives in each tool's own config and isn't portable — only the narrative instructions are shared via AGENTS.md
.