How to Write a CLAUDE.md File (That Actually Helps)

You explain the same three things to Claude Code every session — the test command, the folder it must never touch, the fact that your API lives in packages/api. A CLAUDE.md file kills that loop. It’s the standing memory Claude reads before it reads your first message, and writing a good one is the biggest single upgrade you can make to how the tool behaves.

What a CLAUDE.md file actually is

CLAUDE.md is a plain Markdown file that Claude Code loads into context automatically at the start of every session. Think of it as project memory or standing instructions — the model has already read it before you type a word. There’s nothing magic about the format; it’s just Markdown. What makes it powerful is timing: it lands at the top of the session, so the rules you put there shape every response that follows.

The catch is that because it loads every single session, it costs you tokens every single session. That tension — useful context versus token weight — is the whole game. Every line has to earn its place.

Where it lives, and which file wins

A CLAUDE.md can sit in a few places, and they all get merged. More-specific beats more-general:

• Project memory — ./CLAUDE.md at your repo root. This is the big one. Commit it; everyone who clones the repo gets it. Team conventions and project facts go here.
• User memory — ~/.claude/CLAUDE.md. Applies to you across every project. Personal preferences: your name, how you like commits written, tools you always reach for.
• Subdirectory memory — a CLAUDE.md inside a subfolder. Loaded only when you’re working on files under that subtree. Gold for monorepos — the frontend folder carries its own rules without polluting the backend’s context.

(An org can also enforce a managed policy file above all of these, but most people never touch that.)

The merge rule matters in practice. If your root file says “use tabs” and packages/web/CLAUDE.md says “use 2-space indent,” the web one wins while you’re in that folder. Lean on that instead of cramming every exception into one giant root file.

Bootstrap it with /init, then cut

Don’t start from a blank page. Inside Claude Code, run:

/init

It reads your codebase and writes a starter CLAUDE.md — build commands, structure, the obvious conventions. Treat it as a first draft, not gospel. The auto-generated version is almost always too long and too polite (“follow best practices,” “write clean code”). Your job is to cut it down to the lines that actually change behavior.

What actually earns a line

The test for every line: would Claude do something different because this line exists? If not, delete it. The stuff that earns its place is concrete:

• Exact commands. Write npm test, not “run the tests.” Write npm run lint -- --fix. Claude should never have to guess your scripts.
• Project structure + key files. “API handlers live in src/routes/, shared types in src/types.ts.” Saves a dozen searches per session.
• Code style you actually enforce. Named exports only. No default exports. Validate every route input.
• Workflow rules. Branch naming, commit style, PR conventions.
• Explicit do-NOT landmines. “Never edit generated/ — it’s rebuilt.” “Do not run migrations against prod.” These are the highest-value lines in the whole file.
• Environment gotchas. “Tests need DATABASE_URL set.” “This project is ESM — no require.”

What does not earn a line: aspirations. “Be thoughtful.” “Follow SOLID.” Vague vibes waste tokens and the model skims right past them. Specific, testable rules work; vibes do not.

A CLAUDE.md skeleton you can steal

Here’s a tight starting shape — short bullets under ## headings, no paragraphs:

# Project: acme-api

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint -- --fix`
- Dev server: `npm run dev` (port 3000)

## Structure
- `src/routes/` — HTTP handlers
- `src/db/` — schema + queries
- `src/types.ts` — shared types (import from here)

## Conventions
- Named exports only, no default exports
- Validate every route input
- Errors: throw `AppError`, never bare strings

## Do NOT
- Never edit `src/db/migrations/` by hand — generate them
- Never commit `.env`
- No new dependencies without asking

There’s no filler in there. Every line changes what Claude does, and the whole thing is scannable in a few seconds.

Imports: keep it modular with @

You don’t have to stuff everything into one file. Pull other files in with @path syntax:

See @docs/architecture.md for the request lifecycle.
Personal prefs: @~/.claude/my-preferences.md

Imports can nest up to 5 levels deep, so a root file can pull in a doc that pulls in another. One caveat worth knowing: an @ inside a fenced code block is not treated as an import — which is exactly why the examples above are safe to show without accidentally sucking in files.

The old CLAUDE.local.md convention for personal, un-shared notes is deprecated. Instead, gitignore a file and import it:

@.claude/local-notes.md

That keeps your personal scratch out of the shared repo while still loading it into your own sessions.

Quick-add memories mid-session

The best CLAUDE.md files grow by accretion. The moment you catch yourself re-explaining something to Claude, add a line — you don’t even have to open the file. Start a line with # and Claude appends it to a memory file:

# always use pnpm, not npm, in this repo

To edit the files directly:

/memory

That opens your memory files so you can prune and reorganize. Do it periodically. Dead rules are worse than no rules: they burn tokens and dilute the rules that still matter.

Keep it tight — it’s a token budget, not a wiki

Because CLAUDE.md rides in the context window every session, a bloated one taxes every request you make. That’s doubly true if you run Claude Code on a metered plan or a cheaper backend. I run a lot of my sessions against the GLM models to keep costs near zero — if you want that setup, I wrote it up in how to set up Claude Code with the GLM API. The plan I actually use for that is the z.ai GLM Coding Plan: that’s a referral link, disclosed, and it helps fund our compute — https://z.ai/subscribe?ic=BWTG6TRYYQ. On a lighter model a tight CLAUDE.md matters more, not less — weaker models follow short, concrete rules far better than rambling ones.

The same discipline that makes a good CLAUDE.md — specific, reusable, testable instructions instead of vibes — is what makes a good prompt anywhere. If you write instructions for agents all day, Meta-Prompt Architect is the tool I built for turning rough intent into reusable, high-signal prompts so those cheap tokens actually do real work.

Troubleshooting: the stuff that actually breaks

Claude ignores half your file. Usually it’s too long or too vague. If a rule isn’t testable, the model treats it as noise. Cut aspirations, keep commands and do-NOTs. Shorter files get followed harder.

A rule applies everywhere when you meant it for one folder. You put it in the root ./CLAUDE.md. Move folder-specific rules into a subdirectory CLAUDE.md so they only load under that subtree and don’t waste context elsewhere.

Two rules contradict each other and Claude picks the wrong one. Remember the merge order — more-specific wins. If root says one thing and a subfolder says another, the subfolder wins there. Grep your own files when behavior surprises you; a stale line from three months ago is often the culprit. This is also why /memory housekeeping matters.

Where this fits

A CLAUDE.md is your project’s standing context, but it’s one piece of a bigger setup. Once your rules are tight, the next wins are usually tooling and repeatable actions: wiring up data sources via how to add an MCP server to Claude Code, and canning your repeated workflows with how to create a custom slash command in Claude Code. And if you’re moving on to build your own agent from scratch, the same “concrete over aspirational” mindset carries straight into how to write a system prompt for an AI agent. Get the CLAUDE.md right first — it’s the cheapest, highest-leverage lever you’ve got.