The biggest change between six-months-ago me and today's me isn't that I write code faster. It's that I almost never repeat myself to Claude anymore.
When I first started using Claude Code, every new session began the same way: "This project is Next.js 16, articles always ship as a Japanese/English pair, pushes happen from /tmp rather than the workspace..." Thirty seconds each time, sure. But once you're opening a dozen sessions a day, those thirty-second explanations become a surprising slice of the workday — and, more importantly, a surprising slice of your attention.
The fix was a single file: a real CLAUDE.md at the project root, maintained with actual care.
"Starting From Zero" Wears You Down Over Time
I want to be honest about my starting point. My first CLAUDE.md was ceremonial. I wrote something README-shaped, never revisited it, and assumed Claude would figure out the important stuff from surrounding context.
At that stage I treated re-explaining as a one-time cost. If Claude needed background, I'd give it — inline, in the moment. Cheap, right?
Six months later I understand what that approach was actually costing me, and it wasn't the seconds. It was the mental switching cost of summarizing your own project to a stranger, five or ten times a day. That's the kind of fatigue you don't notice until it's been eroding you for weeks.
My breaking point was embarrassingly small. I forgot to set highlights on a premium article three weeks in a row, and Claude didn't catch it — because I had never told Claude it was a rule. Claude wasn't the problem. The absence of a shared rulebook was.
That was where I started taking CLAUDE.md seriously.
What I Put in CLAUDE.md, and What I Deliberately Leave Out
Here's the line I've settled on after six months of editing.
What belongs in CLAUDE.md:
- Rules that should never bend (e.g. "every article ships in both Japanese and English")
- Project-specific workflow that isn't obvious from the code (directory layout, git conventions, deploy quirks)
- Lessons from past incidents, especially the ones that are easy to repeat
- The reasoning behind major design decisions — not just the decisions themselves
What I keep out:
- Anything Claude can learn by reading the code itself (class responsibilities, function signatures)
- Numbers that change often (current article counts, active users)
- Beginner-oriented explanations for someone who hasn't read CLAUDE.md before — this file is a team-internal handoff, not a tutorial
The criterion is simple: CLAUDE.md is loaded into every session automatically. Everything you write there gets processed on every conversation you start. If you overload it, the signal-to-noise ratio drops and Claude's judgment actually gets worse.
My CLAUDE.md for the Dolice Labs project eventually settled at around 500 lines. It started closer to 1,000. Trimming out "things you can learn from the code" made the remaining rules significantly easier to see and act on. If you want a more introductory overview of how memory works in Claude Code, my earlier piece Claude Code Memory Management Basics — How CLAUDE.md and MEMORY.md Actually Work walks through the building blocks.
Writing Down What Worked (Not Just What Broke)
The entries that produced the biggest lift weren't the failure logs. They were the ones that captured a successful pattern and made it explicit.
For example: "When changing any payment component, always verify bfcache handling, link consistency, button usage, and plan_type separation." That's a four-line checklist distilled from past incidents — but now that it's written down, both Claude and future-me execute the same judgment every single time.
### Required checks when modifying payment components
1. **bfcache handling**: buttons that redirect externally must reset loading state via `pageshow` + `event.persisted`
2. **Link consistency**: any `/support` or `/membership` link must match the current checkout flow
3. **Use `<button>`**: checkout triggers must call `/api/checkout` directly via `onClick`, not via `<a>` navigation
4. **`metadata.plan_type`**: keep `tip` / `premium` / `pro` strictly separatedCodifying "shapes of judgment" like this has one subtle benefit: the reasoning travels with the rule. When an edge case shows up, Claude (and I) can see why the rule exists and decide whether this situation might actually be the exception. Rules written as raw commandments — "do X", with no context — fall apart the moment reality wiggles.
Writing project context well is, in a real sense, a writing problem. The book that most reshaped how I approach it is The Art of Readable Code by Dustin Boswell and Trevor Foucher. It's technically about source code, but reread it as a book about any text meant to be read under pressure — CLAUDE.md included — and it becomes one of the most useful writing guides I know of.
Monthly Review, or It Slowly Goes Stale
CLAUDE.md rots if you leave it alone. A note that was load-bearing six months ago can be completely irrelevant now, and it'll just sit there, taking up attention on every session.
I set aside time once a month to review it. Three questions drive the review:
- Does this still describe a real problem? (workaround notes for bugs we've since fixed — out)
- Is this still consistent with the current design? (category-onboarding steps that don't match the new implementation — rewrite or delete)
- Has this rule actually been triggered in the last month? (never-referenced rules are noise, not context)
Skip this review and CLAUDE.md quietly degrades into something Claude learns to tune out. Keeping it trustworthy is what keeps its influence strong. If you want a taste of the broader operational story this sits inside, I wrote about it in How Cowork Transformed My Daily Workflow for Managing 4 Sites.
Where to Start If You Haven't
After six months, my CLAUDE.md feels less like a config file and more like a shared memory between me and Claude. The project and the rulebook grew in parallel, and at this point neither would fully make sense without the other.
If you don't have a CLAUDE.md yet, the most useful first step isn't to write a comprehensive one. It's to open the file, write down the one explanation you've already given Claude too many times this week, and save it. Tomorrow's session will be a little lighter. Next week, a little lighter still.
You don't have to build the whole thing at once. As long as the project is moving, the memory quietly fills in.