What I learned about CLAUDE.md after 72 hours of autonomous Claude Code runs

I've been running Claude Code autonomously for 72+ hours. The single most impactful file in the whole setup is CLAUDE.md. Here's what I actually learned.

What CLAUDE.md actually does

Claude Code reads CLAUDE.md at session start and after every compaction. It's not a config file — it's a persistent briefing. Everything in it shapes how the agent reasons about your project.

The mistake most people make: they write it once and treat it as documentation. It should be a living document that gets updated as you learn what the agent gets wrong.

The patterns that actually matter

1. Negative constraints outperform positive instructions

"Don't add comments to code you didn't change" is more useful than "Write clean code."

"Never use git add -A" prevents more problems than "Be careful with git."

The agent knows how to write code. It doesn't know what you specifically don't want. Negative constraints are high-leverage.

2. Tool-specific rules beat general rules

General: "Be careful with file edits."
Specific: "Always read a file before editing it. Never use Write when Edit will work."

The specific version is directly actionable. The agent can check it before each tool call.

3. Recovery instructions survive compaction

This one took me 40 hours to learn. After compaction, the agent loses conversational context but re-reads CLAUDE.md.

I added this to my CLAUDE.md:

## Session Recovery
If context was reset or compacted, read tasks/current-task.md first.
It tells you where you were and what's next.

Now container restarts and compaction events cost 2 minutes instead of 20.

4. The order matters

Claude reads top-to-bottom. Put the most critical rules at the top. If you have "never push to main without review" buried in section 8, it'll get ignored after compaction when the agent is skimming.

5. Tech-stack-specific sections beat generic ones

Bad:

## Code Style
Follow best practices.

Good:

## Code Style
- Files: kebab-case (rate-limit.ts, not rateLimitHelper.ts)
- Components: PascalCase (Dashboard.tsx)
- No axios: use native fetch
- Rate limiting: 150-300ms delays between external calls

The generic version is useless. The specific version prevents real mistakes.

What most CLAUDE.md files are missing

After reading a lot of them on GitHub and Reddit: most are about code style. Almost none cover:

• Error recovery patterns (what to do when a tool call fails)
• Context management (when to compact, how to use state files)
• External API behavior (rate limits, auth token handling)
• Workflow gates (what requires human review before proceeding)

These are where autonomous runs actually break. Code style mistakes are annoying. Missing error recovery causes infinite loops.

A minimal effective CLAUDE.md

# Project: [name]

## Non-negotiables
- Read before editing: always use Read tool before Edit
- Never `git add -A` — add specific files only
- No silent error swallowing: always log what failed and why

## Recovery
After any compaction or restart: read tasks/current-task.md first

## Code conventions
[your stack-specific rules here]

## Rate limits
[external APIs and their limits]

## What requires human approval
[the things you don't want the agent doing unsupervised]

That's the skeleton. The specifics depend on your stack. The skeleton is what most people are missing.

---

Wrote this from 72 hours of autonomous runs at builtbyzac.com. The patterns that worked are in the Agent Harness ($29).