How to Write a CLAUDE.md (the file that 10x'd my Claude Code)

A working CLAUDE.md is the single biggest difference between Claude Code feeling like a smart autocomplete and a junior employee who actually knows your business. I rewrote mine three times in 9 months on 500k.io. The current 580-line version is what runs the content factory shipping 17+ articles in 30 days. Most founders skip the CLAUDE.md, install Claude Code, ask three questions like it’s ChatGPT, and quit by day 5. This article is the file structure I’d give to a founder on day one — if I could only give them one thing.

If you’re brand new to Claude Code itself, read a $500K founder’s first 30 days with Claude Code first. This article assumes you’ve installed it and run at least one session.

What is CLAUDE.md, exactly?

CLAUDE.md is a Markdown file at your repo root that Claude Code automatically reads at the start of every session. The agent uses it as context — your project’s “operating manual.” Same model (Claude Sonnet 4.6 / Opus 4.x), but with your business rules baked in.

Without CLAUDE.md, Claude Code is generic. With it, Claude Code knows your stack, your voice, your locked decisions, your boundaries. The fix takes 90 minutes of writing and saves you hundreds of hours of re-explaining.

The six sections that actually matter

I’ve tested CLAUDE.md structures across four projects (500k.io, two SaaS prototypes, one agency repo). The structure below is what survived.

1. What this project is — two paragraphs, plain English

The opening section. Not a marketing pitch. Two paragraphs answering: what does this project DO, and who is it FOR. Specific.

## Project: 500k.io

500k.io is the live journal of a solo founder going $0 → $500K ARR
in 12 months with AI as the only team. Currently at $9,500 MRR.
Monetized via The 500K Brief newsletter and Synapse Circle community.

The audience is the leveraged solopreneur — 25-45, technically curious
but not a developer, building agencies, content businesses, or SaaS.
They want concrete tactics. Not motivation. Not theory.

That’s 60 words. Claude Code now knows what voice to write in, what audience to target, what stage the business is at. Without that paragraph, every session starts blind.

2. The non-negotiables — locked decisions

This is the highest-leverage section. List every decision you will not re-debate. The point is to stop Claude from re-asking and re-suggesting the same things.

Example from my actual file:

## Locked decisions

- Stack: Astro + MDX + Tailwind + Cloudflare Pages. No Next.js. No Vercel.
- Newsletter: Beehiiv. Not Substack. Not ConvertKit. Decision is final.
- Language: English first. French translations are a Phase 2 problem.
- Brand: 500k.io is the personal brand. The Kreators AI is the agency
  brand. Never confuse them.
- Budget cap: $565/mo total tooling. New tools require killing an old one.
- Voice: founder-to-founder, specific numbers, opinionated. See voice rules.

I have 14 locked decisions in mine. Each one was a multi-hour debate I had once and never want to have again.

3. Voice and style rules — banned phrases, preferred patterns

The section that determines whether content ships in your voice or “AI voice.” I wrote a full voice bible for 500k.io — the CLAUDE.md version is the compressed enforcement layer.

## Voice rules

Banned phrases (cut on sight):
- "delve into", "leverage", "robust", "comprehensive"
- "navigate the landscape", "ever-evolving", "in the realm of"
- "in conclusion", "to summarize", "as we've explored"
- "moreover", "furthermore", "indeed"

Preferred patterns:
- First-person ("I", "we") for opinions. Never "one" or "users".
- Specific numbers in every H2 ("$9,500 MRR" not "growing revenue")
- Sentence rhythm: vary 4-word punchy with 25-word complex
- Contractions always allowed. "I'll" not "I will".

Hooks formulas: see /context/voice-guide.md

The banned-phrases list is doing more work than any other 30 lines in the file. Claude Code stops generating LLM-tone copy the moment it has the list.

4. The Definition of Done

What must be true before a task counts as finished? This is the most-edited block in my file. It evolves as the project matures.

## Definition of Done (per article)

- [ ] TLDR box, 60-80 words, self-contained
- [ ] 6+ internal links to /journal/* or pages
- [ ] 3+ external citations with footnotes
- [ ] FAQ section, 4-6 Q&A
- [ ] At least 1 table (comparison or pricing or decision matrix)
- [ ] Specific Maxime anecdote (not generic abstraction)
- [ ] Frontmatter complete (all fields present)
- [ ] draft: true (no auto-publish without review)
- [ ] Voice check: zero banned phrases (grep before commit)

Without this, Claude Code thinks “draft 3000 words” = done. With this, “done” has 9 specific gates. The number of revisions per article dropped from 4 to 1.5 after I shipped this section.

5. The roadmap pointer

A one-paragraph block telling Claude where to look for the active sprint. Not the whole roadmap — just the pointer.

## Active sprint

Current focus: Wave 1 SEO content engine, 10 articles by May 9.
Roadmap: see outputs/atlas/2026-05-03-seo-master-plan-v2.md
Open questions: see brain/00-inbox/

Don't work on Phase 2 stuff (programmatic SEO, /tools/ pages, FR
translations) without explicit ack.

This stops the “drift” problem where an agent starts working on something tangentially related instead of the active priority.

6. The agreement — how Claude should behave

The behavioral contract. How does Claude interact with you?

## The agreement

- Pause for ack before any task that writes >5 files or runs >5 minutes
- List file changes before writing them, not after
- If a decision conflicts with locked decisions, FLAG it — don't override
- If you don't know, say "I don't know". Never invent.
- Commit messages: imperative mood, ≤72 chars, no marketing language
- Don't push to git. I push manually after review.

This is what stops Claude Code from cowboy-shipping a 47-file refactor while you’re at lunch. Six lines. Saves you from at least one disaster per month.

Section structure side-by-side

Section	Length	Update frequency	Why
Project description	60-150 words	Quarterly	Identity rarely changes
Locked decisions	8-20 bullets	Monthly	New decisions accumulate
Voice rules	30-80 lines	Quarterly	Stable once set
Definition of Done	5-15 bullets	Weekly	Evolves with project
Roadmap pointer	3-5 lines	Weekly	Sprint changes
Agreement	6-10 bullets	Quarterly	Behavioral contract

How long should it actually be?

Mine is 580 lines on 500k.io. The four projects I’ve run CLAUDE.md on landed in a tight range:

• 500k.io: 580 lines (content factory, voice-heavy)
• Agency client repo: 410 lines (technical-heavy, less voice)
• SaaS prototype #1: 220 lines (early stage, less locked)
• SaaS prototype #2: 340 lines (mid stage, more locked decisions)

The pattern: more lines for more mature projects. Under 200 means you haven’t made enough decisions. Over 600 means you’ve padded — and Claude reads the whole thing every session, so bloated briefs lose signal.

Nested CLAUDE.md for scoped context

Claude Code reads CLAUDE.md hierarchically — root level first, then any nested CLAUDE.md inside subdirectories you’re working in. I use this for:

• /src/content/blog/CLAUDE.md — voice rules and article structure (overrides root for content work)
• /scripts/CLAUDE.md — deploy specifics, environment vars, git rules
• /skills/CLAUDE.md — skill metadata format

Don’t go deeper than 2 levels. The nested briefs add context, but every level multiplies the cognitive overhead. Two layers is the sweet spot.

The five mistakes that kill CLAUDE.md value

I’ve watched founders ship bad CLAUDE.md files and abandon Claude Code. The pattern is repeatable.

1. Writing it like a README

A README explains what the project IS to a human reader. CLAUDE.md explains what “done” means and what’s NOT up for debate. Different document, different purpose. Don’t copy/paste your README.

2. Skipping the locked decisions

The most common mistake. Founders write voice rules and skip the “I will not re-debate this” section. Then Claude keeps suggesting Substack instead of Beehiiv. Locked decisions stop that loop.

3. Vague Definition of Done

“Make the article good” is not a Definition of Done. “TLDR box, 6+ links, FAQ section, draft: true frontmatter” is. Specificity is the gate.

4. Treating it as one-time setup

CLAUDE.md is a living document. If you haven’t touched it in 30 days, you’re shipping decisions that aren’t documented. Update weekly.

5. Padding for length

Long doesn’t mean useful. 250 sharp lines beats 800 padded lines. Cut everything that doesn’t change Claude’s behavior.

My exact CLAUDE.md template (copy this)

The bare-bones structure I’d give a founder on day one:

# CLAUDE.md

## Project
[Two paragraphs. What it is, who it's for, where it stands now.]

## Locked decisions
- [Stack]
- [Brand boundaries]
- [Budget cap]
- [Tools committed to]
- [Tools rejected]

## Voice rules
Banned phrases:
- [list]
Preferred patterns:
- [list]

## Definition of Done
- [ ] [Specific gate 1]
- [ ] [Specific gate 2]
- [ ] [Specific gate 3]

## Active sprint
[3-5 lines. Where to look for current priority.]

## The agreement
- [Behavioral rule 1]
- [Behavioral rule 2]
- [Behavioral rule 3]

That’s the skeleton. Fill it with your specifics. Aim for 200-300 lines on day one. Iterate up to 500-600 over the first month. Don’t try to write the perfect 600-line file from scratch — you don’t know enough yet.

“The best CLAUDE.md files I’ve seen read like a startup brief, not a tech doc. Locked decisions, voice rules, and a Definition of Done — that’s 80% of the value.” — Boris Cherny, Anthropic, on agent design¹

What changes after you ship CLAUDE.md

The 48 hours after I shipped my first real CLAUDE.md:

• Average article draft time: dropped from 90 minutes to 35
• Voice revisions per article: dropped from 4 to 1.5
• “Did you mean…” re-asks per session: dropped from 6 to 1
• Agent confidence on “is this done?”: went from 40% accurate to 85%

Not magic. Just context. Claude Code is the same agent — but now it knows your business.

FAQ

What is a CLAUDE.md file?

It’s a Markdown brief at your repo root that Claude Code reads on every session. It tells the agent what your project is, what’s locked, what voice to use, and what “done” means. Without it, every session starts from zero context.

How long should my CLAUDE.md be?

Between 200 and 600 lines. Mine is 580. Under 200 means you skipped something important. Over 600 means you padded — and Claude reads the whole thing every session, so bloated briefs lose signal.

Does CLAUDE.md need to be at the repo root?

Yes for the global brief. You can also nest CLAUDE.md inside subdirectories for scoped context. I use this for /content (voice rules) and /scripts (deploy specifics). Don’t go deeper than 2 levels.

What’s the single biggest CLAUDE.md mistake?

Writing it like a README. A README explains what the project IS to a human. CLAUDE.md explains what “done” means and what’s NOT up for debate. Locked decisions are the highest-ROI lines you’ll write.

Does CLAUDE.md replace agents or skills?

No. CLAUDE.md is the global brief. Subagents in .claude/agents/ are scoped specialists. Skills in .claude/skills/ are reusable workflows. The three layers stack — global context, specialist personas, repeatable patterns.

How often should I update CLAUDE.md?

Every time you make a “never re-debate this” decision. Mine gets touched 2-4x/week. The Definition of Done section is the most-edited block — what counts as “shipped” evolves as the project matures.

Going further

• Claude Code: a $500K founder’s first 30 days
• Claude Code Pricing in 2026, Actually Explained
• How to Write a Claude Skill in 2026
• The 500K stack
• 7 Claude skills every solo founder ships first

Footnotes

1. Boris Cherny, Anthropic engineering blog: “Claude Code best practices” (anthropic.com/engineering/claude-code-best-practices). ↩

FAQ

What is a CLAUDE.md file?

+

It's a Markdown brief at your repo root that Claude Code reads on every session. It tells the agent what your project is, what's locked, what voice to use, and what 'done' means. Without it, every session starts from zero context. With it, you skip the first 15 minutes of explaining.

How long should my CLAUDE.md be?

+

Between 200 and 600 lines. Mine on 500k.io is 580. Under 200 means you skipped something important. Over 600 means you padded — and Claude reads the whole thing every session, so bloated briefs lose the signal.

Does CLAUDE.md need to be at the repo root?

+

Yes for the global brief. You can also nest CLAUDE.md inside subdirectories for scoped context — Claude Code reads parent and local CLAUDE.md when working in nested folders. I use this for /content (voice rules) and /scripts (deploy specifics).

What's the single biggest CLAUDE.md mistake?

+

Writing it like a README. A README explains what the project IS to a human. CLAUDE.md explains what 'done' means and what's NOT up for debate. Locked decisions are the highest-ROI lines you'll write.

Does CLAUDE.md replace agents or skills?

+

No. CLAUDE.md is the global brief. Subagents in .claude/agents/ are scoped specialists. Skills in .claude/skills/ are reusable workflows. The three layers stack: global context (CLAUDE.md), specialist personas (subagents), repeatable patterns (skills).

How often should I update CLAUDE.md?

+

Every time you make a 'never re-debate this' decision. Mine gets touched 2-4x/week. The Definition of Done section is the most-edited block — what counts as 'shipped' evolves as the project matures.