How-to

Write a CLAUDE.md that stops you repeating yourself

Updated Jul 10, 2026 3 min

If I had to name the one file that improved my Claude Code sessions the most, it is CLAUDE.md. It is the project's memory: a Markdown file Claude Code reads into context at the start of every session, so the things you would otherwise re-explain every single time, the build command, the conventions, the gotchas, are just known. Written well it saves you tokens and, more importantly, stops a whole class of wrong-context mistakes. Written badly it is bloat. Here is how I keep mine on the right side of that.

Why it matters

Everything you re-type into a prompt costs you twice: once in the typing, and once in the tokens it adds to the session. Worse, when you do not tell Claude a convention, it guesses, and a plausible guess that is wrong for your project is exactly the kind of mistake that is annoying to catch. CLAUDE.md fixes both. Say it once, in one place, and every session starts already knowing it.

What belongs in it

The test for anything you consider adding: is this durable (true across sessions, not just today) and does it change what Claude does? If yes, it earns its place.

  • How to run things. The build command, the test command, how to start the dev server, the lint command. These are the facts an agent needs constantly and guesses badly.
  • Conventions the code cannot show at a glance. "We use Preact, not React." "Never push without asking." "Components attach to window." The rules that are load-bearing but not obvious from any single file.
  • Architecture pointers. Where the important things live, so the agent starts in the right place instead of grepping around. A short map beats a long search.
  • Gotchas and hard rules. The landmines: the file that is a committed artifact you must hand-edit, the API you must not touch, the thing that looks wrong but is intentional.

What to leave out

CLAUDE.md is loaded into context every session, so every line is a small permanent tax. Keep it lean:

  • Not a substitute for reading the code. Do not paste file contents or duplicate what the code already says clearly. Point to where things are; let the agent read the detail on demand. This is the same context discipline that keeps a session lean, applied to the memory file.
  • Not a changelog or a diary. Yesterday's task notes do not belong here. Durable facts only.
  • Not everything you can think of. A focused half-page that gets read and followed beats three pages that dilute the important rules. If a section is not changing behavior, cut it.

Keep it honest over time

The failure mode is a CLAUDE.md that drifts out of date. A file that says the build command is npm run build when it is now npm run compile is worse than no file, because the agent trusts it. When something changes, update the file in the same breath. It is a living document, not a one-time setup.

A stale CLAUDE.md is a confident wrong answer waiting to happen. Treat a change to your build, your conventions, or your architecture as a change to CLAUDE.md too.

Two levels

You can have a project CLAUDE.md at the repo root (checked in, shared with anyone on the project) and a personal one at ~/.claude/CLAUDE.md that applies to everything you do. Put project truths in the former and your own preferences ("explain before you edit", "prefer small commits") in the latter. If you are starting from nothing, Claude Code can draft a first pass by scanning your project, which you then trim down to what actually matters.

The habit underneath it

A good CLAUDE.md is the same instinct as meta-prompting and planning first: front-load the clarity so you are not paying for it in repeated explanations and wrong guesses later. It is one of the quiet levers in the rundown of habits that run up your Claude Code usage, and one of the few that pays off on literally every session.

More in How-to

Serve a folder over HTTP in one line
Quick one-liners to serve the current directory over HTTP, no setup, when you just need to preview something.
Use Claude Code remotely from your phone or the web
Step away from your desk without stopping a Claude Code run. Turn on remote control and pick the session up from your phone, claude.ai/code, or another machine.
Stop running one giant chat: manage context in Claude Code
A long-running Claude Code session gets slower, pricier, and less accurate. Here is how I keep context lean, and the truth about what a big context window actually costs.
/clear, /compact, or a new session: when to reset Claude Code
Claude Code gives you two ways to trim a session and a third option to start over. Here is what /clear and /compact each do, and a simple rule for choosing.