How I Structure CLAUDE.md After 1000+ Sessions
I've rewritten this file from scratch four times. Here's what survived.
The first CLAUDE.md I wrote was three lines.
You are a helpful assistant. Be concise. Help with code.
That was ten months ago. Today mine is 472 lines split across two files. The agent using them has built apps, deployed to production, written blog posts, and run autonomous overnight sessions without me watching.
Most of those 472 lines exist because I wrote the wrong version first.
Here's what I've learned.
What CLAUDE.md Actually Is
Not a prompt. That's the first wrong model.
A prompt is what you write when you want a specific output. CLAUDE.md is closer to a role definition — the rules of engagement for every session, every task, every edge case you can anticipate.
Claude Code reads CLAUDE.md at the start of every session. It reads it again when you mention relevant topics. It uses it as a reference point when deciding how to behave in ambiguous situations.
If your agent does something surprising, it's either following CLAUDE.md instructions you forgot you wrote, or it's filling in a gap you didn't cover. Both are CLAUDE.md problems.
The Two-File Architecture
This took me three rewrites to figure out.
Global file (~/.claude/CLAUDE.md): Who the agent IS.
- Identity, personality, core values
- Communication style
- What the agent won't do
- General behavioral rules
Project file (/your-project/CLAUDE.md): What the agent DOES.
- Specific capabilities and tools
- Infrastructure details (server addresses, API endpoints)
- Project structure and file locations
- Task execution rules
The mistake I kept making was putting everything in one place. Identity leaked into project specifics. Commands were mixed with philosophy. The agent got confused about what was a rule versus what was context.
Separation solves this. Global = constant. Project = contextual.
The Sections That Survived
After iterations, my global CLAUDE.md has six sections that I don't touch anymore:
Core values — four principles that settle most ambiguous decisions without me having to be there. I have: Action Over Words, Clarity Over Noise, Evolution Over Consistency, Your Tool Not Your Crutch. These aren't decoration. When the agent is deciding whether to ask me for confirmation or just do the thing, it checks these.
Capabilities matrix — a table mapping trigger phrases to what the agent should do. "generate image" → use Gemini. "deploy" → SSH to DigitalOcean. This is the routing layer. Without it, the agent improvises.
Behavioral rules — explicit DO and DON'T lists. "Never take irreversible external actions without confirmation." "Never plan without executing." These overrule default behavior in edge cases.
Communication style — how the agent writes back to me. "Brief, direct, action-oriented. Show results, not process descriptions." This one took me a while because I kept getting back verbose explanations that I didn't need and wouldn't read.
Memory and rollover instructions — how to manage the tiered memory system. Without explicit instructions here, the agent either remembers everything (memory bloat) or nothing (repeated mistakes).
Decision rules — when uncertain, choose action over asking. Concise over verbose. Automation over manual. These are tiebreakers.
What I Tried That Didn't Work
Long lists of specific instructions — I spent a week writing a 200-line list of edge cases. Specific behaviors for specific situations. It failed because I can't anticipate everything, and a long list with exceptions creates conflicts. Better to write principles.
Personality instructions that weren't grounded in behavior — "Be thoughtful and curious!" is useless without translating to behavioral rules. What does "thoughtful" mean when deciding to ask before deleting a file? Write the behavior, not the trait.
Commands in the global file — for a while I had deployment instructions, server credentials, and project structure in CLAUDE.md. Every project session started with the agent reading info it didn't need. Move project-specific everything to project-level files.
No escalation rules — the agent would either ask permission for everything (annoying) or barrel through consequential decisions (dangerous). I needed explicit escalation rules: here's what you do autonomously, here's what you confirm first, here's what you never do. Without this, the agent guesses.
What Good Instructions Actually Look Like
I'll show you the same instruction written badly and well.
Bad:
Be careful with important actions. Think before doing something risky.
Good:
Reversibility tiers:
- Reading files, research, drafting → always autonomous
- Editing files, git commits → autonomous for reversible changes
- Pushing to remote, deploying → confirm first
- Deleting data, force-push, production DB changes → always confirm
When uncertain, choose the more reversible option and tell me what you chose.
The bad version asks the agent to use judgment about "risky." The good version defines the categories explicitly. After 10 months, I've learned that every time I write an adjective without a behavioral definition, I'm leaving something to chance.
"Be thorough" is an adjective. "Before claiming work is complete, run it and show me the output" is a behavioral definition.
The difference shows up in edge cases. Always in edge cases.
The Patterns That Stick
After 1000+ sessions, the instructions that produce consistent results:
Principle beats rule — "Prefer reversible actions" works better than a list of prohibited commands. The agent generalizes from principles. It can't generalize from an incomplete list.
Show don't tell — "Before claiming work is complete, run it and show me output" is better than "be thorough." Concrete behavior beats abstract quality standards.
Explicit failure modes — tell the agent what to do when things go wrong. If a command fails, try X then Y. If that fails, report the error and stop. Without this, the agent improvises failure handling, which is usually wrong.
Tiered autonomy — different action types get different rules. Reading files: always autonomous. Editing files: autonomous for reversible changes. Pushing code: confirm. Deleting data: always confirm. Explicit tiers prevent the all-or-nothing problem.
The Thing Nobody Told Me
CLAUDE.md is not a one-time setup. It's a living document.
Every time the agent does something unexpected, that's a CLAUDE.md gap. Every time I correct the agent, I update CLAUDE.md. Every time I notice a pattern in how sessions go wrong, I add a rule.
After 10 months, my CLAUDE.md reflects 10 months of learning what this specific agent, doing these specific tasks, in this specific environment, actually needs.
The agent gets better with every update. Not because the model changed — because the instructions got more precise.
That's the actual work. Not prompting. Instruction design.
What's in the AI Agent Blueprint
If you want to skip the 10 months of iteration, the AI Agent Blueprint has the actual templates.
Both CLAUDE.md files — global and project-level — annotated with explanations for each section. The three-tier memory system with rollover rules. The skill creation framework with 10+ real skill examples. The sub-agent orchestration patterns I use for parallel research and background tasks. And the self-improvement systems — error registry and lessons log — that make the agent learn from mistakes.
$29. Available at wiz.jock.pl/store.
Free for paid Digital Thoughts subscribers.
The Blueprint isn't theory. It's the actual files that run my agent — with comments explaining why each piece is there.
Top comments (0)