The 4 Lines Every CLAUDE.md Needs

If you only have time to write four lines of CLAUDE.md, write these four. They are the lines that, in audits across about a hundred projects, separated the CLAUDE.md files that visibly carried weight from the ones that drifted into the dead-letter pile. They are the lines whose absence reliably correlated with "the agent did something I didn't want," and whose presence reliably correlated with "the agent's first decision was the right one." This piece is about which four lines, why those four, and what they each do that no other line can.

Why four

The number is empirical, not aesthetic. We catalogued the rules that appeared in CLAUDE.md files we considered well-written, looked for the rules that appeared in most of them, and ranked by impact on observed agent behavior. Above four lines, the marginal value drops off fast — line five matters less than line four, line ten matters less than line five. Below four, the file is missing something that audits flagged in nearly every project that didn't have it. So four became the operational floor.

This is not the same as saying four lines is enough. Four is the minimum. Most working files are 100-250 lines. But if you ship a CLAUDE.md with only the four below, you have already captured most of the value that prose can add. Everything beyond four is refinement.

Line one: what this project is, in one sentence

This is a real-time collaboration tool for editing shared documents
in the browser. TypeScript, React, Yjs, Postgres, Redis. Deployed on Fly.io.

The agent needs to know what kind of project this is before it has read a single source file. The first sentence prevents an entire class of bad early decisions: the agent suggesting database migrations for a frontend-only project, proposing browser polyfills for a Node script, optimizing for mobile in a desktop-only tool. Without this line, the agent infers from package.json and src/ structure, which usually works but occasionally produces a confident misclassification that derails the session.

The line should answer three questions: what does it do, what is it built with, where does it run. Twenty-five words is enough. If you cannot describe your project in twenty-five words, the agent's confusion in the first session is your warning that the project itself lacks a clear identity.

Line two: how to make changes — the process rule

All changes go through PR. No direct pushes to main. Tests must pass before merge.

Process rules separate "the agent did something good" from "the agent shipped something to production at 3am." Without the process line, the agent's defaults take over, and the defaults are often "do whatever the user asks." If the user asks for a quick fix, the agent will push to main. If the user is in a hurry, the agent will skip the test run.

The process line tells the agent what is non-negotiable about the way changes happen. Three sub-rules cover most projects: branching policy, push policy, gating policy. Some projects add review policy, commit-message policy, or merge strategy. Four to six rules in this line is fine; the irreducible core is "where do changes start, where do they end up, what gates them."

This is also the line that needs an enforcement pair. CLAUDE.md describes; hooks enforce. The line "no direct pushes to main" is wishful thinking unless there is a pre-push hook or a branch protection rule actually blocking the push. Pair this line with ~/.claude/scripts/push-gate.sh or equivalent, and now the rule has teeth.

Line three: the language and style commitment

TypeScript with strict mode. No `any`. State via Jotai (Redux/Zustand
deprecated). Tests live next to source as `<name>.test.ts`.

The language and style line tells the agent what the project's technical choices already are, so it does not propose alternatives. Without this line, the agent will sometimes look at the project and propose migrations that the team explicitly chose not to do. "This codebase looks like it should use Pinia" — except the team picked Zustand for specific reasons. "TypeScript would be cleaner with branded types here" — except the team has a rule against branded types. The line preempts these proposals.

Three sub-rules in this line cover most cases: language pinning (TypeScript strict, Python with uv, etc.), framework pinning (which library for state, which for forms, which for routing), structural conventions the linter does not catch (where tests live, what naming uses kebab-case vs PascalCase). Five to ten rules in this line is typical.

The 2026 best practice is to capture the deprecated choices explicitly. "State via Jotai (Redux/Zustand deprecated)" is more useful than "State via Jotai" because it tells the agent which proposals to actively avoid. Agents reading the code can deduce that Jotai is in use; they cannot deduce that Redux was tried and rejected.

Line four: the principle that catches edge cases

Don't add error handling for cases that can't happen. Trust internal
code; validate at boundaries. Three identical lines is better than a
premature abstraction.

The principle line is the one that handles cases the other lines do not cover. Specific rules tell the agent what to do when the case is named; principles tell the agent how to reason when the case is not named. Without principles, the agent's defaults take over, and the defaults are usually "be defensive, abstract early, handle every case" — which is fine for some projects and exactly wrong for others.

Three to seven principles is the operational range. Each principle should have a one-sentence rationale, even if you don't write it down — the rationale lets the agent apply the principle to edge cases the rule does not explicitly cover. "Don't add error handling for cases that can't happen — because the handling code itself becomes a maintenance burden and obscures the real failure modes" applies cleanly to a case the rule's surface form does not name.

The hardest part of the principles line is keeping it short. Principles are seductive; once you start writing them, every team value wants to become one. The discipline is to ask: would removing this principle change a decision the agent would otherwise get wrong? If yes, keep it. If no, delete it.

What the four lines do together

Each line covers a different layer of the agent's decision space. Line one orients the agent ("what world am I in"). Line two constrains the agent's actions ("what can I not do"). Line three steers the agent's choices ("what defaults apply"). Line four guides the agent's edge-case reasoning ("what do I do when no rule applies").

Without line one, the agent operates on inferred context, which is right most of the time and wildly wrong occasionally. Without line two, the agent ships things you wouldn't have shipped. Without line three, the agent proposes migrations you don't want. Without line four, the agent's edge cases default to its training, which is averaged over millions of projects and probably not optimized for yours.

The four lines together produce an agent that, in the first session, makes decisions that look like decisions you would have made. That is the whole game.

What the four lines deliberately omit

It is worth saying what these four lines are not trying to do.

They do not constitute the whole CLAUDE.md. Operational notes (the symlink that catches everyone, the flaky CI step), communication style (English / Chinese, terse / verbose), and meta-rules (review cadence, override declarations) all belong in the file. They just do not belong in the irreducible four.

They do not replace enforcement. Each of these lines needs a corresponding mechanism — process line needs hooks, style line needs linter config, principles need code review or AgentLint sweeps. The CLAUDE.md prose is the briefing; the harness is the enforcement.

They do not replace AGENTS.md or .cursor/rules. If your project has multiple agent harness files, each needs its own four lines (or pointer to a shared source of truth). The four-line discipline applies file-by-file.

A challenge

If you have an existing CLAUDE.md, here is a useful exercise. Open it, find the four lines that map to "what this project is," "how changes happen," "language and style," and "principles." If your file does not have all four, add the missing ones. If your file has more than four lines competing for any one slot, consolidate.

If you do not have a CLAUDE.md yet, write the four lines first, ship them, and let the file grow only when you observe specific agent behavior that justifies a new rule. The first session with the four lines will be 80% as good as the first session with a 200-line file. The second session, after you have observed which rules are actually load-bearing, you will know what to add — and the additions will be better than anything you could have predicted before you saw the agent in action.

The four lines are not the destination. They are the launchpad. But shipping the launchpad is the part most projects skip, which is why so many CLAUDE.md files start at line one hundred without ever having been useful at line four.