CLAUDE.md is a project-level configuration file that gives Claude Code persistent context about a repository’s purpose, structure, rules, and workflows — turning it from a generic assistant into a project-aware collaborator.
Overview
When developers first use Claude Code, the natural instinct is to write detailed prompts for each task. This works, but it means repeating yourself constantly — explaining the project structure, naming conventions, testing requirements, and architectural decisions every single session. CLAUDE.md solves this by giving Claude a persistent memory file it reads automatically at the start of every interaction.
The file sits in the root of a repository (or in subdirectories for module-specific guidance) and acts as a compact briefing document. Think of it less as a prompt and more as onboarding documentation — the kind of context you’d give a new team member on their first day. The key insight, articulated by Shraddha Bharuka, is that structure is permanent while prompting is temporary.
What goes in a CLAUDE.md
A well-structured CLAUDE.md covers four things:
The Why — a one-paragraph statement of what the project does and why it exists. This shapes every decision Claude makes about tradeoffs and priorities.
The Map — where things live. Key directories, entry points, config files, and any non-obvious file organisation. Claude can explore a repo itself, but giving it a map up front saves tokens and prevents wrong turns.
The Rules — hard constraints. Coding standards, forbidden patterns, required test coverage, deployment restrictions, protected directories. These are the guardrails that prevent Claude from making well-intentioned but dangerous changes.
The Workflows — how things are done in this project. Git branching strategy, PR conventions, how to run tests, deployment steps. These define the “how” once so Claude follows the same process every time.
What does not belong in CLAUDE.md
Counterintuitively, longer is not better. Liquidity Goblin reports that concise CLAUDE.md files consistently outperform verbose ones for Python repositories. The reason is mechanical: everything in CLAUDE.md consumes context window tokens on every interaction. Bloated files crowd out the actual work.
Detailed architectural documentation, ADRs, runbooks, and reference material belong in a docs/ directory that Claude can read on demand. CLAUDE.md should point to these resources rather than inlining them.
Reusable workflow instructions (code review checklists, refactoring procedures, release processes) belong in .claude/skills/ as separate skill files, not crammed into the main config.
The compounding effect
The most powerful aspect of CLAUDE.md is that it compounds over time. Kshitij Mishra describes a feedback loop pattern: every time Claude makes a mistake and gets corrected, it writes a new rule into CLAUDE.md so the error never recurs. In the first week, corrections are frequent. By month three, Claude operates like an engineer with a year of project-specific experience.
This is a fundamentally different model from traditional prompting. Rather than the developer getting better at asking, the system itself accumulates institutional knowledge.
Local CLAUDE.md files
For large repositories, a single root-level file isn’t enough. Shraddha Bharuka recommends placing local CLAUDE.md files in high-risk modules — authentication, persistence layers, infrastructure code — with just-in-time guidance specific to that area. Claude reads the root file plus any local file in the directory it’s working in, creating a layered context system.
Practical recommendations
Keep the root CLAUDE.md under 200 lines. Start with purpose, map, and two or three critical rules. Add rules organically as corrections arise — don’t try to anticipate everything upfront. Move workflow-specific instructions into skills. Treat CLAUDE.md as a living document that evolves with the project, not a static config file written once and forgotten.
Sources
- @BharukaShraddha — 4-layer structure, CLAUDE.md as repo memory, local CLAUDE.md pattern
- @liquiditygoblin — concise CLAUDE.md outperforms verbose ones for Python repos
- @DAIEvolutionHub — compounding feedback loop, week-to-month progression
- @PrakashS720 — CLAUDE.md as project memory layer
- @AnishA_Moonka — Boris Cherny interview, productivity gains context