CLAUDE.md is a product, not documentation

For our first year with Claude Code, our CLAUDE.md was documentation. We wrote it. We updated it occasionally. Nobody was formally responsible for it. It grew, it drifted, it accumulated inconsistencies. Standard documentation lifecycle. The shift that changed everything wasn't "write a better CLAUDE.md" — it was reframing it as a product rather than documentation. Same content, different mindset, dramatically different outcomes.

This post is the framing shift. Not "CLAUDE.md should be short" (which it should be — see the bloat post). Not "CLAUDE.md should be structured" (which it should be). The framing that fixed everything else: treat CLAUDE.md like a product with users, feedback loops, and measurable outcomes. Documentation gets neglected; products get maintained.

The documentation mindset vs the product mindset

Documentation and products both involve writing content that others consume. The differences look small on the surface; they compound to very different outcomes.

Documentation mindset:

• Written when the system is built; updated occasionally
• Success = "the docs exist"
• Ownership vague; often "whoever last touched the system"
• Feedback loop: users complain when docs are wrong
• Changes: whenever someone notices something
• Metric: does it cover the current state?

Product mindset:

• Continuously iterated based on how users engage with it
• Success = users get what they came for
• Ownership explicit; someone is accountable
• Feedback loop: instrumented; failure modes surface actively
• Changes: driven by user needs, tracked, reviewed
• Metric: does it produce the outcomes you want?

The differences compound. Documentation-mindset CLAUDE.md files decay because nobody's watching. Product-mindset CLAUDE.md files stay useful because someone is measuring whether they're working and iterating when they aren't.

Who your CLAUDE.md users actually are

The single most useful reframe: your CLAUDE.md has users. Treat them like real users of a product, not passive readers of a doc.

Your CLAUDE.md has two categories of user:

User 1: Claude itself

Every Claude Code session loads CLAUDE.md into context. The primary "user" of the file is Claude, generating code and answers informed by whatever's in the file. This user reads every session — literally 100% engagement.

What Claude needs from your CLAUDE.md is different from what a human documentation reader needs. Claude doesn't need onboarding narrative, historical context, or "why we chose this approach" essays. Claude needs clear, actionable guidance about what to do and what not to do in this codebase. Focused, specific, terse.

Test: does each paragraph of your CLAUDE.md give Claude a specific behavior change it should exhibit? If yes, it earns its place. If no — if it's "background reading" — Claude doesn't need it. Save it for the human onboarding doc.

User 2: The engineer maintaining CLAUDE.md

Every engineer who edits CLAUDE.md is a user of it — they need to understand its structure to update it safely. If your file has grown organically over months with no structure, this user has a bad time. Edits are risky ("will this contradict something I didn't see?"), so edits get avoided, and the file drifts further.

This user needs the file to be navigable, sectioned clearly, with obvious homes for different kinds of content. If a new engineer can't find where to add "our team's convention about X" in your CLAUDE.md, that's a product failure — the file's structure isn't serving its editors.

The product management practices that apply

Four standard product management practices adapt naturally to CLAUDE.md. All four transformed how we maintain ours.

Practice 1: Explicit ownership

One person is the "product manager" for CLAUDE.md. They're responsible for its coherence, they review changes, they drive iterations. This isn't glamorous work but it prevents the "everyone edits it, nobody owns it" pattern that makes documentation decay.

For us, the owner rotates every quarter. Rotation prevents burnout and brings fresh perspective. But at any given moment, one person is accountable for CLAUDE.md quality.

Practice 2: User feedback collection

Engineers who notice CLAUDE.md producing weird behavior — Claude following guidance that seemed correct but produced bad output, or ignoring guidance that should have applied — have a clear channel for reporting it. We built @feedback-claude-md, a lightweight tool for logging observations.

Feedback gets triaged monthly. Patterns across multiple feedbacks are especially valuable — they surface systemic issues with a specific section that individual reports don't reveal.

Practice 3: A/B testing (when it matters)

For significant CLAUDE.md changes, we sometimes run a lightweight A/B: half the team's sessions use the old version, half use the new, for a week. Compare outcomes (task success rate, cost per task, complaint rate). Pick the winner based on data rather than opinion.

This is overkill for small changes but valuable for structural ones. When we redesigned the CLAUDE.md structure, A/B testing gave us evidence the new structure actually produced better outcomes rather than just feeling better to write.

Practice 4: Outcome metrics

The metrics that matter for CLAUDE.md aren't "word count" or "sections present." They're outcome metrics: does Claude actually behave the way the guidance intends?

The specific outcome metrics we track:

• Compliance rate on stated conventions — sample generated code, check adherence to CLAUDE.md rules
• Rate of "Claude did X wrong" reports in the areas CLAUDE.md addresses
• Cost per session (CLAUDE.md bloat inflates this)
• New-engineer time to productive Claude Code use (proxy for how well the file onboards)

These are lagging indicators, measured monthly. When any trends the wrong way, it triggers investigation into whether CLAUDE.md needs adjustment.

The change management shift

The most visible practice change from the product mindset: how CLAUDE.md changes happen.

Documentation-mindset changes:

• Someone notices something wrong, edits it directly
• No review; commit lands
• No changelog; changes are invisible to teammates
• No rollback plan; if the change is bad, someone eventually reverts

Product-mindset changes:

• Changes proposed via PR
• Owner reviews; two-person approval for major changes
• Changelog entry required — what changed and why
• Rollback plan implicit (revert the commit)
• Big changes get a short "release note" to the team

This looks like a lot of process for a Markdown file. It's justified: CLAUDE.md changes affect every session for every engineer. Silently changing it produces silent behavior shifts nobody knows about. The process makes changes visible, reviewable, and reversible.

What "iterating" looks like in practice

The product mindset makes iteration continuous rather than episodic. What that actually looks like week-to-week:

Weekly: the CLAUDE.md owner reviews any feedback submitted that week. Small tweaks land as PRs; larger patterns get flagged for the monthly review.

Monthly: aggregate review of outcome metrics. Are compliance rates declining? Are certain sections producing repeated complaints? Any patterns that suggest structural issues rather than one-off problems?

Quarterly: deeper audit. Is anything in CLAUDE.md now obsolete? Any patterns that emerged that should be codified? Any structural changes worth A/B testing?

This cadence keeps CLAUDE.md alive. Documentation-mindset CLAUDE.md gets updated when someone happens to notice something. Product-mindset CLAUDE.md gets updated on a schedule, driven by data, based on user feedback.

The specific structural change that came from this

When we started measuring, one specific pattern emerged: engineers reported CLAUDE.md guidance being "ignored" in certain areas. Investigation revealed the guidance was there — buried in a long section that Claude wasn't attending to reliably.

The structural fix: reorganize CLAUDE.md into short, focused sections with clear headers. Each section is 2-4 paragraphs. Each section addresses one specific concern. Sections are ordered by importance (highest-priority guidance first).

This structure is optimized for Claude's attention pattern (lost-in-the-middle effect on long content) and for editor experience (easy to find where to add new guidance). Both users get better served.

The change came from data — user reports of guidance being ignored, backed by measurement of compliance rates — not from opinion. This is what iteration driven by outcome metrics looks like.

What the product mindset unblocks

Beyond keeping CLAUDE.md useful, the product mindset unblocks several things that documentation-mindset never gets to:

Deprecation confidence. When you know an old convention was replaced by a new one, you can confidently remove the old guidance — you'll see immediately if compliance rates drop. Documentation-mindset keeps old guidance around "just in case."

Experimentation. Try a new approach; measure whether it helps; keep or revert. Documentation-mindset treats CLAUDE.md as too authoritative to experiment with.

Team-wide learning. When one engineer discovers a pattern, it goes into CLAUDE.md as a proposal, gets reviewed, and becomes team practice. Documentation-mindset keeps such learnings on individual laptops.

Retrospective feedback loops. After incidents or difficult debugging sessions, "what would have helped Claude do this better?" becomes a CLAUDE.md improvement rather than a lesson someone remembers.

Where this framing doesn't apply

The product mindset is right for team CLAUDE.md files (shared, high-impact, worth investment). It's overkill for personal CLAUDE.md files (your own project, only you edit it, informal). The scale of investment should match the scale of impact.

Rough thresholds: if 3+ engineers depend on the CLAUDE.md, the product mindset pays for itself. If just one person uses it, the documentation mindset is fine — the maintenance overhead of the product mindset outweighs the benefit at that scale.

For anything in between (small team, shared but not high-volume), pick your practices. Explicit ownership always pays for itself. Change management may or may not. Outcome metrics may or may not. Take the practices that fit; skip the ones that don't.

The mindset shift is the whole thing

The practices that come out of the product mindset — ownership, feedback, A/B testing, outcome metrics, change management — are useful. But they're downstream of the framing. The framing is what changes everything.

If you treat CLAUDE.md as documentation, you'll naturally under-invest in it. Documentation is chore work; nobody's excited to write it; it decays. If you treat it as a product with real users and real outcomes, you naturally invest in it appropriately. Products get roadmaps, feedback loops, and iteration; they stay useful because they're treated as things worth iterating.

The specific practices matter less than the shift in what you're building. You're not writing docs. You're building a product that shapes how Claude works with your codebase. That framing makes better outcomes almost inevitable; the practices are just implementation details of the frame.