CLAUDE.md

Boris Cherny, who created Claude Code at Anthropic, describes CLAUDE.md as a feature that was noticed rather than designed: like plan mode, it came from watching users already improvise it. The file is read at the start of every session, which is what separates it from a prompt.

The habit the Claude Code team repeats most often is a ratchet: after Claude makes a mistake, ask it to write the correction into CLAUDE.md so the error is not repeated. Cherny finds Claude unexpectedly good at drafting its own rules. Michael Nuñez reports the team keeps one CLAUDE.md in its git repository, each error becoming a permanent rule; Kieran Klaassen ends each delivery cycle by codifying a single learning there.

Louis Claxton places the file inside a wider split of institutional knowledge into versioned artifacts: CLAUDE.md for repository context, REVIEW.md for review doctrine, bands.yaml for production thresholds. The same division runs through Anthropic's review pipeline, where CLAUDE.md describes the project and REVIEW.md, written by the code owners, tells the reviewer what matters. Against skills the line is frequency: CLAUDE.md holds what applies every time.

Cobus Greyling reads the file as evidence of a collapsing layer: natural-language instructions in a CLAUDE.md have displaced orchestration frameworks such as LangGraph and CrewAI. Shubham Saboo names the cost in his case for Loop Engineering: the file lengthens, criteria shift without a trace, and a month on the agent seems worse while the model has not regressed. The append-after-every-correction habit and the drift are one mechanism.