Writing and Maintaining CLAUDE.md

Knowing what CLAUDE.md does is one thing. Writing a good one is another skill entirely, and it's the one this page actually teaches, with a concrete checklist you can start applying to your own project today, not someday.

The checklist

Start with /init. Running it first in a new folder means starting from a generated draft instead of a blank page, which beats a blank page almost every single time, the four-step process shown below.

FIGURE 8 — /init: codebase → CLAUDE.md. Starting from a generated draft beats starting from a blank page.

Use bullet points, not paragraphs. Compress everything into high information density, cutting every word that doesn't earn its place on the page. Put your most important guardrails at the very top of the file, not buried three sections down where nobody reads carefully. Version-control the root CLAUDE.md like any other source file. Review and prune it on a regular schedule, the same way you'd review anything else that tends to accumulate cruft over time if nobody ever looks at it again.

FIGURE 9 — CLAUDE.md maintenance checklist. Six habits, all from the same source paragraph, none of them optional.

Try this with AI "Paste my current CLAUDE.md below. Check it against this six-item checklist and tell me which items it's missing, in order of how much each one would matter."

One more rule, and it's an easy one to break by accident: don't paste an unedited voice transcript straight into CLAUDE.md. Dictate your requirements out loud instead, then ask Claude to convert that raw transcript into a tight, structured summary of rules. Put critical restrictions first. That single habit alone solves most of the mess a raw, unedited transcript would otherwise leave behind in the finished file, long after you've forgotten exactly what you said.

Here's a small, real example of the process working. I needed a starting workflow for recreating website designs from screenshots. Rather than writing it by hand, I had another Claude instance summarize existing posts on the topic into a structured draft, which I then used and refined myself. Drafting a first-pass CLAUDE.md is itself something you can delegate, not something you're required to write alone from scratch.

Where you put things matters

Two effects shape how a long prompt actually gets read, and they matter more than most people assume. Primacy bias means Claude retains information near the beginning of a long prompt more strongly than information buried in the middle. Recency bias is the mirror image. It favors the very end. Figure 10 shows the shape of this clearly: strong at the start, weak in the middle, strong again at the end, which is exactly why guardrails belong at the top of the file and nowhere in between.

FIGURE 10 — Where Claude pays the most attention in a long prompt. Put guardrails at the top of CLAUDE.md, never buried in the middle where retention is weakest.

The practical consequence follows directly from that shape. Put your guardrails at the top. Don't bury them in the middle of the file, where the evidence says they're least likely to actually get weighted the way you intended when you wrote them down.

Treat it like living code

CLAUDE.md needs regular maintenance, not a one-time setup you finish and forget about forever. Left alone, it tends to accumulate unnecessary or overly specific instructions over time, especially if you let Claude update the file repeatedly on its own without ever sitting down to review what actually got added along the way. I compare this build-up to technical debt: individually reasonable, collectively a burden. Review it. Prune it. Treat every line as something that has to keep earning its place in the file.

Two more habits matter here. Don't dump an entire style guide or a full set of API docs into the file. Picture a complete PandaDoc integration costing roughly ten thousand tokens on every single session start, a hypothetical I use to make the point concrete: that's a real and recurring cost, not a one-time inconvenience you pay just once and move past. Ask Claude which sections you actually need, and keep only those. And when Claude makes the same mistake two or three times with some library or platform, write the fix down as a permanent rule, so the next fresh session starts already knowing what earlier sessions had to learn the hard way.

Keep the whole file short. Roughly two hundred to five hundred lines is the range. Treat five hundred as a hard ceiling, not a soft suggestion you can quietly ignore whenever it's convenient to do so. Past that point, split it into the scoped rule files covered on the previous page, rather than letting one file keep growing without any real limit in sight.

Avoid vague, aspirational instructions too. "Be smart," "make no mistakes," "make me a million dollars" are my own examples of what not to write. None of them work. They give Claude no real process, no real boundary, and no way to know when it has actually succeeded at the thing you asked for, so they end up doing no real work in the file at all, no matter how good they sound out loud.

Practices here move fast, faster than any fixed checklist could ever hope to keep up with on its own, this one included, which is worth admitting honestly rather than pretending otherwise. I search recent posts and ask an AI to summarize best practices drawn from roughly the past month, rather than trusting one permanent list written down years ago. That's a habit worth borrowing. Whatever specific tools you end up using, make it your own.