Claude.md in 67 Lines: What 3 Rewrites Taught Me

TL;DR

• My current CLAUDE.md is 67 lines. v1 was 312 lines and barely worked
• The fix wasn't writing better rules. It was deleting 75% of them
• Full file below, side-by-side v1/v2/v3 comparison, and the six rules that survived the last rewrite
• If you're not a programmer: the non-developer CLAUDE.md at the bottom is meant for you

My first CLAUDE.md was 312 lines of everything I could think of. Tab width. Naming conventions. A list of things Claude should "prefer." A paragraph of writing style rules. Two paragraphs of things to avoid. Four "important notes" at the bottom in all caps.

Claude ignored about half of it.

I assumed I was writing bad rules. I wrote more rules. The file grew to 380 lines. Claude started ignoring 60% of it.

Then I found a Hacker News comment from Boris on the Claude Code team that flipped the problem for me:

If there is anything Claude tends to repeatedly get wrong, not understand, or spend lots of tokens on, put it in your CLAUDE.md. I add to my team's CLAUDE.md multiple times a week.

Multiple times a week. Not "write it once perfectly." Not "cover every edge case." The file is supposed to be small enough that you can edit it mid-task.

I rewrote mine from scratch. Cut to 142 lines. Then, a month later, to 67. That's the version Claude actually follows now, and the rest of this post is what got me there.

Who This Is For

• You've been using Claude Code for a few weeks and your CLAUDE.md is either empty or bloated
• You copied a template off someone's blog and you're not sure why half the lines are in there
• You're not a programmer — you're using Claude for writing, research, or a business you run alone
• You want a file that feels like yours, not a boilerplate

If you haven't installed Claude Code yet, start with my first-week guide and come back. If you've already got a working CLAUDE.md and want prompts that make it earn its keep, jump to my prompt-pattern cheat sheet instead.

If you're deep in the Claude Code weeds already, skip to Six Rules or The File Itself.

What CLAUDE.md Actually Is (30 Seconds)

One-line version: CLAUDE.md is a Markdown file Claude Code reads at the start of every session. It becomes part of the system prompt — the background context Claude uses to answer you. Anthropic's own memory docs put it plainly: "Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory."

Think of it as the onboarding doc you give a new hire. You don't paste the employee handbook at them. You tell them where their desk is, who their mentor is, and where the coffee is. Everything else is on the shared drive.

A good CLAUDE.md is the same: directions, not documentation.

Where CLAUDE.md Sits in Claude's Memory Stack (2026)

There are three separate memory systems at Anthropic right now. It's worth knowing which one you're in before you start writing rules:

The three aren't replacements for each other — they're parallel tools for different roles. If you use Claude.ai in the browser and Claude Code in the terminal, you'll touch two of them. This post is about the second row.

The Four File Layers Inside CLAUDE.md

Within the Claude Code system, CLAUDE.md actually reads up to four files, layered from broad to specific:

Later layers can override earlier ones (except enterprise). Most people only need two: ~/.claude/CLAUDE.md for personal preferences and ./CLAUDE.md in each project. That's what I use. I've never written a rules file, and I'm fine.

There's also a fifth kind — Auto Memory, which Claude writes for itself based on your corrections. I'll leave that for a separate post; it's a different system with different rules.

The File: My Actual 67-Line CLAUDE.md

This is the current ./CLAUDE.md in my main content project. Copy it, read past it, or steal sections — it's here to be useful, not admired.

# Content Workflow Project

## What this project is
A one-person writing and research workspace. Markdown files organized by topic.
No code compilation. No build step. Everything is text.

## Stack
- A blog I built (publishing) — drafts live in /articles/, not in the CMS
- Notion (notes) — synced via export, never edited here
- Cloudflare R2 (images) — public bucket, no auth

## Directory map
- /articles/    Drafts, one folder per piece
- /research/    Source material, PDFs, transcripts
- /templates/   Reusable outlines and boilerplate
- /archive/     Anything older than 6 months

## Rules (MUST / NEVER)
- MUST keep filenames in kebab-case
- MUST add frontmatter (title, date, tags) to every article
- NEVER modify files in /archive/ unless I say the word "archive"
- NEVER rename files without asking
- NEVER add features, refactoring, or structure I didn't request
- NEVER claim a task is done without showing me the diff

## Writing rules
- Plain English. No corporate voice, no "leverage" or "unleash"
- Short sentences. One idea per paragraph
- If a claim needs a source, add a link. If no source, say "no citation"

## Workflow
- Stage changes with git add after every approved step
- Use @research/{topic}.md when I ask about a topic I've researched before
- When unsure, ask. Don't guess.

## Commands I use
- Preview: open /articles/{slug}/index.html in browser
- Count words: wc -w articles/{slug}/*.md
- Lint links: grep -rn "]()" --include="*.md"

## Detailed docs (loaded on request)
- Publishing flow: @docs/publish.md
- Voice and tone: @docs/voice.md
- Newsletter format: @docs/newsletter.md

That's 67 lines, give or take. Every section earns its spot.

Line-by-Line: Why Each CLAUDE.md Section Is Here

Most of what makes the file work is what I didn't put in it. But the sections that stayed each answer a different question Claude asks implicitly every session:

"What is this project?"
→ ## What this project is. Three sentences. A human onboarding to the repo would need this. Claude needs it too.

"What tools are in play?"
→ ## Stack and ## Directory map. These catch Claude before it asks. Without them, I was answering "where do the images go?" every third session.

"What are you going to yell at me for?"
→ ## Rules (MUST / NEVER). This is the section that changed the most across rewrites. More on the wording below — it's specific on purpose.

"How do you want me to write?"
→ ## Writing rules. Four lines. Any more and I'm asking Claude to be a style guide, which is the wrong job.

"What should I do between steps?"
→ ## Workflow. Process rules, not style rules.

"What shell commands are allowed?"
→ ## Commands I use. Three commands. I type them often enough that I'd rather Claude know about them than rediscover them.

"Where's the rest?"
→ ## Detailed docs. Three pointers. Each @path file is loaded only when the section is relevant, so the cost is zero until I need it. This is the single most important structural trick in the file.

Three CLAUDE.md Versions: What I Deleted and Why

This is the boring part most guides skip. It's also the part that would have saved me a month.

What went into v1 that I later deleted

• 40 lines of formatting rules. Indent width. Quote style. Blank lines around headings. Every one of these is something Prettier or a Markdown linter can enforce in zero tokens. Deleted.
• A paragraph of "preferred styles." Words like "prefer" and "try to" are mushy. Claude treated them as suggestions. Turned into MUST/NEVER or deleted.
• A list of 22 terms I wanted Claude to use consistently. Three of them mattered. The other 19 were me being precious. Kept three. Deleted the rest.
• Sample code pasted directly in the file. Three examples of "here's how to write an article." These lived in the file, which meant every session paid for them in tokens whether I was writing an article or not. Moved to @docs/voice.md, loaded only when relevant.
• Rationale paragraphs. I'd write "we use kebab-case because…" and explain. Claude doesn't need the why to follow the rule. Deleted the why.

What survived into v3

Anything I caught Claude getting wrong twice. That's the filter. Not "things that would be good to specify" — things Claude actually got wrong.

The humanlayer team calls this onboarding minimalism: "include as few instructions as reasonably possible." I'd put it more bluntly — if a rule isn't stopping a specific mistake, it's decoration.

Six CLAUDE.md Rules That Made v3 Work

These aren't my rules — they're six ideas I pulled from Anthropic's docs, Boris's HN comment, a few bloggers who've written a lot of CLAUDE.md files, and the cuts I made across three rewrites.

1. A CLAUDE.md is a table of contents, not an encyclopedia

Any large language model can follow a limited number of instructions in one pass — research and user reports both put the stable range at around 150-200. Claude Code's own system prompt already uses a chunk of that budget. If your CLAUDE.md adds another 300 instructions, you're asking Claude to juggle more than it can hold.

The practical rule: if a section is 15+ lines and only matters sometimes, move it to @docs/xxx.md and link it. Your CLAUDE.md points at the detailed doc. The detailed doc only loads when Claude needs it.

2. Point, don't paste

Instead of pasting 40 lines of sample code into CLAUDE.md, write:

Example of our article format: @templates/article-standard.md

Claude reads the referenced file when it's relevant and ignores it otherwise. Your main file stays small. The template file stays canonical — when you update it, Claude sees the update automatically. No copy stays stale.

Builder.io's CLAUDE.md guide pushes this hard, and for good reason. Copies rot. Pointers don't.

3. Cover WHAT, WHY, HOW

A good CLAUDE.md answers three questions:

• WHAT is this project? (stack, directory map, core modules)
• WHY is it like this? (the one or two decisions someone would otherwise try to reverse)
• HOW do I work in it? (commands, workflow, review loop)

If a line doesn't fit one of those three buckets, it's probably filler. Cut it.

4. Stop asking the LLM to be a linter

Prettier gives you the same output every time. Claude doesn't. Asking Claude to enforce indent width or quote style is asking a probabilistic tool to do a deterministic job. It'll get it right 95% of the time — which means wrong one in twenty. That's worse than a linter.

Move formatting to tools. Keep CLAUDE.md for things tools can't do: architecture decisions, naming judgment calls, project-specific patterns, workflow choices.

5. It's a living document

Boris's comment keeps coming back to me: I add to my team's CLAUDE.md multiple times a week. Not once. Not weekly. Multiple times. The file you write on day one will be wrong in ways you don't yet know. That's fine.

The update trigger I use: if I find myself correcting Claude on the same thing twice in two sessions, I add a line to CLAUDE.md. One line. Specific to the mistake. Then I watch whether it sticks.

6. Budget awareness

Rough math, from what we know about LLM instruction following:

A 2026 workflow guide from smart-webtech puts the hard ceiling at 200 lines: "Files longer than that consume too much context and instruction adherence measurably drops." That matches what I saw going from v1 to v3 — below 100 lines, every rule got followed; between 100-200, adherence started drifting; above 200, Claude was actively triaging.

Anthropic themselves publish a rolling Claude Code changelog that's been shipping memory improvements most months in 2026 — reduced memory footprint, cache clearing after compaction, capped file history snapshots. The tool is getting leaner. Your CLAUDE.md should go the same direction.

Every line you add is a line spent. Ask yourself: is this useful every session, or only sometimes? If only sometimes, it belongs in an @docs/ file, not the main one.

A specific wording note: MUST and NEVER work, "prefer" doesn't

I tested both. Polite language — "prefer kebab-case," "try to use short sentences" — got followed about 70% of the time. MUST/NEVER wording got followed closer to 95%.

Why? LLMs trained on technical docs know RFC 2119 keywords. MUST, NEVER, and MUST NOT are treated as rules. "Prefer" and "try to" are treated as suggestions. Both forms are grammatically fine. Only one behaves like a rule.

The Mr Tinkleberry Test

Here's a trick I borrowed from a Hacker News thread. A developer wrote:

A friend of mine tells Claude to always address him as "Mr Tinkleberry." He says he can tell Claude is not paying attention to the instructions on Claude.md when it doesn't.

It's dumb, and it works. Add one small, unusual, low-stakes instruction to your CLAUDE.md — something Claude would never do on its own. Mine is this line, near the top:

## Greeting
Always greet me as "Captain" at the start of a session.

When a new session opens with "Hello, Captain" — I know Claude is reading the file. When it opens with "How can I help you?" — I know the file is being skipped, usually because I've stuffed too much in and Claude is triaging.

It's the cheapest smoke test I've found.

Four Ways I See People Break CLAUDE.md

Mistake 1 — Writing it like a manifesto

The worst CLAUDE.md I've seen a reader send me started like this:

# Project Philosophy
This project represents a commitment to excellence in software craftsmanship.
We believe that clean code is a form of respect for your future self and your
colleagues. Every line should be written with intention...

Three paragraphs of this before any instruction. Zero of it helps Claude do a task. Claude doesn't need a manifesto — Claude needs rules. Delete the philosophy and start at "## What this project is."

Mistake 2 — Using it as a linter

A reader wrote me a 180-line CLAUDE.md. 130 of those lines were formatting rules. Indent style. Trailing commas. Blank lines around headings. Single quotes versus double quotes. Every one of those lines is something ESLint and Prettier solve for free, and they solve it more reliably than any LLM.

The fix: delete all 130 lines. Add one line: MUST run npm run lint before reporting a task complete. Let the tool do the tool's job.

Mistake 3 — "Please" and "prefer"

Please try to use descriptive variable names when possible.
We would prefer if you avoided overly complex nested structures.
It would be great if documentation could be kept up to date.

Every one of those lines will be followed sometimes. Rewrite them:

MUST use descriptive variable names. No single-letter names outside loop counters.
NEVER nest conditionals more than 3 levels deep.
MUST update @docs/{relevant}.md when changing a public API.

Specific and directive. Suggestions get ignored. Rules get followed.

Mistake 4 — Writing it once, forever

The CLAUDE.md that was right for your project two months ago is probably wrong now. The stack moved. You stopped using one of the tools. A decision got reversed. The file needs to move with the project.

I audit mine monthly. Twenty minutes. Delete anything I haven't needed since last audit. Add anything I've been repeating to Claude lately. It's the smallest maintenance tax in the project, and the thing that keeps the file from rotting.

A Quick Note on Auto Memory

You may have heard about Auto Memory — the other half of Claude Code's memory system. It became a standard, stable feature in early 2026 and complements what I've covered above.

Short version: CLAUDE.md is what you write for Claude. Auto Memory is what Claude writes for itself, based on your corrections and habits. When you tell Claude "don't do that again," Claude stores a note; next session, the note loads.

The two systems don't conflict — they complement each other. CLAUDE.md is your rules. Auto Memory is Claude's running notebook. I'll cover Auto Memory properly in a separate post, because the right/wrong ways to use it are different from CLAUDE.md.

For now, one thing worth knowing: you can check what Claude has stored with /memory inside a session. If you're surprised by something Claude "remembered," that's usually where it came from. Anthropic is also actively shipping memory-related improvements — the changelog from Q1 2026 shows consistent work on reducing memory footprint, better session recap, and file-history caps. Good news for anyone writing long CLAUDE.md files: the tool is getting smarter about what it actually retains.

The common CLAUDE.md regret I hear most

After publishing my six-month review, the #1 note readers sent back was the same: "I wish I'd audited my CLAUDE.md a month earlier." The file rots silently. You stop using a tool, a rule becomes obsolete, a section you added to fix a bug fixes a bug that no longer exists. A 20-minute audit every 4-6 weeks is the cheapest maintenance tax on the list, and the one most people skip.

One reader who runs a two-person agency had a 240-line CLAUDE.md for an old client engagement. The client project wrapped up in January. The file was still loaded into every new project session in April — three months of every prompt carrying 180 lines of dead context. Five minutes to delete, three months of unnecessary tokens. That's the cost of "write once, forever."

Copy This CLAUDE.md Starter Template

Not a programmer? Use this. It's a CLAUDE.md for a solo content or research workspace, 28 lines, no code context. Paste it into ./CLAUDE.md in your project folder and edit the filled-in parts.

# {project name}

## What this project is
{One or two sentences. What is the work? What's the output?}

## Tools
- {Tool 1} — {what I use it for}
- {Tool 2} — {what I use it for}

## Directory map
- /{folder}/  {what lives here}
- /{folder}/  {what lives here}

## Rules (MUST / NEVER)
- MUST keep filenames in kebab-case
- MUST add a date and title to every file in /articles/
- NEVER modify files outside the current task
- NEVER claim a task is done without showing me the diff
- When unsure, ask. Don't guess.

## Writing rules
- Plain language. No corporate voice.
- Short sentences. One idea per paragraph.

## Greeting
Greet me as "{pick one word}" at the start of a session.

## Commands I use
- {Your most common command}

The greeting line is the smoke test from earlier — keep it while you're tuning the file, then delete it once you trust Claude is reading the file consistently.

Key Takeaways

• The optimal CLAUDE.md length is 60-100 lines — past 150, Claude measurably starts triaging rules. My current file is 67 lines after three rewrites
• Use MUST / NEVER / MUST NOT (RFC 2119 keywords) — polite language like "prefer" or "try to" gets followed ~70% of the time vs. ~95% for directive language
• Point, don't paste — move long templates into separate files and reference with @path/to/file.md; the referenced file is lazy-loaded only when relevant
• Audit monthly, not quarterly — the most common reader regret is waiting too long between CLAUDE.md cleanups. 20 minutes every 4-6 weeks keeps the file alive
• Don't ask the LLM to be a linter — Prettier and ESLint are deterministic and free; CLAUDE.md should hold decisions tools can't make
• Add a one-word greeting as a smoke test — if Claude opens the session without the greeting, the file isn't being read (usually because it's too long)

FAQ

Where should CLAUDE.md live — in the project or in my home folder?

Both, usually. A project-specific ./CLAUDE.md in the project folder covers rules that apply only to that work. A user-level ~/.claude/CLAUDE.md covers things you want across every project (voice, working style, "don't over-explain your answers"). Project-level overrides user-level where they conflict.

How long should CLAUDE.md be?

60-100 lines for most work. Past 150, Claude starts skipping parts of it. If you feel the file pushing past 100, that's the signal to move detail into @docs/ files and link them from the main file. The humanlayer guide argues for even shorter files — I've found 67 lines is the sweet spot for my content workflow.

Does CLAUDE.md work in subdirectories?

Yes, and it's useful. If you have a ./frontend/CLAUDE.md, Claude loads it on top of the root ./CLAUDE.md when working in that folder. Keep the subfolder file scoped — things true only of the subfolder. Avoid duplicating rules between levels; duplicates drift apart over time.

What's the `@` syntax actually doing?

@path/to/file.md tells Claude to include the contents of that file when the surrounding section is relevant. It's lazy loading: if Claude isn't touching that area, the file doesn't load and doesn't cost tokens. Depths nest up to five levels, so you can chain imports if you want to, though most setups don't need more than one level.

Can I have a personal CLAUDE.md that isn't committed to git?

Yes — name it CLAUDE.local.md in the same folder as CLAUDE.md, and add it to .gitignore. This is where I put URLs, test accounts, and notes I don't want to share with the team. The pattern was discussed in depth on HN — team-visible file for shared rules, local file for personal shortcuts.

Do I need to tell Claude to read CLAUDE.md at the start of a session?

No. Claude Code reads the file automatically on session start. If Claude seems to be ignoring it, the problem is almost always one of two things: the file is too long (it's being triaged), or the rules are written as suggestions rather than directives. The Mr Tinkleberry test from earlier will tell you which one.

What if my project doesn't have any code at all?

The 28-line template above is written for exactly that case. Filenames, directories, voice rules, and workflow notes apply just as much to a writing or research project as to code. Drop the "commands" section if you never use shell commands. Everything else stays relevant.

What's Next in This Series

• Which phrasings save the most time, ranked by ROI — my seven-prompt cheat sheet for Claude Code, plus the three I dropped
• The honest scoreboard: 5 Skills I kept, 3 I deleted — post-mortems on the ones I shipped and regretted
• 5 MCP connections worth it, 7 I removed — a non-programmer's short list
• Where this CLAUDE.md lives inside my real setup — the six-month retrospective: cost, workflow, three regrets

— Leo