CLAUDE.md

Boris Cherny's team at Anthropic keeps a single CLAUDE.md file in their git repository, and the rule attached to it is narrow: every time Claude makes a mistake, the mistake gets written into the file so it is not repeated. Cherny reports that Claude is unexpectedly good at drafting its own rules. Kieran Klaassen ends each delivery cycle the same way, comparing implementation against plan and codifying one learning into CLAUDE.md.

What the file holds is repository context that applies every session: commands, conventions, architecture, and the agent's recurring errors. That is the line separating it from skills, which carry procedural workflows invoked on demand. Louis Claxton of Anthropic's Applied AI team places it among versioned artifacts alongside REVIEW.md for review doctrine and bands.yaml for production thresholds, institutional knowledge kept as files under version control. The Claude Code curriculum describes four memory levels, with the project CLAUDE.md sitting between enterprise policy and the user CLAUDE.md.

The failure mode is documented too. Shubham Saboo names drift: the CLAUDE.md lengthens, evaluation criteria change without a trace, and a month later the agent seems worse though the model has not regressed. Jude Gao's evals at Vercel, run on the sibling file AGENTS.md, show the cost from the other side, since passive context is injected into the system prompt on every turn; Vercel compressed 40 KB of documentation into an 8 KB index to pay for that. A file everyone writes to and no one prunes.