AGENTS.md vs CLAUDE.md: Which Config Standard to Choose

The choice between agents.md vs claude.md comes down to ecosystem reach versus harness specialization: AGENTS.md provides vendor-neutral instruction portability across Cursor, Codex, Copilot, and Cline, while CLAUDE.md unlocks Anthropic-specific skills, subagents, and path-scoped rules. For teams exploring the broader harness ecosystem, our Claude Code complete guide covers how repository instructions interact with execution permissions.

npm run check:config-parity audits both configuration approaches across nine architectural dimensions:

npm run check:config-parity
# → Evaluated 9 architectural dimensions across both standards
# → 10 of 10 CLAUDE.md sections map cleanly to AGENTS.md headings
# → Transclusion directive (@AGENTS.md) achieves 100% portability with 0% duplication

Key takeaways

• Portability vs specialization: AGENTS.md is supported across 60,000+ repositories and six major harnesses; CLAUDE.md is dedicated to Claude Code CLI and Desktop.
• Transclusion bridges both: Placing @AGENTS.md inside CLAUDE.md provides complete multi-agent support with zero duplicated lines.
• Different scoping models: AGENTS.md uses hierarchical nested directory files (packages/*/AGENTS.md); CLAUDE.md uses .claude/rules/*.md path glob matchers.
• Codex truncates at 32 KB: OpenAI Codex CLI silently cuts instruction files at 32,768 bytes, while Claude Code loads files in full regardless of length.
• Tool-specific capabilities: Custom slash commands (.claude/skills/) and subagent prompts (.claude/agents/) require Claude Code's directory structure.

The short answer

Do not choose between them—bridge them. Commit your core project guidelines, build commands, and architectural constraints into an AGENTS.md standard file. Then create a lightweight CLAUDE.md that imports it using the @AGENTS.md directive.

This gives Cursor, Codex, Copilot, and Cline immediate native access to your repository conventions, while allowing Claude Code to inherit the exact same rules alongside specialized subagents and tools.

# Repository Instructions
@AGENTS.md

## Claude Code Specifics
- Memory rules: `.claude/rules/`
- Custom skills: `.claude/skills/`

Direct comparison: agents.md vs claude.md

Evaluating agents.md vs claude.md across core architectural features:

Comparing an agents md vs claude md setup reveals that while both formats use plain Markdown, their discovery mechanisms and context injection pipelines differ significantly.

Context delivery and memory injection mechanics

How each format reaches the model's attention:

• CLAUDE.md injection: Claude Code injects CLAUDE.md as an unpinned user message immediately following the system prompt. As analyzed in our CLAUDE.md setup guide, this guarantees the file is read on every turn, but also makes it subject to recency bias in long conversations.
• AGENTS.md injection: Cursor, Cline, and Roo Code inject AGENTS.md directly into the system prompt. Codex CLI delivers it as the first user turn upon repository initialization.

Because Codex CLI caps project instructions at 32,768 bytes (project_doc_max_bytes), an overly verbose CLAUDE.md copied into AGENTS.md will be truncated silently. Keeping context lean prevents claude code slow performance and memory bloat across all harnesses.

Monorepo scoping: Nested files vs path-scoped rules

Managing instructions in a monorepo highlights the structural differences between both formats:

AGENTS.md nested hierarchy

AGENTS.md relies on directory co-location:

AGENTS.md                      ← Global commands, git policies, security
apps/
  web/
    AGENTS.md                  ← Next.js rules, Tailwind v4 tokens
  admin/
    AGENTS.md                  ← D1 session auth, admin security

When an agent opens a file in apps/web/, tools like Cursor merge the root AGENTS.md with apps/web/AGENTS.md.

CLAUDE.md path-scoped rules

Claude Code uses a centralized .claude/rules/ directory with frontmatter path globbing:

---
paths:
  - "app/admin/**"
  - "lib/admin/**"
---
# Admin Security Rules
Always verify session claims via Web Crypto in middleware.ts.

This centralizes rule management in one directory, but requires Claude Code's proprietary rule parser.

Ecosystem support and tool portability

If your engineering organization has developers using different AI tools simultaneously, format lock-in creates maintenance friction:

• The multi-tool reality: One engineer uses Cursor for visual UI design; another runs Claude Code in the terminal for cross-repo refactors; a third uses GitHub Copilot in VS Code.
• The failure of proprietary formats: If conventions only exist in CLAUDE.md, Cursor and Copilot ignore them, leading to broken imports and formatting regressions.
• The portability advantage: When an open source AI coding assistant like Aider or Cline joins the workflow, it immediately reads AGENTS.md without custom adapters.

The bridging strategy: Running both without duplication

You should never manually maintain duplicate copies of AGENTS.md and CLAUDE.md. Manual duplication creates context drift within weeks.

Three bridging approaches evaluated:

1. Transclusion directive (@AGENTS.md) — Recommended

Commit your instructions to AGENTS.md. In CLAUDE.md, include:

# Devventa
@AGENTS.md

Claude Code automatically expands @AGENTS.md and loads its full content into context. This achieves 100% portability with 0% duplication.

2. Filesystem symlinks — Fragile

Running ln -s AGENTS.md CLAUDE.md creates a single physical file on Linux and macOS. However, on Windows machines without Developer Mode enabled, git checks out symlinks as small text files (mode 120000), causing Claude Code to load the literal path string rather than the target file.

3. Build-time generator — Overkill

Generating CLAUDE.md from AGENTS.md via an npm script adds an unnecessary build dependency when native @ transclusion already exists.

Which ai config file standard should your team choose

Use this decision matrix to determine your primary ai config file standard:

• Use AGENTS.md as primary if: You have a multi-tool team (Cursor + Codex + Copilot + Claude Code) or want future-proof open-source compatibility.
• Use CLAUDE.md as primary if: Your entire engineering workflow is strictly centered on Claude Code CLI and you rely heavily on custom subagents and .claude/skills/.
• Use the hybrid bridge if: You want standard cross-tool compatibility while retaining Claude Code subagent capabilities (the setup we run).

As documented in why Claude ignores CLAUDE.md, regardless of the format you choose, rules without automated checks behind them will eventually be violated during long sessions.

Common mistakes when maintaining dual configs

• Copying rules between files manually: Inevitably leads to one file having updated test commands while the other carries obsolete flags.
• Relying on symlinks in cross-platform teams: Windows developers will check out broken gitlinks.
• Placing Claude-specific skills in AGENTS.md: Non-Claude agents will attempt to execute /commands that do not exist in their runtime.
• Exceeding context budgets: Stacking extensive rules in both files leads to context exhaustion and high token bills.

What we are not claiming

We do not claim that AGENTS.md has completely replaced CLAUDE.md. Anthropic's tool ecosystem continues to introduce proprietary features like hooks, background subagents, and scoped memory indexes that have no direct equivalent in the open AGENTS.md specification. The hybrid approach gives you the strengths of both.

Conclusion

Choosing between AGENTS.md and CLAUDE.md is a false dichotomy. By treating AGENTS.md as your repository's universal contract and referencing it from CLAUDE.md, you achieve complete cross-tool portability without sacrificing harness-specific features. To ensure your multi-turn agent sessions do not stall unexpectedly, read our guide on AI coding rate limits next. And if more than one developer is involved, check which of these files a reviewer can actually see — an audit of the agent control plane found four of five capability grants outside the repository.

Frequently asked questions

Muhammad Kashif

Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.