In January 2026, AI luminary Andrej Karpathy posted a thread on X criticizing Claude's coding style: silent assumptions, overcomplication, and collateral damage to unrelated code. Forrest Chang turned these pain points into 4 behavioral rules in a CLAUDE.md file, which went viral and accumulated 120,000 stars. But by May 2026, the Claude Code ecosystem had shifted from single-shot completions to multi-step agent pipelines, rendering the original template insufficient. A developer spent six weeks testing 30 codebases, uncovering four critical blind spots in the original rules, and added 8 new ones—cutting the error rate from 41% to 3%.
Karpathy's Original 4 Rules
Rule 1: Think before coding. State assumptions and expose trade-offs instead of guessing silently. Rule 2: Prefer simplicity. Write the minimum code needed; don't add imaginary features. Rule 3: Surgical changes. Modify only what must change; don't touch adjacent code unless required. Rule 4: Goal-oriented execution. Define success criteria first, then iterate until validated. These four rules addressed roughly 40% of failure modes in unsupervised Claude Code sessions.
New Frontier: Agent Conflicts, Hook Chains, Cross-Session Breakdowns
Scenarios the original rules never handled soon emerged: Claude started deciding deterministic logic (e.g., whether to retry an API call), leading to inconsistent weekly behavior; unbounded sessions ballooned into 50K-token context dumps; when two conflicting patterns existed in the same repo, Claude produced mediocre hybrid code; during multi-step tasks, one wrong step caused the model to continue on corrupted state. The developer added 8 rules to cover: offloading non-AI decisions to deterministic code, setting a 4K-token budget per task, choosing one pattern when contradictions exist, and reading exported content of a file before modifying it.
Rules 5–8: Budget, Unification, True Tests
The new rules patch blind spots that cost real time. For instance: before adding code in a file, read its exports, immediate callers, and any obviously related shared utilities to avoid duplicate functions; tests must encode why a behavior matters, not just verify a constant return; after each step in a multi-step task, summarize what's been done and what remains. Results after adding 8 rules: error rate dropped to 3% (down from 41%), while compliance rate only slipped from 78% to 76%, proving the new rules don't compete for the same attention budget.
Four Weaknesses of Original Template
First, long-running agent tasks: no budget or checkpoint rules allowed pipelines to drift. Second, multi-repo consistency: the original rule expects one style, but in a monorepo with 12 services, Claude either picks randomly or averages styles. Third, test quality: treating tests as success criteria lets Claude write tests that always pass but verify nothing. Fourth, production vs. prototyping: the simplicity rule can over-trigger in early exploration. The added rules are targeted patches, not replacements.
The developer warns: CLAUDE.md must stay under 200 lines; beyond that, compliance plummets. The full 12-rule template can be copied directly: start with Karpathy's 4 base rules, then append rules 5–12. Each rule should answer one question: What error does it prevent? A tailored 6-rule file beats a generic 12-rule one where half are never used.