CLAUDE.md Best Practices: Keeping Your AI Setup From Going Stale

Your CLAUDE.md started clean. Then it grew: a rule here, a gotcha there, a paste of half your architecture doc. Now it is long, half of it is out of date, and Claude Code either ignores the important lines or follows a convention you dropped three months ago. A good CLAUDE.md is one of the most valuable files in your repo. A bloated, stale one quietly makes Claude worse. This is how to keep yours lean, useful, and current.

Key takeaways

• CLAUDE.md is a plain-text file Claude Code reads at the start of every session. Put the durable facts and rules that do not fit in the code itself.
• Keep it lean. A short, high-signal file beats a long one, because everything in it competes for the model's attention.
• Structure it with clear headings: what the project is, commands, conventions, and the things Claude keeps getting wrong.
• The two most common failures are bloat (pasting docs the AI does not need) and staleness (rules that no longer match the code).
• CLAUDE.md tells the AI how to work; your facts about yourself and your world are a separate thing. Both go stale by hand unless something keeps them current.

---

What CLAUDE.md is and where it lives

CLAUDE.md is a plain-text file that Claude Code loads automatically at the start of a session and treats as standing instructions. It is the closest thing Claude Code has to memory you control directly, because you can see it, edit it, and version it like any other file.

There are a few places it can live, and they stack:

• Project root (./CLAUDE.md): rules for this repo. Commit it so the whole team shares it.
• Home directory (~/.claude/CLAUDE.md): your personal rules that apply across every project.
• Subdirectory (./packages/api/CLAUDE.md): scoped rules that only matter inside that part of the tree.

Claude reads the relevant files for wherever it is working, so the closer file adds detail to the broader one. The mental model that helps: CLAUDE.md is the onboarding note you would write for a sharp new contractor who has never seen your codebase but is a strong engineer. You do not re-teach them how to code. You tell them the things that are specific to you and would take them a while to discover.

What to put in CLAUDE.md

The best CLAUDE.md files hold the durable, project-specific facts that are not obvious from reading the code. Concretely:

• What the project is, in two or three lines. The one-sentence purpose and the shape of the stack.
• Commands that matter. How to run tests, start the dev server, lint, build. The exact commands, so Claude does not guess.
• Conventions you always follow. "Use the existing db.query helper, never raw SQL." "Prefer composition over inheritance here." "All API responses go through formatResponse."
• Things Claude keeps getting wrong. This section earns its keep. Every time the AI makes the same mistake twice, write the correction here once.
• Boundaries. What not to touch, what is generated, what is deprecated but still present.

The test for any line is simple: would a strong engineer who is new to this repo need to be told this, and would it save real time? If yes, it belongs. If it is generic advice any competent developer already knows, or something the AI can read straight from the code, leave it out.

What to keep out of CLAUDE.md

Just as important is what does not belong, because everything in the file competes for attention.

• Do not paste whole docs. A link or a one-line summary beats a wall of pasted architecture. The file should point, not duplicate.
• Do not restate the obvious. "Write clean code" and "add tests" are noise. The model already knows.
• Do not include secrets. No keys, tokens, or credentials. The file is committed and read every session.
• Do not let it become a changelog. History belongs in git. CLAUDE.md is the current state, not the story of how you got here.

Every extra line dilutes the signal of the lines that matter. A tight 40-line file that Claude actually follows is worth more than a 300-line file it skims.

How to structure it: a copyable example

Use clear Markdown headings so the model can find the relevant part fast. Here is a real, copyable skeleton you can adapt. It is deliberately short.

# CLAUDE.md

## Project

Billing service for the app. Node + TypeScript, Postgres, deployed on Fly.
Handles subscriptions, invoices, and webhooks from Stripe.

## Commands

- Install: `pnpm install`
- Dev server: `pnpm dev`
- Tests: `pnpm test` (run before every commit)
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`

## Conventions

- Money is always integer cents, never floats. Use the `Money` type.
- All DB access goes through `src/db/queries.ts`. Never write raw SQL in handlers.
- API responses are wrapped by `formatResponse()`. Do not return bare objects.
- New endpoints get a test in `test/api/` in the same PR.

## Watch out for

- `stripe.ts` retries are idempotent by design. Do not add your own retry loop.
- The `legacy/` folder is deprecated but still live. Do not extend it; flag if touched.
- Webhook handlers must be fast. Offload real work to the queue in `jobs/`.

## Out of scope

- Do not modify migrations already applied (anything in `migrations/` dated before this month).

That file is short on purpose. Every line either tells Claude how to run the project, a convention it would not know, or a mistake it should avoid. Nothing is generic. If you want a leaner starting point, the Claude memory hub covers how CLAUDE.md fits alongside Claude's other memory forms.

Common mistakes that make it worse

Two failures ruin most CLAUDE.md files, and they are the reason the file often makes Claude less reliable over time rather than more.

Bloat. The file grows because adding a line feels free. It is not. A model reading a 300-line CLAUDE.md spreads its attention across 300 lines, and your three load-bearing rules get the same weight as thirty pieces of trivia. When Claude starts ignoring important instructions, the fix is usually to cut the file in half, not to add another line telling it to pay attention.

Staleness. This is the quiet one. You wrote "always use the useAuth hook" and then you migrated off it. The rule is still in the file. Now Claude confidently follows an instruction that is wrong, and you spend time undoing it. A CLAUDE.md only reflects reality on the day you last edited it. It does not know the code changed. Nobody schedules a "clean the CLAUDE.md" task, so it drifts, and a drifted setup file is worse than none because you trust it.

The maintenance answer is boring but real: treat CLAUDE.md like code. Review it when you review the code around it. When a convention changes, change the file in the same PR. And keep it small enough that reviewing it is not a chore.

A CLAUDE.md is only as good as its last edit.

CLAUDE.md tells the AI how. Your facts are a separate thing.

Here is a distinction worth holding, because it explains why even a perfect CLAUDE.md leaves a gap.

A CLAUDE.md tells the AI how to work in this project: the commands, the conventions, the rules. It is procedural. It is about the codebase, not about you.

Your facts are different. Who your users are, what you decided about pricing last week, your opinion on a library, the reason a feature exists, the context from the meeting that never made it into a doc. That knowledge is what makes an AI's output specific to your situation, and it does not belong in a per-project setup file. It is not procedure. It is memory.

Both have the same failure mode: they go stale by hand. A CLAUDE.md drifts when the code changes and you forget to edit it. Your facts drift the moment your world moves and nobody updates the note. The difference is that a CLAUDE.md is small enough to maintain if you are disciplined, while your facts are too many and too fast-moving to keep current by editing files. That is where a memory that updates itself earns its place: it watches your real activity, marks the old fact superseded when something changes, and keeps the AI working from the current truth without you filing a ticket against your own notes. A well-kept CLAUDE.md plus a self-maintaining store of your facts is a setup that stays fresh instead of decaying.

Frequently asked questions

What should go in a CLAUDE.md file?

The durable, project-specific facts that are not obvious from the code: what the project is, the commands to run it, the conventions you always follow, and the mistakes Claude keeps making so you can correct them once. Keep out secrets, pasted docs, generic advice, and history that belongs in git.

Where should the CLAUDE.md file live?

In the project root for repo-wide rules (commit it so the team shares it), in your home directory (~/.claude/CLAUDE.md) for personal rules across all projects, and optionally in a subdirectory for rules scoped to one part of the tree. Claude combines the relevant files for wherever it is working.

How long should a CLAUDE.md be?

Shorter than you think. Everything in the file competes for the model's attention, so a tight, high-signal file that Claude actually follows beats a long one it skims. If Claude starts ignoring instructions, cutting the file usually helps more than adding to it.

Why does my CLAUDE.md stop working over time?

Usually staleness or bloat. The file describes reality on the day you last edited it, so when the code changes and the file does not, Claude follows rules that are now wrong. And as the file grows, your important rules get diluted. Review it alongside the code and keep it lean.

Is CLAUDE.md the same as Claude's memory?

No. CLAUDE.md is a file you write and maintain that tells Claude how to work in a project. Claude also has a memory tool it writes itself and cross-chat memory in the consumer apps. CLAUDE.md handles procedure; your personal facts and decisions are a separate kind of context.

---

A great CLAUDE.md is worth keeping tight, because it is the one piece of your AI setup you fully control. But your setup is more than one file, and the facts that make your AI's output specific to you drift faster than you can hand-edit. Locul is a second brain that builds itself from what you already produce and keeps itself current on your machine, then serves that context to Claude Code and your other tools. Memory Packs help keep the knowledge side of your setup fresh. See how it works.