AI Guides › Playbooks

The Repeat-Mistake Ledger for Your CLAUDE.md

By Nigel Guy · 6 min read

Most people meet CLAUDE.md in one of two ways. They run a command, accept a long auto-generated file and never read it again. Or they write a page of everything they know about the project, in case it helps. Both feel diligent. Both bury the three lines Claude Code actually needed under forty it could have worked out for itself.

Each Claude Code session starts with a fresh context window, so it remembers nothing about your project unless something is loaded for it. CLAUDE.md is that something. The question is not "what could I tell it?" but "what has it already got wrong?"

What a CLAUDE.md file is

It is a plain markdown file that Claude Code reads at the start of every session. You write build commands, conventions and "always do X" rules in it. Per Anthropic's memory documentation, Claude treats it as context, not enforced configuration. That distinction matters later.

It can live in several places, and they stack rather than override each other:

Claude Code loads files from your working directory and every directory above it, concatenated from the filesystem root downwards, so the file nearest you is read last. CLAUDE.md files in subdirectories load on demand, when Claude reads files there.

Before you start

• Claude Code installed and a project you actually work in.
• Cost: nothing extra for the file itself. Claude Code is included in paid Claude plans; Pro is $20 a month (about £16 at time of writing) and Max starts from $100 (about £80 at time of writing). Check the £ price at checkout.
• Ten minutes, and a memory of the last three times Claude Code annoyed you.

The mechanism: the Repeat-Mistake Ledger

Do not start from a blank page and do not start from a template. Start with a ledger, then let it become the file.

Step 1: Generate a starter, then treat it as a draft

Run /init inside your project. Claude analyses the codebase and writes a CLAUDE.md with build commands, test instructions and conventions it finds. If one exists already, /init suggests improvements rather than overwriting it. Setting the environment variable CLAUDE_CODE_NEW_INIT to 1 first gives an interactive flow that asks which files to set up (CLAUDE.md files, skills, hooks) and shows a proposal before writing anything. It also reads instruction files from other tools, such as Cursor rules and Copilot instructions, and folds in the relevant parts.

Step 2: Run the keep-or-cut test on every line

Anthropic's best-practice guidance gives the test: for each line ask "would removing this cause Claude to make mistakes?" If not, cut it.

Step 3: Open the ledger

Make a short list headed "Mistakes it has made twice". Add to CLAUDE.md when Claude repeats a mistake, when code review catches something it should have known, or when you type the same correction you typed last session. Each entry becomes one instruction.

Step 4: Make every entry checkable

The documentation's own examples are the pattern: "Use 2-space indentation" instead of "Format code properly"; "Run npm test before committing" instead of "Test your changes"; "API handlers live in src/api/handlers/" instead of "Keep files organized". If you cannot tell whether Claude obeyed a line, rewrite it.

Step 5: Prune on a schedule

Aim for under 200 lines per file. Longer files use more context and lower adherence. If Claude ignores a rule you wrote, the file is probably too long, not the rule too weak. Run /doctor prompt-audit (needs Claude Code v2.1.283 or later) and it reports outdated or conflicting instructions and proposes edits without changing anything until you say so.

A prompt to build your first ledger

Paste this into a Claude Code session after /init. Fill in the bracketed parts.

You are helping me tighten the CLAUDE.md for my project, [PROJECT_NAME].

Context: the project uses [LANGUAGES_AND_FRAMEWORKS]. Mistakes you or other
assistants have made here more than once: [MISTAKE_LIST].

Goal: a CLAUDE.md of no more than [MAX_LINES] lines in which every line
would prevent a real mistake.

Steps:
1. Read the current CLAUDE.md and the project's build and test configuration.
2. For each existing line, decide keep or cut. Cut anything you could infer
   from reading the code, anything generic, and anything likely to go stale.
3. For each mistake in my list, draft one concrete, checkable instruction.
4. Flag any pair of lines that contradict each other.

Output: first a table of cuts with a one-line reason each, then the proposed
file in full, grouped under short markdown headings.

Rules: do not invent commands, paths or conventions. If you cannot verify one
from the repository, ask me instead of guessing. Do not write anything to disk
until I approve.

Before answering, check that every line in your proposed file names a command,
path or specific behaviour, and that the file is within the line limit.

Worked example (hypothetical)

Imagine a small invoicing app. Claude Code keeps running the whole test suite (slow), edits files in dist/, and uses npm when the project uses pnpm. The ledger yields three lines:

• Use pnpm, not npm.
• Run one test file with pnpm test path/to/file, not the whole suite, until the end of a task.
• Never edit dist/; it is generated by pnpm build.

Three lines. The generated file's 60 lines of folder descriptions can go, because Claude can read the folders itself.

Where things go instead

• Personal preferences for one project: CLAUDE.local.md, gitignored.
• A long file: split into .claude/rules/ files. Rules with paths frontmatter load only when Claude touches matching files. Imports with @path/to/file help organisation but do not save context, because imported files load at launch too.
• Multi-step procedures or knowledge needed only sometimes: a skill.
• Maintainer notes: block-level HTML comments are stripped before injection, so they cost no context.
• Already using AGENTS.md: recent versions can read it directly. Otherwise put @AGENTS.md at the top of a CLAUDE.md. On Windows, prefer the import to a symlink.

Check it worked

Run /context and look under Memory files for your file. Then give Claude a task that used to trigger a ledger mistake. If it still errs, the line is vague, buried or contradicted elsewhere. Instructions given only in chat vanish; project-root CLAUDE.md is re-read after /compact.

What to skip

• Pasting the whole README or API docs in. Link to them.
• Describing every file and folder.
• Shouting. If Claude skips one line, add emphasis such as "IMPORTANT" to that line alone; emphasise many and none stands out.
• Rules like "write clean code", which change nothing.
• Hoarding. Entries for mistakes it no longer makes are dead weight.

Guardrails

• CLAUDE.md is advice, not enforcement. If something must never happen, such as writing to a migrations folder, use a hook or permission rule. Anthropic's docs point to a PreToolUse hook for blocking actions.
• Never put secrets, tokens or passwords in a file you commit.
• Contradictory instructions across user, project and nested files can make Claude pick one arbitrarily. Review them together.
• Menu names, commands and version requirements change quickly. Check the current Claude Code docs.
• Auto memory (notes Claude writes itself, per repository) is separate. Open /memory to see both and toggle auto memory.

Sources

• Claude Code: How Claude remembers your project
• Claude Code: Best practices
• Claude pricing

All 751 AI guides · JulieMango plans from £17/mo