If you only use Claude Code, the answer is short: keep your project memory in CLAUDE.md. If your team uses Codex, Cursor, Windsurf, Aider, or any combination — the answer is AGENTS.md, with a one-line CLAUDE.md that imports it.
There's a reason this question keeps coming up. CLAUDE.md predates the cross-tool standard. It works extremely well inside Claude Code — auto-loaded at session start, walks up the directory tree, supports nested overrides per subfolder. But the moment a teammate opens the same repo in Cursor or runs a Codex job, your CLAUDE.md is invisible to them. AGENTS.md fixed that by becoming the format the rest of the tools agreed on.
Below is the clear-eyed comparison: what each format actually is, where it loads from, what breaks when you mix them, and the migration path I'd recommend for most teams in 2026.
CLAUDE.md is Claude Code's project memory format. When you start a session, Claude Code reads CLAUDE.md from the current directory, then walks up the tree reading every parent CLAUDE.md it finds, then reads ~/.claude/CLAUDE.md for your user-level instructions. All of it gets concatenated into the system context.
It also supports nested files: a CLAUDE.md inside apps/web/ only loads when you're working in that subfolder. This is the killer feature — you can put repo-wide rules at the root and override them per package.
A minimal real one looks like this:
# Project: payments-api
## Stack
- Node 20, TypeScript strict mode
- Postgres via Prisma, never raw SQL in routes
- Tests: Vitest. Run with `pnpm test --run`
## Conventions
- Route handlers in `src/routes/*.ts`, one file per resource
- Errors use `AppError` from `src/lib/errors.ts` — never throw strings
- No `any`. Use `unknown` + narrow
## Don't
- Don't add new ORM tables without a migration in `prisma/migrations/`
- Don't import from `src/internal/*` outside `src/internal/`
- Don't bypass the rate limiter middleware
That's it. Under 200 lines is the sweet spot. Past that, Claude starts ignoring sections — which is what our optimize tool was built to catch.
AGENTS.md is an open, tool-agnostic format that emerged in 2025 when it became obvious every coding agent was inventing its own version of the same thing. OpenAI Codex, Cursor (current versions), Aider, Continue, Sourcegraph Amp, and several others all read AGENTS.md at the project root.
The format is identical in spirit to CLAUDE.md — plain Markdown, free-form, walks up the directory tree, supports nested files. The difference is the filename and the audience. AGENTS.md targets any agent. CLAUDE.md targets Claude Code specifically.
Anthropic added AGENTS.md support to Claude Code in 2025 as a fallback — if no CLAUDE.md is present, Claude Code will read AGENTS.md. This is the migration bridge.
| CLAUDE.md | AGENTS.md | .cursor/rules | |
|---|---|---|---|
| Primary tool | Claude Code | Codex, Cursor, Aider, Continue, others | Cursor |
| Format | Markdown | Markdown | Markdown (one file per rule) |
| Auto-loaded | Yes — walks tree, plus ~/.claude/CLAUDE.md |
Yes — walks tree | Yes — .cursor/rules/*.mdc |
| Nested files | Yes | Yes | Yes (one rule per file) |
| Read by Claude Code | Yes (primary) | Yes (fallback) | No |
| Read by Cursor | No | Yes | Yes |
| Read by Codex | No | Yes | No |
| Imports / includes | @path/to/file syntax |
Plain Markdown links | Frontmatter globs: field |
| Length sweet spot | Under 200 lines | Under 200 lines | One rule per file, scoped |
The honest read: AGENTS.md is the better default for any team with more than one agent in play, and that's now most teams. CLAUDE.md retains an edge if you're fully committed to Claude Code and want the @import syntax for splitting large memory across files.
.cursorrules and current .cursor/rules/Cursor went through two formats. The old one was a single .cursorrules file at the repo root — basically their version of CLAUDE.md. It's deprecated but still read for backward compatibility.
The current Cursor format is .cursor/rules/*.mdc — one Markdown file per rule, with YAML frontmatter that scopes when each rule applies:
---
description: "Database conventions"
globs: ["src/db/**/*.ts", "prisma/**"]
alwaysApply: false
---
- Use Prisma for all queries. No raw SQL except in `prisma/seed.ts`.
- Migrations must be reversible. No `DROP COLUMN` without a paired `ADD`.
- Always commit `prisma/schema.prisma` and the generated migration together.
This is genuinely better than a giant single file for large codebases — rules attach to file globs, so Cursor only injects the database rules when you're editing database code. But it's Cursor-specific. Other tools won't read it.
If your team is Cursor-only, .cursor/rules/ is the right format. If anyone else on the team uses Claude Code or Codex, you'll duplicate work — which is the case for the migration path below.
Windsurf (Codeium) reads .windsurfrules at the repo root and global_rules.md from its user config dir. Same pattern. Same content. Different filename.
Aider reads .aider.conf.yml plus any conventions you load via --read CONVENTIONS.md. Continue reads .continue/config.json plus a systemMessage. Each one reinvented the format.
This is exactly the fragmentation AGENTS.md was created to solve. As of late 2025, most of these tools either read AGENTS.md natively or have a documented path to point at it.
Use only CLAUDE.md if:
@import syntax to split memory across filesCLAUDE.md snippetsUse only AGENTS.md if:
Run both if:
@import features plus cross-tool reachThe "run both" pattern is what I do on most repos. Keep AGENTS.md as the canonical document. Make CLAUDE.md a one-liner:
# Project memory
@AGENTS.md
## Claude Code only
- When committing, always run `pnpm typecheck` before `git commit`
- Prefer `rg` over `grep`; never invoke `find` (slow on this monorepo)
Claude Code reads CLAUDE.md, expands the @AGENTS.md import, and appends the Claude-only section. Other tools read AGENTS.md directly and ignore the Claude file.
The migration is mechanical. Three steps:
Rename or copy. cp CLAUDE.md AGENTS.md. If you want both, keep both. If you're going pure AGENTS.md, replace CLAUDE.md with the one-liner import above.
Strip Claude-specific syntax. If your CLAUDE.md uses @import to pull in other files, AGENTS.md doesn't have that. Inline the imports or use Markdown links and let the agent fetch.
Test in both tools. Open the repo in Claude Code, run a real task, confirm it picks up the rules. Then do the same in Cursor or Codex. If a rule isn't being followed, it's usually because it's buried past line 200 or stated abstractly. Specific rules survive; vague ones don't.
If you've accumulated months of memory in a single bloated CLAUDE.md, the trim tool will cut the dead weight before you migrate. Migrating a 600-line file produces a 600-line file in the new format — same problem, new filename.
The real reason teams end up with three memory files: nobody wants to redo the work. So .cursorrules exists from 2024, CLAUDE.md got added in 2025, AGENTS.md got added later that year. All three drift.
Two patterns work. First — pick one canonical file (AGENTS.md is the right pick in 2026) and make the others symlinks or import shims. Second — generate the tool-specific files from a single source via a pre-commit hook. The first is simpler and survives contact with reality.
Whatever you pick, the principle is the same: one file gets edited, others get derived. The moment you have two files that both accept edits, you have two sources of truth and neither will be correct.
Does Claude Code read AGENTS.md?
Yes, as a fallback. If CLAUDE.md is absent, Claude Code reads AGENTS.md from the same locations. If both exist, CLAUDE.md wins and AGENTS.md is ignored unless you @import it.
Can I use AGENTS.md and .cursor/rules together?
Yes. Cursor reads both. .cursor/rules/*.mdc files with glob scoping take precedence for matching files; AGENTS.md applies broadly. The risk is rule conflict — if both files say something different about the same code, behavior is undefined.
What's the maximum length for CLAUDE.md or AGENTS.md?
There's no hard cap, but past 200 lines of operating instructions, agents start dropping content from context. Keep durable rules in the main file and push detailed reference material into linked sub-files.
Should AGENTS.md include secrets or API keys?
No. Both files are committed to the repo and read into the agent's context. Treat them like any other source file — no secrets, no internal URLs you wouldn't want in a code review.
How do I handle monorepos with AGENTS.md?
Put a root AGENTS.md with org-wide rules, then a scoped AGENTS.md inside each package or app folder. Agents walk the tree and concatenate. This is exactly how nested CLAUDE.md works in Claude Code.
Is there an official AGENTS.md spec?
There's no single owning body — the format emerged by convention. The closest thing to a spec is the cross-tool readme at agents.md (community-maintained). The format is intentionally loose: plain Markdown, no required sections.
If you're sitting on a CLAUDE.md that grew past 300 lines and you're not sure what to keep when migrating to AGENTS.md, CoworKit's optimizer reads your file, flags the sections that aren't pulling weight, and rewrites them into specific, durable rules. Paste your file in, get a cleaner version back, and decide what to migrate. The trim tool is the right starting point if your file is bloated. The optimize tool is the right one if it's the right length but vague. Both at coworkit.online/generator.
Practical guides and prompt patterns — no fluff, unsubscribe any time.