Karpathy's CLAUDE.md Grows to 10 Rules: A Self-Check Protocol Cuts Agent Error Rate From 41% to 11%
A ten-rule document attributed to Andrej Karpathy — who joined Anthropic’s pretraining team in May — began circulating on X on June 28, and developers say the six rules it adds change how they think about agentic reliability, not just code quality.
The document is distinct from the four-rule andrej-karpathy-skills template that Forrest Chang distilled from Karpathy’s January observations on LLM coding pitfalls. That repository has accumulated over 200,000 combined stars across two forks, making it one of the fastest-growing files in GitHub history. The new ten-rule version carries a subtitle: “A Short List of Rules, Earned by Watching the Same Mistakes Twice.”
Measured against Claude Code, developers using the ten-rule version report a drop in agent error rate from 41% to 11%.
What the Original Four Rules Did
The January template covered: Think Before Coding (stop making wrong assumptions), Simplicity First (minimum code that solves the problem), Surgical Changes (only touch what the task requires), and Goal-Driven Execution (define success criteria, loop until verified with a test). Those rules address what an agent produces. They do not address how the agent monitors its own reasoning mid-task.
The Six New Rules
The ten-rule document targets what the original did not: how an autonomous loop should catch its own failure patterns before they compound.
Rule 5 — Use the model only for judgment calls. Use Claude for classification, drafting, extraction from unstructured text. Do not use it for routing, retries, status-code handling, or deterministic transforms. If a status code already answers the question, code answers it, not the model.
Rule 6 — Token budgets are not advisory. In a multi-step loop, exceeding a token budget is not a soft warning; it is a signal that the approach is wrong. The rule specifies stopping and restating the plan before continuing.
Rule 7 — Surface conflicts, do not average them. When two competing code patterns exist in a codebase, explicitly pick one (the newer pattern or the one with more test coverage), explain the choice, and mark the other for cleanup. Mixing both patterns is defined as the worst outcome — worse than either choice alone.
Rule 8 — Read before you write. Read the exports file, the direct caller, and shared utilities before touching anything. “Looks orthogonal” is identified as the most dangerous phrase in agentic coding; if the agent is uncertain, it should ask.
Rule 9 — Tests verify intent, not just behavior. A test only counts if it would fail when the underlying business logic changes. A passing test that cannot detect a logic regression provides the agent with false confidence and no real protection.
Rule 10 — Checkpoint after every significant step. After each step in a multi-step task, the agent must summarize what was done, what was verified, and what remains. The rule is explicit: “If you can’t clearly describe the state, don’t continue.”
Why the Distinction Matters
The four-rule template tells an agent how to write code. The ten-rule document tells it how to monitor its own reasoning. Specifically, Rule 6 names four recurring failure modes the agent should recognize in its own behavior and stop: scope creep, false confidence from tests that do not cover intent, silent skipping of steps, and mixing conflicting patterns.
The architectural parallel is Claude Code 2.1.139’s /goal command, shipped in May 2026. It uses a separate, faster verifier model — not the same model that wrote the code — to check whether a completion condition is met after each turn. The CLAUDE.md rules and the /goal command address the same problem from different angles: how to make a loop that runs without human review actually know when it has succeeded or failed.
A 200-line CLAUDE.md file will lose compliance quickly, with important rules buried in noise. The ten-rule version stays under 65 lines. Anthropic’s own documentation notes that CLAUDE.md compliance drops sharply beyond that length.
Practical Use
The document is designed for multi-step agentic workflows, not single-session coding assistance. Rules 10, 7, and 8 specifically target the failure modes that appear when an agent chains tasks across turns — state loss, pattern drift, and writing into code the agent has not yet read. For single-turn code generation, Rules 1 through 4 remain sufficient.
The ten-rule version is available as a GitHub Gist and in community repos; it is not the official Anthropic CLAUDE.md template.