Stop Writing README Files for Claude

The 800-line CLAUDE.md problem

• Repos with CLAUDE.md at 800 lines → reads like a company wiki.
• Contents seen → history, philosophy, style guide, contributor list, 200-line “our values” section.
• WARNING: Claude reads every token of that file on every turn.

The cost-benefit per line

• Each line in CLAUDE.md → buys something + costs something.
• Cost → context on every single turn for the rest of the session.
• Benefit → whatever behavior you’re trying to pin down.
• ! If behavior would happen anyway, or is obvious from the code → the line is pure cost.

Better shape

• Keep CLAUDE.md under ~50 lines.
• Use it for:
  • Non-obvious conventions not inferable from code.
  • Commands for build/test/lint.
  • The 1-2 “always do X, never do Y” rules that matter most.
• Everything else → file Claude can read when it needs to, not on every turn.

Lesson: every line in CLAUDE.md is a per-turn tax - charge only for behavior the code can’t teach on its own.