TL;DR
Your CLAUDE.md is a compounding system: every correction you make becomes a rule, and over time Claude's mistake rate drops. The template below mirrors the working practices Anthropic's own Claude Code team has shared - plan mode by default, subagents for research, a lessons loop, verification before anything is marked done, and a short list of core principles. Drop it into your project root and start.
Why this file matters
A good CLAUDE.md is not documentation - it is a feedback loop. Every time Claude does something wrong and you correct it, that correction gets captured as a rule, so the same mistake does not happen twice. The teams who get the most out of Claude Code keep their CLAUDE.md short (around 2,500 tokens) and update it multiple times a week. Short, specific, and always evolving beats long and static.
The template
markdown## Workflow Orchestration
### 1. Plan Mode Default
- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
- If something goes sideways, STOP and re-plan immediately - don't keep pushing
- Use plan mode for verification steps, not just building
- Write detailed specs upfront to reduce ambiguity
### 2. Subagent Strategy
- Use subagents liberally to keep the main context window clean
- Offload research, exploration, and parallel analysis to subagents
- For complex problems, throw more compute at it via subagents
- One task per subagent for focused execution
### 3. Self-Improvement Loop
- After ANY correction from the user: update tasks/lessons.md with the pattern
- Write rules for yourself that prevent the same mistake
- Ruthlessly iterate on these lessons until the mistake rate drops
- Review lessons at session start for the relevant project
### 4. Verification Before Done
- Never mark a task complete without proving it works
- Diff behaviour between main and your changes when relevant
- Ask yourself: "Would a staff engineer approve this?"
- Run tests, check logs, demonstrate correctness
### 5. Demand Elegance (Balanced)
- For non-trivial changes: pause and ask "is there a more elegant way?"
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
- Skip this for simple, obvious fixes - don't over-engineer
- Challenge your own work before presenting it
### 6. Autonomous Bug Fixing
- When given a bug report: just fix it. Don't ask for hand-holding
- Point at logs, errors, failing tests - then resolve them
- Zero context switching required from the user
- Go fix failing CI tests without being told how
## Task Management
1. Plan First: write the plan to tasks/todo.md with checkable items
2. Verify Plan: check in before starting implementation
3. Track Progress: mark items complete as you go
4. Explain Changes: high-level summary at each step
5. Document Results: add a review section to tasks/todo.md
6. Capture Lessons: update tasks/lessons.md after corrections
## Core Principles
- Simplicity First: make every change as simple as possible. Impact minimal code.
- No Laziness: find root causes. No temporary fixes. Senior developer standards.
- Minimal Impact: changes should only touch what's necessary. Avoid introducing bugs.The two sections people skip
Sections 4 and 6 are where the biggest time savings hide, and they are the ones most people leave out. Without 'Verification Before Done', Claude will happily mark things complete that are actually broken. Without 'Autonomous Bug Fixing', it will ask you fourteen questions about a bug instead of just reading the logs and fixing it. Keep both.
Make it compound
- 1Copy the block above into a file called CLAUDE.md in your project root.
- 2Create a tasks/ folder with two empty files: todo.md and lessons.md.
- 3Start working. Every time Claude makes a mistake, correct it - the self-improvement loop logs the lesson automatically.
- 4After a few sessions, your CLAUDE.md plus lessons file becomes a custom rulebook that gets better the more you use it.
Common questions
Where exactly does CLAUDE.md go?
In your project root for project-specific rules, or at ~/.claude/CLAUDE.md if you want the rules to apply across every project. Many people keep a short global file and a small per-project one; Claude reads both.
Will this template work for non-coders?
Yes. Although it uses developer language like 'CI tests', the principles - plan first, verify before done, capture lessons - apply to any work you do with Claude. You can trim the coding-specific lines if they do not fit your use case.
How long should my CLAUDE.md be?
Short. Around 2,500 tokens is a good ceiling. It loads on every session, so every line costs you tokens each time - keep only the rules you repeat constantly and push deeper context into separate files that load on demand.
What are the tasks/todo.md and tasks/lessons.md files for?
todo.md holds the current plan with checkable items so Claude tracks its own progress. lessons.md is where the self-improvement loop writes a rule every time you correct Claude, so the same mistake does not recur. Create both as empty files before you start.
How is this different from the 5 starter files?
This is a deep, opinionated version of just the CLAUDE.md file - the orchestrator. The 5 starter files guide covers CLAUDE.md plus soul, design, voice, and audience. Use this template as the CLAUDE.md inside that larger set.
Do I edit it once and leave it?
No - the whole point is that it evolves. The teams who get the most from it update their CLAUDE.md multiple times a week, adding a rule whenever Claude does something they do not want repeated. A static file stops compounding.
Want a rulebook that improves with you?
Get the other 3 in the starter stack - free, with 5,000+ builders.
Join the Club