Most CLAUDE.md files are context dumps.
They tell Claude what the project is. Stack. Directory structure. What not to touch. Maybe some formatting preferences.
That's a README. It's useful, but it's not an operating system. And the gap between a context dump and an actual operating layer is where most Claude Code setups leave performance on the table.
What CLAUDE.md is actually for
Every Claude Code session starts by reading CLAUDE.md. Not reading the git log. Not reading recent files. CLAUDE.md first.
This makes it the most leveraged place in your entire setup. Whatever Claude reads in that file sets the frame for the entire session — how to approach work, what rules apply, what tools to reach for, what authority it has.
If that file is just context, Claude shows up as a context-aware assistant. If that file is an operating system, Claude shows up as an agent with defined behavior, authorized capabilities, and a structured way of working.
The difference isn't subtle.
The five components of a working CLAUDE.md
1. Identity block
Who is Claude in this project? What is it authorized to do?
This isn't about personality. It's about decision authority. A CLAUDE.md that says "you are a helpful assistant working on this Next.js project" produces different behavior than one that says "you are authorized to create, edit, and delete files within this directory, select implementation approaches without asking, and run terminal commands as needed. When uncertain between approaches, surface options with tradeoffs — don't decide silently."
The identity block defines how autonomous Claude operates in this context.
2. Hard rules
Non-negotiable behaviors. Things Claude must always do and things it must never do.
Examples that belong in rules:
- Never commit
.envor credential files - Always confirm before force-push or reset --hard
- Every correction gets checked for similar instances elsewhere in the codebase
- Never show pricing on ICP landing pages
Rules are the difference between a CLAUDE.md that describes a project and one that governs behavior in that project. Most CLAUDE.md files have zero rules. They have plenty of description.
3. Power flags
This is the most commonly missing section and the one with the highest impact per line of text.
Claude Code has features that aren't in the official documentation and aren't in the default behavior. If they're not documented in CLAUDE.md, Claude won't use them unprompted. Here's what belongs in this section:
--effort max → complex work, client deliverables, architectural decisions
--effort low → quick lookups, simple edits, status checks
--worktree / -w → isolated git branch per session (safe parallel work)
CLAUDE_CODE_COORDINATOR_MODE=1 claude → parallel agent execution
Once these are in the file, Claude reaches for the right tool without being asked. A hard architectural decision gets --effort max automatically. A batch of parallel tasks routes through coordinator mode.
Without this section, every session runs at the default parameters regardless of what would actually be appropriate for the work.
4. Project context
This is the part most CLAUDE.md files do reasonably well. Stack, directory structure, key files, conventions, what not to touch.
The one thing most files get wrong: they describe the architecture but don't describe the current state. A good context block includes:
- What's actively being worked on
- What's in progress vs. what's stable
- Where the highest-risk code lives
- What changed recently that Claude should know about
Some of this belongs in memory files rather than CLAUDE.md itself. CLAUDE.md should point to where the dynamic state lives, not try to capture all of it.
5. Session start ritual
A set of instructions Claude runs at the beginning of every session.
The minimal version:
At session start: read memory files, check git log for recent changes,
run /env to inspect active environment, identify current priority.
Without this, every session starts cold. Claude doesn't know what happened in the last session, what's changed in the repo, or what the current focus is. With a session start ritual, Claude arrives oriented.
The /env command is worth calling out specifically — it's one of the 26 hidden slash commands in Claude Code. It inspects the active environment variables so Claude can see what's actually running, not what's theoretically configured.
How to audit your own CLAUDE.md
Read it and ask: does this file govern behavior, or does it describe context?
The fast version:
- Does it have explicit rules (must/never)? If no → missing the governing layer
- Does it document
--effort,--worktree, coordinator mode? If no → defaulting to basic mode every session - Does it have a session start block? If no → every session starts cold
- Is there a section on current priorities or active work? If no → Claude doesn't know what matters right now
The five-component checklist is the structure. The audit tells you which components are missing.
What fixing it actually looks like
The power flags section is one afternoon of work. Pull the relevant flags for your workflow, document them with when-to-use notes, commit the file.
The session start ritual is three lines.
The rules section requires thinking through what you actually care about in this project — what behaviors matter enough to be non-negotiable. That's a 30-minute conversation with yourself. The result is a paragraph.
The identity block is the most important component and the easiest to write. It's just: what is Claude authorized to do in this project? Write it explicitly.
Most CLAUDE.md files get better with less content, not more. The ones that are 800 lines of context get skimmed. The ones that are 150 lines of operating system get followed.
The thing most guides miss
CLAUDE.md is not static documentation. It's the active configuration layer for a running system.
When Claude makes a mistake and you correct it, the correction belongs in CLAUDE.md — not just in the conversation, not just in memory, but in the operating layer that governs future sessions. Every correction is a flywheel input. The file gets better as you work with it.
This is the compounding part. A CLAUDE.md that gets updated after every session is a materially better operating system six months from now than one that was written once and never touched.
The free audit tool at vibetokens.io/tools/claude-code-audit checks your settings.json for the six configurations most setups are missing. If you want the full kit — settings pre-configured, master CLAUDE.md template with all five components built in and coordinator mode wired, session rituals, hooks, automation scripts — that's OPERATOR.
The template is the part that takes the most time to get right on your own. We've done that iteration already.
