Source confidence: high

Boris Cherny's CLAUDE.md — The Canonical Template

In short: Boris's own CLAUDE.md and the workflow rules he published on X became the de facto template that the wider community now cargo-cults. If you've seen a CLAUDE.md with sections like "Workflow Orchestration," "Self-Improvement Loop," and "Verification Before Done," you're looking at a descendant of Boris's file.

Key fact Detail
What it covers agents, LLM
Tools Anthropic, Claude, Claude Code
Posts covered 1 post (1 S-tier) · top: Boris Cherny's personal CLAUDE.md…
Creators @keshavsuki
Sources dated Mar 2026
Prompt system Run-it-yourself prompts
Last verified 2026-10-22

Author of the pattern: Boris Cherny — Anthropic staff engineer, creator of Claude Code (originally built as a side project in his first month at Anthropic; by the time Claude Code launched publicly in May 2025, over 80% of Anthropic's engineers were using it daily).

Why it matters: Boris's own CLAUDE.md and the workflow rules he published on X became the de facto template that the wider community now cargo-cults. If you've seen a CLAUDE.md with sections like "Workflow Orchestration," "Self-Improvement Loop," and "Verification Before Done," you're looking at a descendant of Boris's file. His team at Anthropic keeps a CLAUDE.md in git at roughly 2.5k tokens — the reference weight class.

This guide reconstructs the template, explains why each section exists, and compares it to a real-world global CLAUDE.md setup.

What it is

CLAUDE.md is the single highest-leverage file in the Claude Code harness. Claude Code injects it into the context window at the start of every session, before the user's first message. It's the only persistent memory primitive that survives compaction, resumes, and cross-session restarts. Nothing else — not chat history, not subagent output, not tool results — is guaranteed to stick.

Boris's core insight: CLAUDE.md is a compounding asset. Every correction you give Claude should be distilled into a rule in CLAUDE.md, so future sessions never make the same mistake twice. The file is not documentation for humans — it is a behavioral contract for the model.

How it works under the hood

Key mechanics (Boris's rules, annotated)

Boris's publicly posted rules crystallize into these sections. The exact wording varies by gist (there are at least four circulating community copies), but the structure is consistent:

1. Workflow Orchestration — "Plan first, execute second"

## Workflow
- For any non-trivial task (3+ steps or architectural decisions), enter plan mode first.
- Write the plan to disk before executing. Get explicit approval before you start editing files.
- Break work into phases. Each phase ends with a verification step.
- Never start coding without a written goal and a verification strategy.

Why: Claude's default behavior is to dive in. Forcing a written plan makes the model's reasoning visible, lets the human catch bad assumptions cheaply, and creates a contract it can check itself against later. This is the pattern the Superpowers writing-plans + executing-plans chain formalizes.

2. Subagents — "Keep the main context clean"

## Subagents
- Use subagents liberally. The main conversation is a precious resource.
- Dispatch anything exploratory (searching, reading unknown files, running tests) to a subagent.
- Subagents return summaries, not transcripts. You don't burn tokens on the tool noise.
- Parallelize independent tasks — spawn 3-5 subagents at once rather than serially.

Why: The main context window is where the actual planning and decision-making happens. Every file you read, every failed test output, every grep result eats tokens that could be used for reasoning. Subagents are a context-compression mechanism.

3. Verification Before Done — "Never claim completion without proof"

## Verification
- Before claiming any task is complete: run the tests, run the linter, run the type checker.
- If the user's request implies "it should work" — prove it works end-to-end, don't just compile.
- If you wrote a function, write a test. If you wrote a test, run it. If it fails, fix it.
- Never say "done" if you haven't verified. Say "I believe this is done pending X."

Why: The single most common failure mode of LLMs is confident false completion. Boris's rule: the model must produce evidence, not assertion.

4. Self-Improvement Loop — "Every correction becomes a rule"

## Self-Improvement
- When I correct you, end your response with:
  "Updating CLAUDE.md so I don't make this mistake again."
- Then actually update CLAUDE.md with a new rule that would have prevented the mistake.
- Ruthlessly edit CLAUDE.md over time. Delete rules that no longer apply. Merge duplicates.

Why: This is the compounding mechanism. Boris's own quote: "Invest in your CLAUDE.md. After every correction, end with 'Update your CLAUDE.md so you don't make that mistake again.' Claude is effective at writing rules for itself." Over weeks, Claude's mistake rate on your codebase measurably drops.

5. Autonomous Bug Fixing — "Reproduce, then fix"

## Bugs
- Before fixing: reproduce the bug with a failing test.
- The test must fail for the right reason (the bug), not a different reason (typo, missing import).
- Only then write the fix. Re-run the test. Confirm it passes. Run the full suite.
- If the bug is ambiguous, ask for clarification before coding.

Why: Mirrors TDD discipline and cuts the "fixed something unrelated" failure mode.

6. Project context (the boilerplate head of the file)

# Project Name
Language: Python 3.12
Framework: FastAPI + SQLAlchemy
Package manager: uv
Tests: pytest (run with `uv run pytest`)
Lint: ruff (run with `uv run ruff check`)
Typecheck: mypy (strict mode)

## Conventions
- Prefer dataclasses over dicts for structured data.
- All public functions get type hints.
- Never use `print` — use the `logging` module.
- Tests live in `tests/` mirroring `src/` layout.

Why: This is the cheap, obvious part everyone gets right. It's the behavioral rules above that distinguish Boris's template from a README.

Quick start

# In any project, scaffold a starter file
cd my-project
claude
> /init

# Then iterate — every time Claude makes a mistake, tell it:
> "That was wrong. Update CLAUDE.md so you don't do it again."

# Or use the # shortcut to append a rule inline
> # Always run `uv run pytest` not `pytest`

# Keep it lean — check length regularly
wc -l CLAUDE.md   # target: under 200 lines

Copy-paste starter (drop into any project root):

# [Project Name]
[One-line description.]

Stack: [language, framework, package manager]
Build: `[command]`
Test: `[command]`
Lint: `[command]`

## Workflow
- For any task with 3+ steps, enter plan mode. Write the plan before editing.
- Use subagents for exploration, searching, and reading unknown files.
- Never claim "done" without running tests + lint + typecheck.

## Conventions
- [Style rule 1]
- [Style rule 2]

## Verification
- Before shipping: `[test command]` && `[lint command]` && `[typecheck command]`
- All must pass. No exceptions.

## Bugs
- Reproduce with a failing test before fixing.
- Test must fail for the right reason.

## Self-improvement
- When corrected, update this file with a rule that would have prevented the mistake.
- Every rule in this file earned its place by catching a real bug.

Contrast with a global CLAUDE.md

A production global CLAUDE.md (~/.claude/CLAUDE.md) is a fundamentally different genre than Boris's per-project file. Key differences worth understanding:

Dimension Boris's template Global orchestrator
Scope Per-project behavioral contract Global meta-orchestrator across ALL projects
Length ~200 lines, ~2.5k tokens ~250 lines but dense with tables
Focus Workflow discipline (plan → execute → verify) Skill routing + knowledge base pointers
Self-improvement loop Yes — "every correction becomes a rule" Implicit via forge/retro/flywheel skills
Trigger mapping Not present Extensive — keyword → skill table
Domain knowledge Project-specific conventions AI3 resource catalog, installed plugins/MCPs
Security rules Not present Top-level CRITICAL block on secret protection

What a global file does that Boris's doesn't:

What Boris's file does that a global file typically doesn't:

The gap to close: A global CLAUDE.md can be excellent at orchestration but light on direct behavioral discipline — relying on the skill layer to enforce plan mode, TDD, and verification. Boris's pattern pushes that discipline directly into the file so it's enforced even in lightweight sessions where no skill was explicitly invoked. A hybrid per-project CLAUDE.md that inherits global triggers and adds a Boris-style Workflow/Verification/Self-improvement block would capture both.

Gotchas

  1. Length creep kills adherence. Past ~300 lines, Claude starts ignoring rules in the middle of the file. Ruthlessly prune.
  2. CLAUDE.md is not documentation. Don't write prose, write rules. "The foo module does X" is dead weight; "Always use the foo module's safe_parse, never parse" is a rule with teeth.
  3. Rules without teeth are ignored. "Prefer X" is weaker than "Never Y." Boris's negative-constraint framing ("NEVER commit with --no-verify") works because it names the exact failure mode.
  4. The self-improvement loop only works if you actually run it. The discipline is: every time you correct Claude, ask it to update CLAUDE.md. If you skip that step once, the loop is broken.
  5. Global + project files concatenate. Don't repeat global rules in every project file — Claude reads both.
  6. Community gists are not canonical. There are at least four different "Boris's CLAUDE.md" gists circulating. They agree on structure but differ on wording. Treat them all as reference, not gospel.

What we could build with it

Sources

Prompt system — run this yourself

Everything below is pasteable into Claude Code, Claude, or any agent. Use the one-shot when you want the whole result in one run; use the step prompts when you want to steer. Every step carries its own audit, and the gap audit at the end makes the agent find and fill what it missed.

Mission. Running this system turns Boris Cherny's CLAUDE.md pattern into a tested project file: a lean, project-specific CLAUDE.md under about 200 lines, rules that earned their place, deterministic hooks for the rules that must never break, and a small behavioural eval that measures whether the file changes what Claude Code does. It is for a developer who uses Claude Code daily and wants fewer repeated mistakes. Done means an A/B eval showing the new file beats the old one or no file on rule adherence, every absolute rule backed by a hook, and every claim in the guide about how CLAUDE.md loads checked against the installed version's docs.

1 · Deeper, not bigger

Before running anything, make the task deeper rather than larger. Ask: what would a top professional do here that I am not asking for; what is the rawest material; which methods and tools; what, other than the model or me, proves it right. Then ask for exactly that.

Rewritten prompt — ask for exactly that:

I want a CLAUDE.md for this project that measurably changes Claude Code's behaviour, using Boris Cherny's pattern as the starting point. Act as an engineer who treats prompts as code. First read the official Claude Code memory, settings, hooks and headless docs for my installed version, and check the guide's claims: how CLAUDE.md files are discovered and loaded, whether the # shortcut still appends to memory, and whether 'under 200 lines' is documented guidance. Then: (1) mine my git history and session transcripts for corrections I gave more than once; (2) draft a CLAUDE.md under 200 lines with project facts (real build, test, lint, typecheck commands from config), plan-first, subagent, verification, bug-reproduction and self-improvement sections, each rule tied to an incident or a stated reason; (3) move any rule that must never break into a PreToolUse hook or a permission setting; (4) build a 12-task headless eval with claude -p that tempts each rule, run it 3 times each with no file, the old file and the new file, and score adherence automatically. Report adherence per rule, token weight, which claims held, and which rules I should delete.

2 · One-shot prompt

ROLE AND STANCE
You are an engineer who treats CLAUDE.md as code: versioned, measured, tested. You keep the file short, tie every rule to a reason, and enforce absolute rules with hooks rather than prose. You verify every claim about Claude Code's behaviour against the installed version's documentation.

CONTEXT
- Guide: Boris Cherny, creator of Claude Code, published workflow rules that became the community template. His team's CLAUDE.md is about 2.5k tokens. Sections: Workflow Orchestration (plan mode for 3+ step tasks, written plan, phased verification), Subagents (keep the main context clean, return summaries, parallelize), Verification Before Done (tests, lint, typecheck, never claim done without proof), Self-Improvement Loop (every correction becomes a rule; ruthlessly edit), Autonomous Bug Fixing (reproduce with a failing test first), and a project-context head (stack, commands, conventions).
- Boris's quote as given in the guide: 'Invest in your CLAUDE.md. After every correction, end with Update your CLAUDE.md so you don't make that mistake again. Claude is effective at writing rules for itself.'
- Guide claims to check: CLAUDE.md files are auto-discovered at project root, ~/.claude/CLAUDE.md and parent directories, then concatenated and prepended to the system prompt; the # prefix appends a line to CLAUDE.md; files over about 200 lines measurably reduce adherence; over 80% of Anthropic engineers used Claude Code daily at public launch in May 2025.
- Contrast in the guide: a global orchestrator CLAUDE.md maps trigger words to skills and inventories tools; Boris's per-project file focuses on workflow discipline.

HARD CONSTRAINTS
- Final file under 200 lines and under 3k tokens, measured.
- Every rule has a reason or an incident reference in a comment or a linked lessons file.
- Absolute rules (never commit secrets, never push to main, never run destructive commands) get a hook or permission rule; prose alone is not enough.
- Commands in the file come from the project's real config (pyproject.toml, package.json, Makefile), and each is run once to confirm it works.
- Do not edit global ~/.claude/CLAUDE.md in this task.

DELIVERABLES, IN ORDER
1. claims.md: each guide claim with verified / outdated / unverified and the doc URL or test.
2. corrections.md: repeated corrections mined from git history and transcripts, grouped and counted.
3. CLAUDE.md (new) with a diff against the old one.
4. .claude/settings.json hooks and permissions for absolute rules, with a test showing each blocks a violation.
5. eval/: 12+ tasks, a runner using claude -p with JSON output, automatic scorers, and results for no file, old file, new file, 3 runs each.
6. report.md: adherence per rule per arm, token weight, rules to delete, open questions.

GAP ANALYSIS (BUILT IN)
Keep gaps.md: claims you could not verify for this version; rules the eval cannot score automatically; nondeterminism across runs; rules that improved adherence for one task but hurt another; any conflict between project and global files. Fill what you can.

SELF-QUESTIONS
- Which rules exist because of a real incident, and which are cargo-culted?
- Which rules does the model already follow with no file at all?
- Which absolute rule still relies only on prose?
- Does the file's length push important rules into the middle where they are ignored?
- Do my eval tasks actually tempt the violation, or are they too easy?

STOP CONDITIONS
Stop and ask if the project has no runnable test command, or if headless runs are not permitted in this environment. Otherwise stop when all six deliverables exist.

RETURN FORMAT
Table of deliverable, path, status; claims verdicts; adherence table per rule per arm; line and token counts; rules recommended for deletion; top five gaps.

3 · Step-by-step prompts

Step 1 — Ground truth: docs, version, current file

Goal: Know how this Claude Code version loads memory and what the project file says now.

Run claude --version and record it. Read the official Claude Code docs for memory, settings, hooks, slash commands and headless mode for this version.
Check each guide claim and write claims.md with verified, outdated or unverified plus the doc URL: discovery locations (project root, ~/.claude/CLAUDE.md, parent directories, nested subdirectories, any local or imported files); whether contents are prepended to the system prompt or injected another way; whether the # shortcut still appends to memory; whether /init and /memory behave as described; whether any doc states a size guideline; the 80% daily-use figure and its source.
In a live session run /memory and record which files are loaded for this project.
Copy the project's current CLAUDE.md to CLAUDE.old.md. Count lines and tokens for it, and list every command it names; run each command once and record whether it works.

Expect: claims.md, loaded_memory.md, CLAUDE.old.md, a command check table.

Audit before moving on: Every claim cites a doc URL or a test you ran. Any command in the old file that fails is marked for fixing in the new file.

Step 2 — Mine corrections

Goal: Find the mistakes that actually repeat in this project.

Search git log messages and diffs for reverts, 'fix' commits following agent commits, and edits to CLAUDE.md, and list what each was correcting. Search the project's Claude Code session transcripts (in the user's Claude projects directory for this repo) for user messages that correct the agent: phrases like 'no', 'wrong', 'don't', 'I told you', 'again', 'you broke'. Do not copy secrets or personal data from transcripts; quote only the correction gist.
Group corrections into themes (wrong command, claimed done without tests, edited the wrong file, ignored plan, touched production, verbose output). Count occurrences and note the last date.
For each theme, decide whether it needs a CLAUDE.md rule, a hook, a permission setting, or nothing (one-off). Prefer a hook whenever the violation is detectable from the tool input alone, such as a command string or a file path.

Expect: corrections.md with themes, counts, dates and the proposed mechanism for each.

Audit before moving on: Each theme has at least one cited commit hash or transcript date. Themes seen once in more than a month are marked one-off unless they caused damage.

Step 3 — Draft the new CLAUDE.md

Goal: Write a lean file where every rule earns its place.

Write CLAUDE.md using Boris's structure, adapted to this project:
- Head: project one-liner, stack, and the exact build, test, lint and typecheck commands taken from the project's config and verified in step 1.
- Workflow: plan mode and a written plan for tasks with 3 or more steps or architectural choices.
- Subagents: use them for exploration and parallel independent tasks; they return summaries.
- Verification: never claim done without running the test, lint and typecheck commands; say what was not verified.
- Bugs: reproduce with a failing test that fails for the right reason before fixing.
- Self-improvement: when corrected, propose a rule; delete rules that no longer apply.
- Project rules from corrections.md that chose the 'rule' mechanism, each with a short reason.
Put the most violated rules near the top. Keep it under 200 lines and 3k tokens; measure both. Write a diff against CLAUDE.old.md and list removed rules with the reason for removal.

Expect: CLAUDE.md, a diff, a removed-rules list, line and token counts.

Audit before moving on: Any rule without a reason or incident is removed or justified. If the file exceeds limits, cut conventions the linter already enforces first.

Step 4 — Hooks for absolute rules

Goal: Make the rules that must never break deterministic.

For each theme in corrections.md that chose 'hook' or 'permission', and for standard absolute rules (no secrets in commits, no force push, no push to main, no destructive deletes at repo root), write enforcement in .claude/settings.json: permission deny rules where a pattern suffices, and PreToolUse hooks running a small script that inspects the tool input and exits with a blocking status and a message when it matches.
Keep hook scripts in .claude/hooks/ with tests: feed each script a sample violating and a sample allowed tool input and assert the exit code.
In a live session, deliberately ask Claude to perform each blocked action and confirm the hook blocks it with a clear message.
Remove the matching prose rule from CLAUDE.md or shorten it to a pointer to the hook.

Expect: .claude/settings.json, .claude/hooks/ with tests, a live-block log.

Audit before moving on: Every hook test passes and every live attempt is blocked. A hook that blocks legitimate work in normal use is narrowed before moving on.

Step 5 — Build and run the behavioural eval

Goal: Measure whether the file changes behaviour.

Create eval/tasks/ with at least 12 tasks, each a small, real change in this repo designed to tempt one rule: a bug fix that invites patching without a failing test; a 4-step feature that invites skipping a plan; a change where the wrong package manager command is tempting; a task that ends with an easy chance to claim done without tests.
Write eval/run.sh: for each arm (no CLAUDE.md, CLAUDE.old.md, new CLAUDE.md), for each task, 3 runs, in a fresh git worktree, run claude -p with the task prompt and --output-format json, saving the transcript and the final diff.
Write eval/score.py: per run, check the transcript and repository state for each targeted rule (ran the right test command, wrote a plan before edits, added a failing test before the fix, claimed done only after verification). Output a table of adherence per rule per arm.

Expect: eval/ tasks, runner, scorer, raw results and an adherence table.

Audit before moving on: Hand-check 5 random scored runs against their transcripts; any scorer mistake is fixed and all runs re-scored. If a task is followed 100% even with no file, it is too easy; replace it.

Step 6 — Validate against oracles and write the gap report

Goal: Decide what to keep, what to delete, and what is still unknown.

1. Compare adherence per rule across the three arms. A rule that shows no improvement over no file is a deletion candidate unless it encodes a project fact.
2. Confirm each hook blocks its violation live and passes its tests.
3. Re-measure final line and token counts.
4. Ask a teammate, or yourself over the next week, to log any correction they still have to give; list the plan for that log.
5. Write report.md: adherence table, rules to delete, hooks added, token weight, claims verdicts.
6. Write gaps.md: unverified loading claims, rules not scorable automatically, run-to-run variance, conflicts with the global CLAUDE.md, and anything skipped. Fix what you can now.
7. Add a dated line to the file's history or a lessons file recording this eval's result, so the next rebuild starts from measured adherence instead of memory.

Expect: report.md, gaps.md, final CLAUDE.md committed with its eval results.

Audit before moving on: Re-run the eval for the new file once more and confirm adherence is within the earlier run-to-run range. Confirm no secret or personal data from transcripts was copied into any output.

4 · Gap analysis and audit

Run this after the build. It makes the agent enumerate its own claims, mark what is verified, rank the gaps and fix the top ones.

You are auditing a CLAUDE.md rebuild you did not do. Read claims.md, corrections.md, CLAUDE.old.md, the new CLAUDE.md, .claude/settings.json, .claude/hooks/, eval/ results and report.md.
1. List every claim: loading behaviour, shortcut behaviour, size guidance, adherence improvements, hook coverage, token weight.
2. Mark each verified, unverified or false with evidence: a doc URL, a test output, an eval table row, a live-block log.
3. Re-check: every command in CLAUDE.md runs; every rule has a reason; every absolute rule has a hook or permission rule that was shown to block; the eval ran 3 times per task per arm in fresh worktrees; the scorer was hand-checked; the file is under 200 lines and 3k tokens; no secrets or personal data were copied from transcripts.
4. List missing pieces: rules that cannot be scored, tasks that were too easy, untested interaction with the global file.
5. Rank gaps by how much they weaken the claim that the new file works.
6. Fix the top three now.
7. Report what you could not fix and why.

Questions the agent must ask itself before it says done:

5 · What proves it right

6 · Failure modes

7 · Agent direction (unattended runs)

Start with claude --version and the official docs; several guide claims depend on version. Cache the docs pages you read under notes/docs/ with dates. Spawn a sub-agent to mine transcripts and git history for corrections, with instructions to quote only the gist and never copy secrets, while the main loop drafts the file. Run the eval in separate git worktrees so arms do not contaminate each other, and run tasks in parallel only when they touch different worktrees. Stop and ask before editing the global ~/.claude/CLAUDE.md, before adding hooks that block common commands, and if headless runs cost more than the user expects. Return README.md linking claims.md, corrections.md, CLAUDE.md with its diff, .claude/settings.json, .claude/hooks/, eval/, report.md and gaps.md, each with a one-line status.

Prompt system updated 2026-10-22 · all prompt systems · JSON