How to Write a CLAUDE.md That Actually Helps

Most CLAUDE.md files are useless in one of two ways: they’re empty, or they’re bloated with things the agent could figure out in five seconds. Both waste the one thing the file exists to spend well — the agent’s attention at the start of every session.

A good CLAUDE.md isn’t documentation. It’s a briefing for a senior engineer joining your team today who happens to read fast and forget nothing. You don’t hand that person a file tree. You tell them how to run the thing, how the pieces fit, the conventions that aren’t obvious, and the traps that already bit you.

I maintain CLAUDE.md files across my projects, and the difference between a good one and a bad one is the difference between an agent that moves like a teammate and one that re-derives your architecture every session. Here’s what actually works.

TL;DR

• CLAUDE.md is a context file Claude Code reads automatically — treat it as a briefing, not documentation.
• Include the non-obvious: commands, big-picture architecture, cross-cutting conventions, and gotchas.
• Leave out what the agent discovers instantly (file trees) or what rots (generic best-practice filler).
• Use a root file for the big picture and nested files for subproject-specific rules.
• Keep it alive. A CLAUDE.md that drifts from reality is worse than none — it actively misleads.

What a CLAUDE.md actually is

CLAUDE.md is a Markdown file that Claude Code loads as project context at the start of a session. Whatever you put in it becomes part of what the agent knows before it reads a single line of your code. That’s the whole mechanism — and it’s why the file is so easy to get wrong. Anything you write is “free” knowledge the agent starts with; anything you omit, it has to rediscover (and sometimes guess at) every time.

So the real question isn’t “what could I document?” It’s “what does the agent most need to know that it can’t quickly find out itself?”

💡 Key insight: Optimize for the agent’s first five minutes. What would a sharp new hire need to be productive — and what would they figure out on their own without being told?

What actually belongs in it

Four things earn their place. Almost nothing else does.

1. Commands

How to build, test, lint, run, and deploy — including the non-obvious incantations. If running a single test needs a specific flag, if dev mode needs two terminals, if there’s a pre-commit gate, that’s gold. The agent will otherwise guess, and guess wrong.

## Commands
- `pnpm dev` — main site on :5173
- `pnpm check` — typecheck; MUST pass before commit
- `pnpm build` — proves the static prerender works

2. The big-picture architecture

Not every file — the shape. How the major pieces fit, what talks to what, where the boundaries are. The things that require reading five files to understand. A short prose map or a simple diagram here saves the agent (and you) enormous time.

This is where “the analytics API is the only server-side code” or “sub-apps are built separately and copied in at build time” belongs — facts that aren’t visible from any single file.

3. Cross-cutting conventions

The rules that span the codebase and that the agent would otherwise violate: “everything ships static, never introduce SSR,” “use runes only, no legacy reactive syntax,” “canonical domain is X, use the central config.” State them as rules, with the why when it isn’t obvious.

4. Gotchas and hard-won lessons

The traps. “This build step fails silently if X.” “Don’t edit the generated covers by hand.” “Running git add from inside the subdir breaks paths.” These are the highest-value lines in the file because they’re the ones nobody could infer.

What to leave out

Every line that doesn’t earn its place dilutes the ones that do. Cut:

• Exhaustive file trees and component lists. The agent can run ls and grep faster than you can maintain a manifest. Describe structure only where it’s non-obvious.
• Generic best practices. “Write unit tests.” “Handle errors gracefully.” “Don’t commit secrets.” The agent already knows. These read as noise and train it to skim.
• Restating the code. If a function’s behavior is clear from its name and body, don’t narrate it in CLAUDE.md.
• Anything that rots. Version numbers, line counts, “currently we’re working on X” — unless you’ll actually keep them current. Stale instructions are worse than missing ones because the agent trusts them.

💡 Key insight: A CLAUDE.md that’s wrong is worse than one that’s empty. An empty file makes the agent investigate; a wrong file makes it confidently do the wrong thing.

A structure that works

You don’t need a rigid template, but this shape covers the essentials without bloat:

# CLAUDE.md

## What This Repo Is
[One paragraph: what it is, the stack, how it's organized.]

## Architecture / How the Pieces Fit
[The big picture. A diagram or short prose map. Boundaries and data flow.]

## Common Commands
[Build, test, run, deploy — including the non-obvious ones.]

## Conventions
[Cross-cutting rules the agent must follow, with the why.]

## Gotchas
[Traps, footguns, things that bit you before.]

## Keeping This File Up To Date
[A note that this is a living map, updated as part of normal work.]

For a monorepo, go further: a root CLAUDE.md for the big picture, plus a nested CLAUDE.md inside each subproject for rules specific to it. Claude Code reads the relevant files based on where you’re working, so subproject rules stay close to the code they govern. There’s also a user-level ~/.claude/CLAUDE.md for personal preferences that follow you across every project.

Common mistakes

• The kitchen sink. Dumping everything turns the signal-to-noise ratio against you. Be ruthless.
• Write-once, never-update. The fastest way to make a CLAUDE.md harmful is to let it drift. Update it in the same change that alters what it describes.
• Documenting the obvious. If the agent learns it in one grep, it doesn’t belong.
• No commands. The single most useful section, and the one people most often skip.
• Vague rules. “Follow good practices” tells the agent nothing. “Never use transition-all; always name the exact property” tells it exactly what to do.

Best practices

1. Bootstrap with /init, then trim. Claude Code’s /init generates a first draft from your repo. Treat it as a starting point and cut it down to the non-obvious essentials.
2. Write rules, not essays. Short, imperative, specific. “Do X. Never Y. Because Z.”
3. Put rules near the code. Root file for the big picture; nested files for subproject specifics.
4. Make it a living document. Update it as part of the change that affects it — not as a someday chore.
5. Re-read it as the agent would. If a line wouldn’t change what the agent does, or it could learn it instantly, delete it.
6. Lead with commands and gotchas. They’re the highest-leverage content in the file.

Conclusion

A CLAUDE.md is the cheapest leverage you have over how well an AI agent works in your codebase — and almost everyone either skips it or stuffs it. Write it like a briefing for a sharp teammate: the commands, the architecture that isn’t obvious, the conventions that matter, the traps that bite. Cut everything they’d discover on their own. Then keep it honest.

Do that, and the agent stops re-learning your project every session and starts acting like it already knows it.

Going deeper on agentic coding? See Claude Code — Guides & Deep Dives and AI Coding Agents — Agentic AI for Developers, or the official Claude Code documentation for the full feature set.

Explore more: Claude Code · AI Coding Agents · LLM Engineering