Home / Compare / agents.md vs CLAUDE.md

agents.md vs CLAUDE.md — when to use each

Two file types that overlap. The honest answer: write agents.md as your default; let CLAUDE.md cover Claude-specific things only.

What each is for

agents.md — cross-tool repository instructions. Codex CLI, Cursor, Aider, Cline, and (since late 2025) Claude Code all read it.
CLAUDE.md — Claude Code's project memory. Loaded at the start of every Claude Code session in that repo. Persistent across conversations.

The line: agents.md says "this repo wants X." CLAUDE.md says "and Claude Code in particular should also know Y."

Side-by-side

	agents.md	CLAUDE.md
Read by	Codex CLI, Cursor, Aider, Cline, Claude Code (fallback)	Claude Code only
Loaded at	Tool startup / each prompt	Session start as project memory
Wins on conflict	—	CLAUDE.md (Claude Code prefers it)
Typical length	50–300 lines	20–150 lines
Imports other files?	No	Yes (Claude Code 1.x supports imports)

The recommended pattern in 2026

repo-root/agents.md       # source of truth — every agent reads this
CLAUDE.md       # Claude-specific overrides + imports
.cursorrules    # one-line redirect to agents.md (or empty)

The CLAUDE.md is short — 10–30 lines — and starts with:

CLAUDE.mdSee [agents.md](./agents.md).

Claude Code-specific:
- Use the refactor-to-pure-functions skill when reworking imperative code.
- Don't create new docs (.md files) unless explicitly asked.
- Test command is npm test; long-running tests are gated behind RUN_LONG=1.

Everything Cursor and Codex CLI also need to know stays in agents.md.

What goes in CLAUDE.md only

Skill triggers: "When the user asks to fix a flaky test, use the flaky-test-debugger skill."
Tool-specific overrides: "Don't run npm install automatically; ask first."
References to bundled skills under .claude/skills/ or .claude/subagents/.
Project memory (decisions, lessons, ongoing work) that Claude Code surfaces with /memory.

Anti-patterns

Duplicating instructions in both files. They will drift. Pick one source of truth (agents.md) and reference it.
Treating CLAUDE.md as a README. It's a system prompt, not documentation.
Stuffing 1000+ lines of code conventions into CLAUDE.md. The agent's context window has better uses; load skills on demand instead.

Browse MDs

Last updated: 2026-04-25.