Creating the Perfect CLAUDE.md

The phrase "perfect CLAUDE.md" is a trap. There is no Platonic CLAUDE.md hovering above your project waiting to be transcribed. There is only the CLAUDE.md that fits your codebase, your team, your tooling, and your tolerance for ceremony — and the only useful definition of "perfect" is the one where the agent reads it once at the start of every session and behaves the way you would have behaved on a good day. This piece is about how to write that file, starting from a blank touch CLAUDE.md and ending with something that actually carries weight.

Why the blank-file version usually wins

When people ask "what should be in my CLAUDE.md," they often have a 400-line draft in front of them and want to know what to add. That is the wrong starting point. The drafts I've seen tend to bloat in two ways: copying lines from someone else's CLAUDE.md without checking whether they apply, or adding a rule every time something annoys the team without ever pruning. After a year, the file is half archeology and half wishful thinking.

Starting from a blank file forces a different question. Not "what could go in," but "what would the project actually break without?" That filter cuts the file by 70 percent on the first pass. The remaining 30 percent is usually closer to the real CLAUDE.md than any drafting-by-addition approach gets.

What "perfect" means operationally

A perfect CLAUDE.md, in practice, has three measurable properties. It is readable in one pass — somewhere between 80 and 250 lines, depending on project size, with no section over 50 lines. It is fully machine-checkable — every rule has either a check that runs in CI, a hook that runs locally, or a verifier that the agent can run on demand. And it is load-bearing — every rule, if removed, would change the agent's behavior in a way you'd notice within a week.

The last one is the strictest. If you remove a rule and nothing changes for two weeks, that rule was probably never doing anything. Either the behavior was already happening (rule redundant) or the agent was already ignoring it (rule advisory). Both cases are flags to delete.

The seven-step build

Here is the sequence I use when bootstrapping CLAUDE.md for a new project. It takes about an afternoon for a small repo and two days for a complex one.

Step one: write the project intro paragraph. One paragraph, 100 words or fewer. What this project does, who uses it, what stack runs it. No marketing. The agent uses this to disambiguate similar-sounding repos.

Step two: list the non-negotiables. What does the agent absolutely never do — push to main without a PR, edit lockfiles by hand, commit secrets, modify migrations after they're applied. Six to ten rules. Each one is a falsifiable, machine-checkable directive.

Step three: encode the language and style decisions. Which language(s) the project uses, which frameworks are blessed and which are off-limits, what naming conventions hold. Be specific. "Use TypeScript" is too vague — say "TypeScript with strict mode, no any, no implicit JSX returns." Three to six rules.

Step four: capture the operational gotchas. The path that's a symlink. The CI matrix that fails on Windows. The credential that expires every 90 days. The integration test that needs a real database. This is the section that pays back biggest, because each rule represents a specific bug avoided.

Step five: pick three to seven principles. Not aphorisms. Specific design rules with reasoning. "Don't add error handling for cases that can't happen" with a one-sentence rationale. "Trust internal code; validate at boundaries." Hard cap at seven; if you have ten, you have none.

Step six: wire enforcement. For every rule from steps two through four, add the corresponding hook, CI check, or verification command. If a rule cannot be enforced mechanically, mark it explicitly as advisory in the file — don't pretend it's enforceable.

Step seven: run AgentLint and fix what it flags. Stale paths, contradictions, vague rules, missing thresholds. The linter is the last-mile sweep that catches the kind of drift you can't see when you're the one who wrote the file.

What to leave out, deliberately

The single biggest improvement to most CLAUDE.md files is what gets cut, not what gets added. Some categories that almost always belong elsewhere:

Architecture documentation. CLAUDE.md is not the place for ADRs (architecture decision records), system diagrams, or design history. Put those in docs/ and link from CLAUDE.md if needed. Architecture docs read once at session start are mostly wasted context budget.

Onboarding instructions. "Run npm install then npm run dev" belongs in README. CLAUDE.md is for the agent's session, not for a human contributor's first day. The onboarding doc and the agent rules diverge fast.

Aspirational values. "We value collaboration." This isn't actionable. Either turn it into a specific behavioral rule or move it to a values doc.

Background on past decisions. "We tried Redux, then Zustand, then settled on Jotai." Interesting context for humans, dead weight for agents. If the rule is "use Jotai," that's all the agent needs.

Marketing copy or external pitches. If you find yourself writing for an audience other than the agent, you are writing the wrong file.

A worked example

Here is a CLAUDE.md from a real project, before the seven-step rewrite. The original file was 380 lines:

## Overview
We are a passionate team building the next generation of...
[180 lines of mission, history, philosophy]

## Coding Standards
- Write good, clean code
- Follow best practices
- Be careful with errors
- Test thoroughly
[60 lines of similar rules]

## Architecture
[100 lines of system diagrams in ASCII art]

## Onboarding
[40 lines of git clone / npm install instructions]

Same project, after seven-step rewrite. 142 lines:

## Project
A real-time collaboration tool. Users edit shared documents from
their browsers; conflict resolution is CRDT-based. Stack: TypeScript,
React, Yjs, Postgres, Redis, deployed on Fly.io.

## Non-negotiables
- All changes through PR — no direct pushes to main.
- Tests must pass before merge — Vitest unit + Playwright E2E.
- No edits to bun.lock by hand. Use `bun add` or `bun remove`.
- No secrets in commits — `.env*` is gitignored, secrets via 1Password.
- Migrations are append-only — never modify a migration after it's applied.

## Language & Style
- TypeScript strict mode. No `any`. No implicit JSX returns.
- Components are functional with hooks. No class components.
- State: server state via TanStack Query, client state via Zustand.
- File naming: kebab-case for files, PascalCase for components.
- Tests live next to source as `<name>.test.ts`.

## Operational notes
- `apps/web/` builds with Vite, `apps/api/` builds with esbuild.
- Local dev needs Docker (Postgres + Redis) — see `pnpm dev:up`.
- Playwright requires Playwright browsers installed: `pnpm exec playwright install`.
- CI matrix runs on Linux only — local Windows/macOS issues won't fail CI.

## Principles
- 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.
- If a rule isn't enforced by a hook or CI, it's advisory.
- Comments explain WHY, never WHAT.
- When stuck, write less code, not more.

## Enforcement
- Pre-commit (Husky): lint, typecheck, format on staged files.
- Pre-push: full unit test suite.
- CI: lint + typecheck + unit + Playwright on PR.
- Required status checks: ci-lint, ci-test, ci-e2e.
- AgentLint runs in CI on changes to CLAUDE.md.

Same project, same intent, 60% smaller, 100% machine-checkable. The agent reads this file in under a second and knows exactly what world it is operating in.

Why this is worth the afternoon

The cost of a bad CLAUDE.md is silent. The agent makes 80 decisions per session you never see, and each of them is biased by the file. A 380-line CLAUDE.md full of vague advice doesn't crash; it just produces a slightly worse PR than the 142-line version would have. Multiply that by every session for a year and the gap is large. The file is the boot sequence for an autonomous program. Spending an afternoon getting it right pays back the moment the agent starts a new session — which it does dozens of times a week.

If you want a starting point, AgentLint ships a --init mode that generates a 70-line skeleton matching the seven-step structure above. Run it, fill in the blanks, run AgentLint against the result, and commit. That's the perfect CLAUDE.md for your project — the one that exists, is correct, and the agent actually reads.

Originally posted on agentlint.app/blog/creating-the-perfect-claude-md.