{"slug": "does-claude-code-read-agents-md-no-it-reads-claude-md-the-official-agents-md-and", "title": "Does Claude Code read AGENTS.md? No — it reads CLAUDE.md. The official @AGENTS.md import and symlink methods that actually work (the 'reads it as a fallback' claim is wrong), plus five operator-side…", "summary": "Claude Code reads CLAUDE.md, not AGENTS.md, contrary to claims in third-party guides. Anthropic documents two methods to make Claude Code use AGENTS.md: importing it via @AGENTS.md in CLAUDE.md, or symlinking AGENTS.md to CLAUDE.md. The feature request to natively support AGENTS.md has over 5,200 reactions, making it the largest unmet request in the Claude Code issue tracker.", "body_md": "**For operators running Claude Code alongside Codex, Cursor, Amp, or Aider — and tired of maintaining two instruction files**\n\n*Independent operator field guide, updated 2026-06-03. MIT-licensed prose. ~3,000 words.*\n\n**Claude Code reads CLAUDE.md, not AGENTS.md.** That is stated verbatim in the\n\n[official memory docs](https://code.claude.com/docs/en/memory#agents-md)(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\n\n**not in the official documentation** and does not match observed behavior. Don't rely on it.\n\nThe two methods Anthropic actually documents to make Claude Code use a repo's `AGENTS.md`\n\n:\n\n**Import it from** Put a one-line import at the top of`CLAUDE.md`\n\n(recommended — and the only option that works on Windows without extra privileges).`CLAUDE.md`\n\n:Claude loads the imported file at session start, then appends any Claude-specific notes you add below it.\n\n```\n@AGENTS.md\n\n## Claude Code\nUse plan mode for changes under `src/billing/`.\n```\n\n**Symlink, if you don't need Claude-specific content:** On Windows a symlink needs Administrator privileges or Developer Mode, so prefer the\n\n```\nln -s AGENTS.md CLAUDE.md\n```\n\n`@AGENTS.md`\n\nimport there.\n\n(`/init`\n\nin a repo that already has an `AGENTS.md`\n\nalso reads it and folds the relevant parts into the generated `CLAUDE.md`\n\n.)\n\nThat 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.\n\nFeature request [#6235 on anthropics/claude-code](https://github.com/anthropics/claude-code/issues/6235) — \"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](https://github.com/anthropics/claude-code/issues/31005), adds 220 more reactions. Across the tracker, 173 distinct issues mention AGENTS.md.\n\nThe shape of the ask:\n\nCodex, Amp, Cursor, and others are converging on AGENTS.md (\n\n[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.\n\nAnthropic 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.\n\nIf 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.\n\nWhen Claude Code starts in a directory, it reads `CLAUDE.md`\n\n(plus `~/.claude/CLAUDE.md`\n\nfor global rules). When Codex starts, it reads `AGENTS.md`\n\n. When Cursor starts, it reads `.cursorrules`\n\n. When Amp starts, it reads AGENTS.md too (Amp converged from its own AGENT.md to the shared standard).\n\nThe pain shows up in three places:\n\n**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`\n\nsetup and their `vitest`\n\nsetup disagree about how to mock the database — because the instruction files diverged.\n\n**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.\n\n**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.\n\nThe operator-side workarounds below address all three.\n\nThe 5,200+-reaction cluster maps to three operator shapes:\n\n**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.\n\n**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.\n\n**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.\n\nBefore the five patterns below, there is one approach the official Claude Code docs now recommend as the default — the `@AGENTS.md`\n\nimport (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.\n\nThis 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`\n\n, not `AGENTS.md`\n\n— but a `CLAUDE.md`\n\ncan *import* your `AGENTS.md`\n\nwith a one-line directive, so there is only ever one real instruction file:\n\n```\n@AGENTS.md\n\n## Claude Code\n(optional: Claude-specific instructions, appended after the import)\n```\n\nClaude loads the imported `AGENTS.md`\n\nat session start, then appends anything you write below it. You get one source of truth in `AGENTS.md`\n\n, plus a place for Claude-only additions the other tools never see.\n\n**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.\n\n**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`\n\nreasonably sized.\n\n**Related:** running `/init`\n\nin a repo that already has an `AGENTS.md`\n\nreads it and folds the relevant parts into the generated `CLAUDE.md`\n\n(it also reads `.cursorrules`\n\n/ `.windsurfrules`\n\n) — handy for a one-time consolidation.\n\nThe patterns below are the copy/duplicate-based alternatives, for cases where the import does not fit (you want two genuinely separate files, `AGENTS.md`\n\nis auto-generated, you need programmatic merging, etc.).\n\nThe lightest possible solution. Make `CLAUDE.md`\n\nand `AGENTS.md`\n\nliterally the same file via a filesystem symlink.\n\n```\n# In your repo root, with AGENTS.md as the canonical source:\nln -sf AGENTS.md CLAUDE.md\ngit add CLAUDE.md  # commits the symlink, not duplicate content\n```\n\nNow any edit to `AGENTS.md`\n\nis immediately visible to Claude Code, plus every tool that reads `AGENTS.md`\n\nnatively (Codex, Amp, Copilot, Cursor, Windsurf, Cline).\n\n**Strengths:** Five seconds to set up. Zero divergence possible. Single source of truth.\n\n**Constraints:** Some Windows environments don't handle git symlinks gracefully (requires `core.symlinks = true`\n\n). Some tools may resolve the symlink and complain about content type. Test on every platform your team uses.\n\nIf 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.\n\n``` bash\n# .git/hooks/pre-commit (or via pre-commit framework)\n#!/bin/bash\nif git diff --cached --name-only | grep -q \"^AGENTS\\.md$\"; then\n    cp AGENTS.md CLAUDE.md\n    git add CLAUDE.md\nfi\nif git diff --cached --name-only | grep -q \"^CLAUDE\\.md$\"; then\n    cp CLAUDE.md AGENTS.md\n    git add AGENTS.md\nfi\n```\n\nThe hook runs at commit time and mirrors changes in either direction.\n\n**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).\n\n**Constraints:** Requires every team member to install the hook. The pre-commit framework ([https://pre-commit.com](https://pre-commit.com)) helps with installation enforcement.\n\nIf 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.\n\n``` bash\n#!/bin/bash\n# ~/.claude/hooks/agents-md-merge.sh\n# SessionStart hook\n\nif [ -f \"AGENTS.md\" ] && [ ! -f \"CLAUDE.md\" ]; then\n    # CLAUDE.md absent: render AGENTS.md to a temporary CLAUDE.md\n    cp AGENTS.md CLAUDE.md\n    echo \"Generated CLAUDE.md from AGENTS.md (SessionStart hook)\" >&2\nelif [ -f \"AGENTS.md\" ] && [ -f \"CLAUDE.md\" ]; then\n    # Both exist: warn on drift\n    if ! diff -q AGENTS.md CLAUDE.md > /dev/null 2>&1; then\n        echo \"WARNING: AGENTS.md and CLAUDE.md differ. Consider syncing.\" >&2\n        echo \"Run: diff AGENTS.md CLAUDE.md\" >&2\n    fi\nfi\n```\n\nThe hook fires on session start. If only AGENTS.md exists, it generates CLAUDE.md from it. If both exist, it warns on drift.\n\n**Strengths:** Lazy generation (CLAUDE.md only created when needed). Drift detection at session start. No git history changes for the generated file.\n\n**Constraints:** Generated CLAUDE.md should be added to `.gitignore`\n\nif you want AGENTS.md as the only committed source. The hook must be installed per-machine via cc-safe-setup or manual config.\n\nIf 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.\n\n```\n# /path/to/project-a/.envrc (AGENTS.md canonical)\nexport CLAUDE_PROJECT_INSTRUCTION_SOURCE=AGENTS.md\n\n# /path/to/project-b/.envrc (CLAUDE.md canonical)\nexport CLAUDE_PROJECT_INSTRUCTION_SOURCE=CLAUDE.md\n```\n\nThen a SessionStart hook reads the variable and routes the merge logic:\n\n``` bash\n#!/bin/bash\n# ~/.claude/hooks/agents-md-route.sh\nSOURCE=\"${CLAUDE_PROJECT_INSTRUCTION_SOURCE:-CLAUDE.md}\"\nif [ \"$SOURCE\" = \"AGENTS.md\" ] && [ -f \"AGENTS.md\" ]; then\n    cp AGENTS.md CLAUDE.md\nfi\n```\n\nThe combination gives you per-project policy without changing any per-project files beyond `.envrc`\n\n.\n\n**Strengths:** Centralizes the policy decision (which file is canonical) in `.envrc`\n\nrather than scattered logic. Works well for solo developers managing 20+ repos with different conventions.\n\n**Constraints:** Requires direnv installed. Requires per-project `.envrc`\n\nfiles (which need `direnv allow`\n\non first encounter).\n\nFor 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.\n\n``` bash\n#!/bin/bash\n# ~/bin/agents-md-drift-check.sh\n# Run via cron, CI, or pre-push hook\n\nfor repo in $(find ~/projects -maxdepth 2 -name \".git\" -exec dirname {} \\;); do\n    cd \"$repo\" || continue\n    if [ -f AGENTS.md ] && [ -f CLAUDE.md ]; then\n        if ! diff -q AGENTS.md CLAUDE.md > /dev/null 2>&1; then\n            echo \"DRIFT: $repo\"\n            diff -u AGENTS.md CLAUDE.md | head -20\n        fi\n    fi\ndone\n```\n\nSchedule this in cron (`0 9 * * 1`\n\nfor Monday morning) or wire it to CI (`.github/workflows/instruction-sync.yml`\n\n).\n\n**Strengths:** Independent of session lifecycle. Catches drift introduced by tools other than Claude Code. Provides team-wide visibility.\n\n**Constraints:** Cron requires per-machine setup. CI requires repo-by-repo configuration. The diff alone doesn't fix anything — it just surfaces the problem.\n\n| Persona | Recommended default | Heavier escalation |\n|---|---|---|\n| A (Solo, Multiple Tools) | Pattern 0 (`@AGENTS.md` import) |\nPattern 0 + Pattern 4 (per-project routing) |\n| B (Mixed-Tool Team) | Pattern 0 (`@AGENTS.md` import), or Pattern 2 (pre-commit) if you need two real files |\nPattern 2 + Pattern 5 (CI drift detection) |\n| C (Open-Source Maintainer) | Pattern 0 (`@AGENTS.md` import) |\nPattern 0 + Pattern 5 (CI), with Pattern 2 documented in CONTRIBUTING.md |\n\nFor 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.\n\nInitial 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.\n\n**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](https://github.com/anthropics/claude-code/issues/6235) to make the case.\n\n**Skills-folder interop (.agents/skills/).** A separate ask in [#31005](https://github.com/anthropics/claude-code/issues/31005). Claude Code's hooks and skills are stored under `.claude/`\n\n, while AGENTS.md proposes `.agents/skills/`\n\n. Patterns 1-5 above cover the file-level interop; the skills directory interop needs a different approach (symlinking `.claude/skills/ → .agents/skills/`\n\n).\n\n**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.\n\nThe 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:\n\n(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`\n\n(125★, MIT) — Keep AGENTS.md and CLAUDE.md in sync across your projects.`iannuttall/source-agents`\n\n(17★, CC0) — Claude Code plugin that syncs AGENTS.md → CLAUDE.md.`intellectronica/claude-agentsmd`\n\n(1,593★) — AGENTS.md rules/skills content library for Codex, Cursor, and Claude Code.`ciembor/agent-rules-books`\n\nThe five patterns above use only Bash, git, and direnv — no new tooling. Use whichever fits your team's tolerance for additional dependencies.\n\nThe 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.\n\nIf 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](https://github.com/anthropics/claude-code/issues/18435), [#27302](https://github.com/anthropics/claude-code/issues/27302), [#36151](https://github.com/anthropics/claude-code/issues/36151)) — there's a [parallel field guide](https://gist.github.com/yurukusa/d880ecc984af5d664f003daf85f956e3) for that cluster. The [Sub-Agent Observability Handbook](https://gist.github.com/yurukusa/1c26934ed95f638354f0063df6c05e48) (shipped) covers the subagent silent-failure cluster (8 cases, 4 patterns). The [CC Safety Lab](https://ko-fi.com/yurukusa/tiers) 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.\n\nFree Claude Code safety material:\n\n[cc-safe-setup](https://github.com/yurukusa/cc-safe-setup)— 751+ MIT-licensed safety hooks[Multi-Account Operator Field Guide](https://gist.github.com/yurukusa/d880ecc984af5d664f003daf85f956e3)([日本語版](https://gist.github.com/yurukusa/13f46cf96093ef487760efcfb2c1c2b8))[Multi-Account Self-Audit](https://gist.github.com/yurukusa/fc73fec611cc277c756e2102e067e807)— 7-question interactive diagnostic\n\nWant 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\n\n[Zenn](https://zenn.dev/yurukusa/books/agents-md-interop).)\n\n*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](https://github.com/anthropics/claude-code/issues/6235) or file an issue against [cc-safe-setup](https://github.com/yurukusa/cc-safe-setup).\n\n[#6235](https://github.com/anthropics/claude-code/issues/6235)or file an issue against\n\n[cc-safe-setup](https://github.com/yurukusa/cc-safe-setup).\n\n## Single-page interactive 6-question diagnostic: [https://gist.github.com/yurukusa/bb22e61a75904771e0c88a0335f5fbfa](https://gist.github.com/yurukusa/bb22e61a75904771e0c88a0335f5fbfa) (browser-rendered: [https://htmlpreview.github.io/?https://gist.githubusercontent.com/yurukusa/bb22e61a75904771e0c88a0335f5fbfa/raw/agents-md-self-audit.html](https://htmlpreview.github.io/?https://gist.githubusercontent.com/yurukusa/bb22e61a75904771e0c88a0335f5fbfa/raw/agents-md-self-audit.html))\nMaps 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.\n\n## A Japanese-language version of this guide is also available: [https://gist.github.com/yurukusa/8402b4672147381721dffed6d21a4148](https://gist.github.com/yurukusa/8402b4672147381721dffed6d21a4148) (~3,500 characters, MIT-licensed prose, same five patterns adapted for Japanese-speaking operators).\n\n**Update (2026-06):** Cursor, Windsurf, and Cline have all added native support for a project-root `AGENTS.md`\n\n— 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.\n\nPer their own docs — [Cursor](https://cursor.com/docs/rules), [Windsurf](https://docs.windsurf.com/windsurf/cascade/agents-md), and [Cline](https://docs.cline.bot/customization/cline-rules) — each auto-discovers an `AGENTS.md`\n\nat the repo root and feeds it into its rules engine. Each also keeps a newer per-tool directory format (`.cursor/rules/`\n\n, `.windsurf/rules/`\n\n, `.clinerules/`\n\n); use those only for genuinely tool-specific rules and keep everything shared in `AGENTS.md`\n\n.\n\nSo 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`\n\nas-is:\n\n```\n# Codex, Amp, Copilot, Cursor, Windsurf, Cline read AGENTS.md natively — nothing to do.\n# Only Claude Code needs pointing at it:\nln -sf AGENTS.md CLAUDE.md       # …or put `@AGENTS.md` as the first line of CLAUDE.md (Windows-friendly, no Admin)\n```\n\nTool-specific behavior (Windsurf Cascade hooks, Claude Code's `settings.json`\n\npermissions, Cline-specific rules in `.clinerules/`\n\n) lives in each tool's own config and isn't portable — only the *narrative instructions* are shared via `AGENTS.md`\n\n.", "url": "https://wpnews.pro/news/does-claude-code-read-agents-md-no-it-reads-claude-md-the-official-agents-md-and", "canonical_source": "https://gist.github.com/yurukusa/d36197848911f025add142abefcde685", "published_at": "2026-05-25 18:52:32+00:00", "updated_at": "2026-06-12 22:13:55.762032+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "large-language-models", "generative-ai"], "entities": ["Claude Code", "Anthropic", "Codex", "Cursor", "Amp", "Aider", "AGENTS.md", "CLAUDE.md"], "alternates": {"html": "https://wpnews.pro/news/does-claude-code-read-agents-md-no-it-reads-claude-md-the-official-agents-md-and", "markdown": "https://wpnews.pro/news/does-claude-code-read-agents-md-no-it-reads-claude-md-the-official-agents-md-and.md", "text": "https://wpnews.pro/news/does-claude-code-read-agents-md-no-it-reads-claude-md-the-official-agents-md-and.txt", "jsonld": "https://wpnews.pro/news/does-claude-code-read-agents-md-no-it-reads-claude-md-the-official-agents-md-and.jsonld"}}