/alternative · comparison · claude code

CLAUDE.md vs README.md: same extension, different cost domain.

Matthew Diakonov, Written with AI

Published May 21, 20267 min read

The X thread that brought you here treats these as interchangeable: "CLAUDE.md is just your README for AI." That framing collapses on the first detail. README is filesystem clutter Claude can ignore. CLAUDE.md is core context that gets re-paid for on every turn. Same bytes, different bill. This page walks the cost math, then names the one place ccmd's analyzer enforces the distinction.

1. Same .md, three things differ

Audience, load mechanism, and per-turn token cost. The other dimensions (length, style, where it lives) are downstream of these three.

Dimension	README.md	CLAUDE.md
Audience	A human developer who just cloned the repo	The Claude Code model, on every turn
Read when	Once, during onboarding (or never)	Every session start, every /compact
Enters Claude context?	No, unless explicitly imported with @README	Yes, as a user message after the system prompt
Token cost per turn	0	totalTokens of the file (chars / 4)
Target length	As long as needed; humans scroll	Under 200 lines (Anthropic's own guidance)
Voice	Narrative prose, install commands, license	Short, specific, testable directives
Survives /compact?	N/A, never loaded	Yes, re-injected from disk
What ccmd does with it	Refuses to recognize it; falls through to claude.md default	Grades against Karpathy-12 + 7-finding rubric

2. The bill, in actual tokens

Take two files of identical length: a 3,200-token README and a 3,200-token CLAUDE.md. Same bytes on disk. Now run a normal Claude Code session: 30 turns, Opus 4.7, no subagents. The math diverges from the first turn.

same 3,200 tokens, two different bills

The CLAUDE.md side uses the same chars/4 heuristic ccmd's analyzer applies at src/lib/analyzer.ts:37, plus the per-turn assumption at src/lib/analyzer.ts:264 (estimatedTokensFireEveryTurn = totalTokens), multiplied by 30 turns and Opus 4.7's $15 per million input tokens. The README side uses zero because README is not part of the session at all.

This is not a rounding-error difference. It is the entire reason ccmd exists. README length is free; CLAUDE.md length is a recurring tax. People who write a 6,000-token CLAUDE.md the way they would write a 6,000-token README burn weekly limits by Wednesday.

per session

“CLAUDE.md files are loaded into the context window at the start of every session, consuming tokens alongside your conversation.”

Anthropic, code.claude.com/docs/en/memory

3. The product refuses to grade README

The clearest evidence the two files have different purposes is what happens when you try to treat them the same. ccmd's analyzer has exactly four input types. README is not one of them:

src/lib/analyzer.ts · line 41

Paste a README into the analyzer at ccmd.dev and the function falls through to the claude.md default on line 46. The full pipeline then runs the Karpathy 12-rule rubric against your README body. That rubric was built for agent directives: it rewards short imperative lines, named tools, escape-claused absolutes, and Why: explanations on prohibitions. READMEs fail it because READMEs were never built to be that shape.

what happens when you paste a README

The score is not a bug, it is the point. The mismatch tells you the file is in the wrong cost domain. README copy that would be flagged as bloat (38-word install paragraph) is fine README and terrible CLAUDE.md. Stay in your lane and the file scores well; cross lanes and you pay tokens for the wrong shape of prose.

4. The "just symlink them" trap

Every CLAUDE.md vs README thread eventually surfaces the suggestion to symlink them, or import the README from CLAUDE.md with @README. The import syntax is real and documented; whether it is a good idea is a different question.

One file pretending to serve both audiences

Single 6,000-token README serves as both human onboarding doc and Claude's per-turn instructions. Project Title, badges, screenshots, 200-word feature list, installation steps, contributing guide, license, all of it shipped to Claude on every turn.

6,000 tok per turn
180,000 input tokens over 30-turn session
~$2.70 of Opus 4.7 input cost per session
Claude reads 'See screenshots in docs/img/' on every turn
Karpathy rubric scores 2 of 12

The savings are not a one-time cut. Every session you run for the life of the repo pays the difference. A team of five engineers each running two sessions a day on Opus 4.7 is looking at $200+ per month of input cost burned on screenshots and license text the model will never act on.

5. The one-line rule

One question, in two phrasings. Both work.

Will a human read this once? README. Install steps, what the project is, how to contribute, license, screenshots. Length does not matter; humans scroll.
Do I want Claude to follow this on every turn? CLAUDE.md. Stack, commands, conventions, past incidents, do-not-touch lists. Length does matter; under 200 lines per Anthropic's own guidance.

If a sentence answers both questions, write it twice: a human-readable version in README, a one-line testable directive in CLAUDE.md. The duplication costs you 30 seconds of editing and saves you tokens for the entire life of the repo.

Want a 10-minute pass on your CLAUDE.md and README?

Free. Paste both files in front of us, we will tell you which lines belong in which file and which lines should just be deleted.

Frequently asked questions

What is the actual difference in purpose between CLAUDE.md and README.md?

README.md is human-facing project documentation: what the project does, how to install it, how to run it, who to contact, what license it uses. The audience is another developer who just cloned the repo. CLAUDE.md is agent-facing instructions: rules and conventions you want Claude Code to follow on every turn (build commands, coding standards, do-not-touch lists, past incidents). The audience is the model. Anthropic's docs at code.claude.com/docs/en/memory describe CLAUDE.md as content that is "loaded into the context window at the start of every session, consuming tokens alongside your conversation." README has no equivalent role.

Does Claude Code ever read README.md?

Not unless you tell it to. Claude Code walks the directory tree looking for CLAUDE.md and CLAUDE.local.md files, concatenates them, and injects them into context. It does not auto-load README.md. If you want README content in context, the official docs show you have to import it from inside CLAUDE.md with the @README syntax (e.g. "See @README for project overview"). That import is opt-in. The exception is /init: running /init in a fresh project reads README.md, .cursorrules, and AGENTS.md once to draft a starter CLAUDE.md. After that, README is back to being invisible to Claude.

If they are both markdown, why not just merge them?

Two reasons. First, audience. A README that doubles as CLAUDE.md is now optimized for neither. Humans skim narrative prose; Claude responds best to short, specific, testable directives. The styles fight each other. Second, cost. A 6,000-token README that is also your CLAUDE.md ships 6,000 tokens into context on every turn, which is roughly 180,000 input tokens over a 30-turn session, or about $2.70 of Opus 4.7 input. The README content you actually need (install commands, architecture overview) is maybe 400 tokens; the rest is human-facing prose Claude is paying for and ignoring.

How does ccmd reflect this difference?

Architecturally. The detectType() function at src/lib/analyzer.ts:41 has four cases: claude.md, agents.md, .cursorrules, .grokrules. README is not one of them. If you paste a README into ccmd, it falls through to the claude.md default and gets graded against the Karpathy 12-rule rubric, which was built for agent directives. The result is high finding counts on lines that are perfectly fine README prose (a 38-word installation sentence is good README, terrible CLAUDE.md). The tool's refusal to recognize README as a valid input is the point: the file should not be measured by per-turn rules because it does not fire per turn.

What about AGENTS.md, where does that fit?

AGENTS.md is the cross-tool agent-config standard (used by Codex and other agents). Claude Code does not read AGENTS.md natively; the official workaround is a one-line CLAUDE.md that imports it with @AGENTS.md, or a symlink. Functionally it sits in the same cost domain as CLAUDE.md: agent-facing instructions, loaded into context, billed per turn. ccmd grades it with the same rubric (it's the second case in detectType). README is in a different category entirely: human-only, never loaded, zero per-turn cost.

Does CLAUDE.md survive /compact and README does not?

Yes, and this is the cleanest test of the purpose split. Anthropic's docs say project-root CLAUDE.md survives /compact: Claude re-reads it from disk and re-injects it into the freshly compacted context. README is not re-injected because it was never injected in the first place. If you run a long session that hits /compact two or three times, CLAUDE.md bills you for those re-injections; README bills you nothing. The mechanism Anthropic shipped explicitly treats one as core context and the other as filesystem clutter Claude can ignore.

Can ccmd analyze a README to tell me what to move into CLAUDE.md?

Indirectly. The flow is: paste your README, see the findings, decide which short directives the analyzer flagged (high-severity bloat on a sentence with imperative voice, missing_why on a Don't rule) are actually instructions you wanted Claude to follow. Move those few lines into CLAUDE.md, leave the install/contributing/license sections in README. The 17 findings on a typical 3,000-token README usually reduce to 3-5 lines worth promoting. The rest is README content that should not be paying per-turn tokens.

What is the one-line rule for which goes where?

If a human will read it once during onboarding, it belongs in README. If you want Claude to follow it on every turn for the lifetime of the project, it belongs in CLAUDE.md. If you find yourself wanting both audiences to see the same content (like a stack description), put the human-readable version in README and a one-line testable directive in CLAUDE.md ("Stack: Next.js 16, Postgres on Neon, deploy to Vercel from main"). Two short files beat one long file every time.

Next: the per-turn cost math in full, the Karpathy-12 rubric in full, or paste your CLAUDE.md (or your README, if you want to see the mismatch) into the analyzer.