What to Include in CLAUDE.md

Every line in CLAUDE.md is read on every session in that project, whether or not it’s relevant to the task at hand — which makes “should this be in here” a real question with a real cost, not a rhetorical one. A practical test: would explaining this to a new hire on their first day meaningfully change how they work in this codebase? If yes, it likely belongs. If it’s true of good software engineering in general, it doesn’t.

The Core Categories

Commands. The exact commands for testing, building, linting, and running the project — not “run the test suite” but the actual invocation, including how to target a single file or test case. This is the single highest-value, lowest-effort category: an agent that knows precise commands stops guessing and iterating slowly.

Architecture and structure. A brief map of how the codebase is organized and why, when the why isn’t obvious from directory names alone — which service owns which responsibility, which layer talks to which, where the boundaries deliberately are.

Conventions. Team-specific choices that a generic best-practices default wouldn’t get right: naming patterns, import styles, error-handling conventions, testing philosophy (unit-heavy vs. integration-heavy, colocated tests vs. a separate tree).

Gotchas and warnings. Genuinely non-obvious traps — code that looks safe to delete but isn’t, a directory that’s generated and shouldn’t be hand-edited, a dependency version pinned for a specific reason that isn’t visible from the pin alone. This category has the highest value-per-line of anything in the file, because it’s the one an agent has no other way to discover.

What Doesn’t Belong

Generic best-practice advice. “Write clean code,” “add tests,” “handle errors properly” — true of every codebase, and therefore informationally empty. An agent capable of using CLAUDE.md meaningfully doesn’t need to be told this.

Anything the agent can read directly from the code. If a convention is fully enforced by a linter config or a type system, restating it in prose adds redundancy, not information — the config is the documentation in that case.

Frequently-changing state. Current sprint priorities, “what we’re working on this week,” a specific bug being investigated right now — this belongs in your actual conversation with the agent, not in a file that’s supposed to represent standing, durable context.

Exhaustive API documentation. If your project has (or should have) proper API docs, link to them rather than duplicating their content into CLAUDE.md — the file should orient the agent toward where deeper information lives, not try to contain all of it itself.

A Useful Mental Model

# Ask of every candidate line: "Is this durable, specific, and non-inferable?"

Durable        — true for months, not just this sprint
Specific       — true of THIS codebase, not codebases in general
Non-inferable  — not already visible from reading the code or config directly

A line that fails any one of these three tests is a candidate for cutting. “Use TypeScript strict mode” fails non-inferable if tsconfig.json already enforces it. “We’re currently migrating auth to a new provider” fails durable. “Write good code” fails specific.

Common Mistakes

Optimizing for completeness instead of leverage. A file that tries to document everything ends up diluting the handful of genuinely high-value lines (the real gotchas) among a much larger volume of low-value filler — shorter and higher-signal beats longer and exhaustive.

Copying boilerplate CLAUDE.md templates wholesale without adapting them. Generic templates are a reasonable starting structure, but their example content is, by definition, generic — every section needs to be rewritten with your project’s actual specifics or deleted.

Never removing content that’s become stale. An outdated gotcha (“this endpoint doesn’t support pagination yet” — written before pagination was added) actively misleads rather than merely wasting space; stale content is worse than no content on that topic.

Frequently Asked Questions

Should CLAUDE.md include the project’s business domain context (e.g., what the product does)? A brief orientation is often worth including if it changes how the agent should reason about the code (e.g., “this is a medical records system — patient data fields require extra care around logging”), but a full product pitch isn’t necessary for an engineering-context file.

How do I know if something is “obvious from the code” or genuinely needs stating? A reasonable heuristic: if a competent engineer reading the relevant files cold would reach the same conclusion in under a minute, it’s inferable and doesn’t need restating; if it requires knowledge of a decision, an incident, or a conversation that isn’t in the code, it belongs in CLAUDE.md.

Is there a maximum useful length? No hard number, but the practical ceiling is usually reached well before most people expect — a few hundred lines of genuinely high-signal content outperforms a much longer file, and if yours is growing past that, it’s worth auditing for content that’s drifted into the “doesn’t belong” categories above.

Summary

The durable-specific-non-inferable test is a fast, reliable filter for almost any candidate line: commands, real architectural context, team-specific conventions, and genuine gotchas pass it; generic advice, inferable-from-code facts, and transient state don’t. Apply it consistently and CLAUDE.md stays a high-signal asset instead of drifting into padding nobody benefits from re-reading every session.