How to Write a CLAUDE.md That Actually Improves Output

I've read a lot of CLAUDE.md files over the last few months, and most of them make the same mistake: they try to hold everything.

Tone preferences. Team values. Random reminders. Half an onboarding doc. By the time Claude gets to the part that actually matters, the useful instructions are buried.

That is when the usual problems show up. Claude runs the wrong command, edits the wrong layer, or turns a small fix into a much wider change than anyone asked for.

Anthropic describes CLAUDE.md as project memory loaded at the start of a session. That is exactly why this file needs restraint. Every vague paragraph takes space away from the few local facts Claude actually needs.

The version that works is usually short and practical. Claude already knows how to write code. What it does not know, at least not yet, is how your repo is laid out, which commands are real, which shortcuts are forbidden, and what your team considers out of bounds.

What belongs in the file

You are not trying to restate software engineering. You are filling in the gaps Claude cannot infer reliably from a quick scan of the repo.

That usually means:

• the commands that actually work in this project
• the boundaries between layers
• the mistakes that are expensive enough to preempt
• the working style you want during changes

Anthropic's guidance here is straightforward: keep the file specific, concise, and well structured, ideally under 200 lines. That tracks with what I have seen in practice. Once these files get bloated, they get less useful.

1. Start with commands

If Claude does not know how to build, test, lint, or type-check your project, it will improvise. I've seen it reach for npm in a pnpm repo, call the wrong test runner, or use a path format the tooling does not accept.

This is the highest-leverage place to be explicit.

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test single: `pnpm vitest run path/to/file.test.ts`
- Test all: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm tsc --noEmit`

A command section should read more like a cheat sheet than a policy doc. No explanation, no prose, just the exact command.

2. Add a codebase map

Claude starts with no local knowledge. If your repo has clear boundaries, say so.

## Architecture
- `src/lib/services/` -> business logic
- `src/components/` -> presentational UI only
- `src/app/api/` -> API routes, no business logic
- `src/lib/store/` -> global state
- Database access only through server actions or API routes

This section should help with placement, not documentation. You are not trying to mirror the file tree. You are trying to reduce bad architectural guesses.

Anthropic also supports subdirectory CLAUDE.md files that load when Claude works in those areas. That is usually a better pattern than turning the root file into a kitchen sink.

3. Write the rules that save you from expensive mistakes

Most teams either skip this section or fill it with generic values. Neither helps much.

Useful rules are concrete. Do not commit secrets. Do not introduce SSR. Run type check after edits. Keep changes minimal. Each line should point at a failure you have actually seen, or could easily imagine.

## Rules
- Never commit `.env` files or secrets
- Run type check after every code change
- Make minimal changes; do not refactor unrelated files
- Static export only; do not introduce SSR
- All async error paths must be handled explicitly

Anthropic's materials note that emphasis can help. I agree, but sparingly. If everything is marked IMPORTANT, nothing stands out.

4. Be explicit about how changes should happen

Quite a bit of frustration with coding agents is not about correctness. It is about pace and scope.

You wanted a targeted fix. The agent decided to clean up five related files while it was there. You wanted two options. It silently picked one and moved on.

## Workflow
- Ask clarifying questions before complex changes
- Prefer minimal edits
- Run relevant tests after each change
- Keep commits scoped to one logical change
- When two valid approaches exist, explain both before choosing

These instructions are less about code style and more about collaboration. When should Claude ask first? How broad should a change be? Should it run tests every time? Should it explain tradeoffs before choosing a path? If you care about those things, put them in writing.

What to leave out

If I open a CLAUDE.md and the first thing I see is "be a thoughtful senior engineer," I already know the file is wasting space.

Leave out:

• personality filler like "be a senior engineer"
• formatting rules your linter already enforces
• long pasted docs that belong elsewhere
• duplicated instructions across user, project, and local files
• anything Claude will learn faster by inspecting the repo directly

Anthropic now supports multiple instruction scopes: user-level, project-level, local overrides, and managed policy. That means you do not need to cram everything into one root file. Shared project rules belong in the project file. Personal habits belong in your user file. Machine-specific or private preferences belong in local overrides.

That separation is what keeps the main file readable.

A practical template

Here is a lean version that is actually worth copying:

# CLAUDE.md

## Project
Brief description of the product and who it serves.

## Stack
Framework, language, database, deployment target.

## Commands
- Dev: `[command]`
- Build: `[command]`
- Test single: `[command]`
- Test all: `[command]`
- Lint: `[command]`
- Type check: `[command]`

## Architecture
- `[path]` -> `[responsibility]`
- `[path]` -> `[responsibility]`
- `[path]` -> `[responsibility]`

## Rules
- `[Rule that prevents a real mistake]`
- `[Rule that prevents a real mistake]`
- IMPORTANT: `[The rule Claude must not break]`

## Workflow
- `[How to approach changes]`
- `[When to ask questions]`
- `[Testing expectations]`
- `[Commit expectations]`

## Out of Scope
- `[Areas not to touch]`
- `[Manually maintained files or integrations]`

I use one simple test for every line in a file like this: if I remove this, is Claude more likely to do the wrong thing? If the answer is no, cut it.

What you get out of it

A good CLAUDE.md does not magically improve the model. What it does is remove avoidable ambiguity.

That is enough to matter. You stop repeating the same corrections. Claude stops guessing quite so much. And the file becomes what it should have been from the start: a small set of local instructions about how this repo should be changed.

Look at it again whenever Claude gets something wrong. Tighten the line that would have prevented the mistake. Remove the ones that are only there because nobody wanted to delete them.

If you are trying to formalize how AI should behave inside a real product or delivery workflow, the more strategic next step is usually AI product strategy consulting.