CLAUDE.md is the most important file in a Claude Code project. Most people write it once. It should be updated every time the agent does something you didn't want it to do.
Negative constraints outperform positive instructions
"Don't add comments to code you didn't change" prevents more problems than "write clean code."
The agent already knows how to write code. It doesn't know your specific preferences. Negative constraints are directly checkable before each action — the agent can ask "does this violate any constraint?" and get a clear yes/no.
Recovery instructions are the most underused pattern
After compaction, the agent loses conversational context but re-reads CLAUDE.md. Most CLAUDE.md files have nothing about recovery.
This changed my 72-hour run completely:
## Session Recovery
After any compaction or container restart:
read tasks/current-task.md first.
It tells you where you are and what's next.Without this: 15-20 minutes of reconstruction after every compaction. With it: 2 minutes.
Tool-specific rules beat general rules
General: "Be careful with file edits."
Specific: "Always Read before Edit. Never use Write when Edit works."
The specific version maps to actual tool calls. The agent can check it at the moment of decision.
Order by criticality, not by category
After compaction, the agent skims. Critical rules need to be at the top — not buried in section 8 under "Miscellaneous Guidelines."
My current order: non-negotiables → recovery → git rules → code conventions → API limits → human approval required.
The things most CLAUDE.md files are missing
Almost every CLAUDE.md on GitHub covers code style. Almost none cover:
- What to do when a tool call fails (error recovery)
- When to compact proactively (context management)
- External API rate limits and how to handle them
- What requires human approval before proceeding
These are where autonomous runs actually break. Code style mistakes are annoying. Missing error recovery causes infinite loops at 3am.
A working skeleton
## Non-negotiables
- Read before Edit — always use Read tool first
- Never git add -A — add specific files only
- No silent errors — log what failed and why
## Recovery
After compaction or restart: read tasks/current-task.md
## What requires human approval
[the things you don't want the agent doing unsupervised]
## Rate limits
[external APIs and their specific limits]
## Code conventions
[your stack-specific rules]The skeleton is what most people are missing. The specifics depend on your stack.