Boot context. What loads automatically, where it lives, size tradeoffs, and how to design it well.
What CLAUDE.md Actually Is
If you've used Claude in a project folder, you may have noticed a file called CLAUDE.md in your workspace. It looks like a normal Markdown file. But what it does is fundamentally different from any other file Claude can read.
CLAUDE.md is the only file Claude reads before you say a single word.
Every other document — attached files, tool outputs, knowledge bases — gets loaded in response to something happening. CLAUDE.md loads automatically, every session, before the conversation begins. It's not retrieved. It's not searched. It's injected directly into Claude's context window as part of the boot sequence.
Analogy
CLAUDE.md is your employee handbook — except the employee reads the entire handbook before their first conversation of every single workday.
Most companies hand an employee a handbook once and expect them to remember it. Claude gets the opposite deal: perfect recall, every time, but only of what's in that file. If something isn't written there, it doesn't exist at session start.
The Phase 1 connection: In Phase 1 Session 2, you saw the boot sequence — system prompt → CLAUDE.md → conversation history → your message. CLAUDE.md sits right after the system prompt. That prime position in the context window means it gets maximum attention weight (Session 5). Location matters.
Anatomy of a CLAUDE.md
A well-designed CLAUDE.md has distinct sections that each serve a specific purpose. Click any block below to see what it does and why it belongs at boot time.
🏷️
## IDENTITY # Who Claude is in this context. Role name, session type, what machine it runs on.
IDENTITY
🎯
## Primary Role # Core responsibilities. What this Claude instance actually does.
ROLE
🔧
## Tools Connected # MCPs, integrations, what's available right now. Tool gotchas and quirks.
TOOLS
⚡
## Shorthand Commands # "check inbox" means X, "deploy" means Y. Custom vocabulary for this workspace.
SHORTCUTS
📎
@.claude/rules/hard-rules.md @.claude/rules/session-protocol.md # @-imports pull in modular rules files at load time.
@-IMPORTS
📖
## Lessons Learned (rolling, max 10) # Recent discoveries that need to be front-of-mind. Dated, capped.
Click any colored block to see what it does, why it belongs in CLAUDE.md (or why it doesn't), and how to write it well.
The Token Cost Reality
Every token in your CLAUDE.md is a token not available for your conversation, tool outputs, or Claude's response. CLAUDE.md doesn't just sit there — it fills the context window. The tradeoff is real.
The calculator below shows how your configuration choices affect your available context. Drag the sliders to see the impact.
Model context
System prompt
2,000
CLAUDE.md size
3,000
Conversation history
5,000
Context window allocation
System
CLAUDE.md
History
Available
System prompt
CLAUDE.md
Conversation history
Available for response + tools
0
Tokens used by config
0
Tokens free for work
0%
Config overhead
⚠️ Warning: Your configuration is consuming over 50% of the context window. Conversations will get expensive fast, and compaction will kick in sooner. Trim your CLAUDE.md.
The counterintuitive truth: More isn't better. A bloated CLAUDE.md with vague filler instructions costs tokens AND reduces attention quality. Every line competes with every other line. A tight, specific 2,000-token CLAUDE.md beats a sprawling 8,000-token one almost every time.
The @-Import System
CLAUDE.md doesn't have to contain everything directly. Claude supports @-imports — special lines that pull in other Markdown files at load time, as if you'd copy-pasted them inline.
You can update a rules file without touching CLAUDE.md. Less risk of accidentally breaking something important.
Readability
CLAUDE.md stays as a clear table of contents. Rules stay in their own dedicated files.
Selective loading
Different Claude deployments can share some rules files but not others. Marketing rules live in their own file and only load for the right session.
Version control
Git diff on hard-rules.md shows exactly what changed. Easier to audit.
Important: @-imports are loaded at the same priority as CLAUDE.md itself. They're not "secondary" — they're all part of the same boot context. The token cost applies to everything imported, so the budget math applies to your full import tree, not just the root file.
Where Does This Information Belong?
The most common CLAUDE.md mistake is putting everything in it. Use this decision tree to figure out the right place for any piece of information.
What kind of information is this?
Lean vs. Bloated — Side by Side
Both examples below are trying to accomplish the same thing: tell Claude how to handle client emails. One does it in ~40 tokens. One does it in ~200 tokens, and it's worse.
❌ Bloated (~200 tokens)
~200 tok
Vague opener
When clients send emails, you should always be professional and try your best to handle their questions and concerns in a helpful and timely manner. Client satisfaction is very important.
~45 tokens — says nothing actionable
Undefined threshold
If the email seems urgent, try to prioritize it. If something is above your capabilities, escalate appropriately to the right person.
~35 tokens — "seems urgent" and "appropriately" are guesses
Redundant reminder
Remember to be careful with client data and always make sure you're following our privacy guidelines. Never share anything you shouldn't.
~38 tokens — "shouldn't" is undefined
Aspirational noise
Always aim to leave clients with a positive impression of our company and our commitment to excellent service.
~28 tokens — zero behavioral change
✅ Lean (~42 tokens)
~42 tok
Clear trigger
Client emails: reply within 4 hours during business hours (9am–6pm CT). After hours = next morning.
~22 tokens — completely unambiguous
Specific escalation
Escalate to Sarah if: billing dispute, churn risk, or legal mention. Tag #urgent in Slack.
~20 tokens — three defined triggers, one action
The vague instruction problem: "Be professional" and "handle urgency appropriately" don't change Claude's behavior — they just burn tokens. Claude's default behavior is already professional. You only need to write what differs from the default, and you need to write it specifically.
The Five Most Common CLAUDE.md Mistakes
MISTAKE 1
Dumping everything in. CLAUDE.md is boot context, not a filing cabinet. If Claude doesn't need to know it in the first 30 seconds of every session, it doesn't belong here. Put reference material in a knowledge base instead.
MISTAKE 2
Writing aspirations instead of rules. "Always prioritize client satisfaction" is not a rule — Claude already does that. "Never respond to a complaint without first reading the client's contract" is a rule. Aspiration doesn't change behavior. Specificity does.
MISTAKE 3
Burying critical rules at the bottom. From Phase 1 Session 5: attention weight is highest at the top and bottom of a document, lowest in the middle. Your most important behavioral rules belong in the first 20% of your CLAUDE.md.
MISTAKE 4
No structure, just a wall of text. Markdown headers create semantic anchors. Without them, your CLAUDE.md is a blob that Claude processes as a continuous flow. Section headers tell Claude "this next part is about X" — that context matters.
MISTAKE 5
Setting it and forgetting it. CLAUDE.md should evolve. When something goes wrong that you had to correct, add the lesson to Lessons Learned (capped at 10). When a tool changes behavior, update the gotchas section. Stale CLAUDE.md = stale behavior.
DESIGN PRINCIPLE
Write what differs from defaults. You don't need to tell Claude to be helpful, accurate, or professional — those are defaults. Every line in CLAUDE.md should answer: "What would Claude get wrong without this?" If the answer is "nothing," cut the line.
The Binary Test for Every Line
Before adding any line to CLAUDE.md, run it through this test:
"What would Claude have to guess to follow this instruction?"
BEFORE (requires guessing)
"Respond quickly to urgent things"
Guesses needed: what counts as urgent? what does quickly mean? what things?
AFTER (no guessing needed)
"Respond within 1 hour to any email with 'urgent' or 'down' in the subject"
Zero ambiguity. Claude knows exactly when and how to act.
Every guess is a gap. If Claude has to guess to follow your instruction, you haven't written the instruction — you've written a hope. Hopes don't reliably survive context changes, different conversations, or long sessions where attention dilutes.
PHASE 2 — SESSION 2
Next: Rules Files
You've seen how @-imports work. Next session digs into the rules files themselves — hard rules vs. soft guidelines, how to structure them for maximum Claude attention, and when modular beats monolithic. Includes: the session protocol pattern, marketing rules anatomy, and designing rules files that actually change behavior.
After Session 2, you'll understand why some rules hold and others quietly get ignored — and how to write ones that stick.