CLAUDE.md — The Map You Draw for Your AI
Core idea: CLAUDE.md is the persistent instruction and memory file that tells Claude Code how your project works and how you want it to behave.
Think of it as a map + constitution + guardrail system for your AI teammate.
What You Will Learn
- Why CLAUDE.md matters
- Guardrails, not manuals
- What belongs in CLAUDE.md
- What should stay out
- The CLAUDE.md hierarchy
- How to use @ imports safely
- A practical project example
- Auto Memory vs. handwritten CLAUDE.md
- The iterative flywheel
- How to create your first CLAUDE.md
- Common mistakes and fixes
- Practice, revision questions and memory map
1. The Main Idea
Claude Code can inspect your files and understand a project, but every new session still needs reliable project-specific rules. That is where CLAUDE.md comes in.
The book describes it as more like a contract than a manual: the things you and Claude have agreed about how to work together live there. Claude Code reads the file when a new conversation starts.
2. Why Is CLAUDE.md So Important?
Imagine joining a new company on your first day. You know programming, but you do not know:
- which commands the team uses,
- which testing framework they prefer,
- which architectural decisions are intentional,
- which mistakes must never be repeated,
- or which coding conventions are specific to this project.
Without project instructions, Claude has to discover these things repeatedly. With CLAUDE.md, the important project rules are available at the beginning of a session. The source calls the root CLAUDE.md the agent's “constitution” and primary source of truth for the codebase.
3. The Big Mistake: Writing an Encyclopedia
A beginner may think:
That is the wrong direction. A huge file consumes context before Claude even starts doing the actual task. The source specifically warns against turning CLAUDE.md into an encyclopedia and notes that Boris's team keeps its core rules file around roughly 2,500 tokens.
4. Guardrails, Not Manuals
The recommended strategy is to start small and grow the file from real mistakes.
This creates a useful feedback loop. Instead of guessing what rules might be needed, you add rules when the project gives you evidence that they are needed.
5. What Actually Belongs in CLAUDE.md?
The source gives a very useful test:
If Claude can figure it out from the code, don't write it.
If Claude cannot reasonably guess it, write it.
| Write This | Usually Don't Write This |
|---|---|
| Custom Bash/build commands Claude cannot guess | “This is a React project” when the code already makes that obvious |
| Project-specific code style preferences | Normal language conventions Claude already knows |
| Test commands and preferred testing framework | Full API documentation pasted into the file |
| Architectural decisions and their context | Frequently changing information |
| Development-environment quirks | File-by-file descriptions Claude can discover |
| Common mistakes and how to avoid them | Generic filler such as “write clean code” |
This distinction is directly based on the source's “Write This / Don't Write This” guidance.
6. Good Rules vs. Weak Rules
Weak rule
Better rule
Why is the second better? It gives Claude a replacement path. A rule should not merely block an action when the correct alternative can be stated clearly.
7. Don't @ Import Huge Documents
CLAUDE.md supports an @ import syntax for pulling other files into the instruction context:
But the source warns that referenced files can be fully embedded into context. Import only short files that genuinely need to be available every session. For a large document, it is better to point Claude to the path and tell it when to read that document.
8. CLAUDE.md Has a Hierarchy
CLAUDE.md is not limited to one file. The source describes a layered structure:
| Level | Example | Purpose |
|---|---|---|
| Global | ~/.claude/CLAUDE.md | Personal preferences shared across projects |
| Project | ./CLAUDE.md | Project rules shared with the team |
| Subdirectory | ./src/CLAUDE.md | Rules for a particular module |
| Deeper directory | ./src/api/CLAUDE.md | More specific rules for a nested area |
The hierarchy is especially useful in monorepos where frontend and backend areas may need different conventions.
How to think about the levels
“How I generally like to work.”
“How this team/project works.”
“How this specific module works.”
“Rules specific to this smaller area.”
9. A Good Project-Level CLAUDE.md
The book provides a concise example. The important idea is not to copy it blindly, but to understand its structure.
The source's actual example is intentionally short: architecture, commands, code style, pitfalls, and “don't” rules.
10. Use CLAUDE.md to Simplify Your Project
There is a deeper lesson in the chapter: if a command is so complicated that it takes several paragraphs to explain in CLAUDE.md, the command itself may be too complicated.
The source suggests creating a simple Bash wrapper with a clean interface and documenting that wrapper instead. In other words, good documentation can reveal bad interfaces.
Instead of documenting a long, fragile deployment command with many flags, create a project command such as
./scripts/deploy.sh and teach Claude that one clear command.
11. Auto Memory: What Claude Remembers Automatically
The book also describes an automatic memory system that works alongside the CLAUDE.md you write yourself.
When you correct Claude with preferences such as “use English for commit messages” or “put tests in a particular directory,” the source says Claude can save such preferences automatically for future sessions. These memories are stored under:
Auto Memory and CLAUDE.md serve different purposes.
| Hand-written CLAUDE.md | Auto Memory |
|---|---|
| Team-shared rules | Personal preferences |
| Checked into Git | Stored locally |
| You maintain it | Claude maintains it automatically |
| Structured and deliberate | Informal accumulated memory |
12. The Iterative Flywheel
The most important long-term idea in this chapter is that CLAUDE.md becomes better through use.
Basic architecture and commands. Claude still makes many mistakes.
You begin recording real mistakes as rules.
The rules become more useful and corrections decrease.
Add useful rules, remove outdated ones, keep the file lean.
The source's one-sentence summary is: start small, add a rule when something goes wrong, keep CLAUDE.md lean, and check it into Git when it contains team-shared project rules.
13. A Simple Workflow for Building Your CLAUDE.md
- Start with a small file.
- Add the project's key architecture and development commands.
- Add important coding conventions that are specific to your project.
- Add verification/testing commands.
- When Claude makes a repeatable mistake, turn the lesson into a rule.
- Remove rules that are no longer useful.
- Keep the file short enough that it does not become a context burden.
- For team rules, keep the project CLAUDE.md in Git.
Create one in a project
The book's exercise specifically recommends running /init, opening the generated CLAUDE.md, and adding three rules of your own.
14. Example: Turning a Mistake Into a Rule
Suppose Claude repeatedly installs new dependencies without asking.
Now the lesson does not need to live only inside one conversation. It becomes part of the project's durable instructions.
15. Common Beginner Mistakes
Fix: Keep only information Claude cannot reliably infer.
Fix: Treat the file as a living document.
Fix: State concrete project-specific behavior.
Fix: Reference their path and load them when needed.
Fix: Explain the preferred alternative.
Fix: Put important, durable constraints in CLAUDE.md because conversation context can be compressed.
16. CLAUDE.md vs. Conversation
| Conversation | CLAUDE.md |
|---|---|
| Good for the current task | Good for durable project rules |
| Can become long | Should stay concise |
| Context can be compressed | Read fresh at session start |
| Temporary decisions can live here | Important repeated decisions belong here |
17. Interview / Revision Questions
- What is CLAUDE.md?
- Why is CLAUDE.md compared with a constitution or project map?
- Why should CLAUDE.md be short?
- What is the “if Claude can figure it out from the code” rule?
- Give three examples of things that belong in CLAUDE.md.
- Give three examples of things that generally should not be put there.
- What is the difference between global, project-level and subdirectory-level CLAUDE.md?
- Why should you be careful with @ imports?
- What is Auto Memory?
- How is Auto Memory different from handwritten CLAUDE.md?
- Explain the iterative flywheel.
- Why is a rule like “use X instead of Y” better than only “never use Y”?
18. Practice — Try It Yourself
Open any project, run /init, and add three rules that are actually useful for that project.
Ask Claude to make a small change. If it makes a mistake, correct it and convert that correction into a CLAUDE.md rule.
Start a fresh session and ask Claude about the project. Notice how much project knowledge is available through the project files and CLAUDE.md without repeating the same background.
19. Quick Memory Map
CLAUDE.md = Project Memory + Rules + Guardrails
Keep it lean → learn from mistakes → update continuously.
20. Final Takeaway
CLAUDE.md changes the relationship between you and Claude Code. Instead of explaining the same project rules in every session, you build a persistent set of instructions that travels with the project.
The key is not to write the biggest possible file. The goal is to create the smallest useful set of guardrails: the commands Claude cannot guess, the decisions that matter, the project-specific conventions, and the lessons learned from real mistakes.
Over time, the file becomes more valuable because every useful rule captures a lesson. That is the chapter's central flywheel: