AGENTS.md vs CLAUDE.md vs INSTRUCTIONS.md

by Ray Svitla

the AI coding tool landscape has a file naming problem. every tool invented its own instruction file. none of them talked to each other about it.

here’s the current mess:

six tools, six different files, six different formats. if you use more than one tool — or if your team does — you’re maintaining parallel instruction sets.

what each file actually does

CLAUDE.md

claude code’s instruction file. TOML-like headers optional, markdown body. loaded automatically at session start. supports project-level (in your repo root) and user-level (~/.claude/CLAUDE.md) instructions.

what goes in it: stack description, key commands, coding conventions, architecture notes, common pitfalls. it’s the most flexible of the bunch — no schema, no required fields, just markdown that the model reads and follows.

hierarchy: user-level CLAUDE.md → project root CLAUDE.md → subdirectory CLAUDE.md files. more specific overrides more general.

.cursorrules

cursor’s equivalent. plain text, no specific format. lives at project root. cursor reads it to shape how the AI behaves in your project.

functionally identical to CLAUDE.md in purpose. different ecosystem. cursor also supports .cursor/rules directory for multiple rule files, which is handy for large projects.

.windsurfrules

windsurf’s version. same concept, different filename. markdown format, project root.

.github/copilot-instructions.md

github copilot’s instruction file. lives in the .github/ directory alongside your workflows and issue templates. markdown format.

this is the most “enterprise-friendly” location — it follows github’s existing conventions for project configuration. but it’s tied to github’s ecosystem in a way the others aren’t.

AGENTS.md

openai’s codex uses this. the name is more general — “agents” instead of a specific product name. it’s positioned as the instruction file for any AI agent, not just one tool.

the name is smart. AGENTS.md doesn’t tie itself to a vendor. it says: “this repo has instructions for AI agents, regardless of which agent you’re using.”

what actually matters

the filename is the least important part. what matters:

1. content quality beats file format

a great CLAUDE.md with specific commands, clear conventions, and useful architecture notes will outperform a mediocre AGENTS.md every time. the model doesn’t care what the file is called. it cares what’s inside.

2. one source of truth

if you maintain CLAUDE.md, .cursorrules, and .windsurfrules separately, they will drift. guaranteed. by the third month, one will say “use vitest” and another will still say “use jest” because you forgot to update all three.

pick one as your source of truth. generate the others from it, or symlink them:

# one file to rule them all
ln -s CLAUDE.md .cursorrules
ln -s CLAUDE.md .windsurfrules

this works because all these files are just markdown that the model reads. they don’t have incompatible schemas (mostly).

3. the convergence is inevitable

five years from now, these will probably all be the same file. the industry is converging on “markdown file at project root that tells AI agents how to behave.” the current naming fragmentation is a temporary coordination failure.

AGENTS.md has the best name for this convergence because it’s vendor-neutral. CLAUDE.md ties you to anthropic. .cursorrules ties you to cursor. AGENTS.md says “this is for any agent.”

4. layer your instructions

the best setup regardless of tool:

AGENTS.md (or CLAUDE.md)     → project-level defaults
docs/architecture.md          → detailed architecture (referenced, not @-included)
src/auth/AGENTS.md            → module-specific instructions

root file has the essentials. subdirectory files have module-specific instructions. detailed docs are referenced but not auto-loaded (to save tokens).

the practical recommendation

if you use only claude code: CLAUDE.md. it’s what the tool looks for natively.

if you use multiple tools: create AGENTS.md as your source of truth and symlink or copy to tool-specific files. keep one authoritative version.

if you’re starting fresh: AGENTS.md. the name is better, it’s vendor-neutral, and if the ecosystem converges on a standard, this is the most likely candidate.

regardless of filename, the principles are the same:

→ keep it under 500 words → specifics over aspirations → commands, conventions, architecture — in that order → review it monthly → every line should change the agent’s behavior

the file that makes your AI agent useful isn’t the one with the right name. it’s the one with the right content.

→ why your CLAUDE.md sucks — anti-patterns in instruction files → agent-first design — structure repos for AI agents → CLAUDE.md guide — the definitive CLAUDE.md guide

Ray Svitla stay evolving