On April 13, abmedia reported that Forrest Chang compiled Karpathy’s January complaints about “Claude writing code” into “4 CLAUDE.md rules,” which had accumulated 15,000 stars on GitHub at the time; by May 12, the repo’s star count had surpassed 126,000—an 8x increase in less than 1 month. The community soon produced many “expanded versions.” Among them, a post published on May 9 by engineer Mnilax (@Mnimiy), titled “Add 8 more on top of the 4 basics, making it a full 12-rule version,” received 5,968 likes and is one of the most-discussed single posts in the recent Claude Code community.
A recap of the 4 rules: Forrest Chang turns Karpathy’s complaints into an executable template
Forrest Chang’s original 4 rules (each one corresponds to a failure mode Karpathy called out on X in January):
Think Before Coding (think first, then write): don’t make implicit assumptions—spell out what you assume; lay trade-offs out and discuss them; if you’re unsure, ask directly—don’t guess; if there’s a simpler way, oppose a complex approach
Simplicity First: write the smallest amount of code that solves the problem; don’t write speculative features or build abstractions for one-off code; senior engineers will say overly complex design must be simplified
Surgical Changes: only change what needs to be changed—don’t “improve adjacent code,” comments, or formatting on the side; don’t refactor things that aren’t broken; follow the existing style
Goal-Driven Execution: define what “success” means, and iterate until it’s verified; don’t tell Claude the steps—tell it what success looks like so it loops on its own
Anthropic’s official documentation is actually very explicit: CLAUDE.md is an “advisory” file, and Claude will follow it with roughly an 80% chance. After more than 200 lines, compliance drops sharply because important rules get drowned out by noise. Forrest Chang’s approach compresses the rules down to 65 lines, 4 rules, achieving a “floor” (the minimum threshold).
The 8 rules added by Mnilax: fill in new failure modes from the agent era in May 2026
Mnilax argues: Karpathy’s January complaints focused on the scenario of “Claude writing code,” but by May the Claude Code ecosystem has evolved into new collaboration settings involving multiple agents, hook chaining, conflicts in skill loading, multi-step workflows that span sessions—so additional rules are needed. The following are the 8 he added (organized in the original order):
Rule 5: only use Claude for tasks that require judgment (classification, drafting, summarization, extraction), while deterministic decisions (retry 503, routing, status code handling, deterministic transformations) should be handled by normal code
Rule 6: the token budget is not a suggestion—single-task limit is 4,000 tokens, single-session limit is 30,000 tokens; when you’re approaching the budget, proactively summarize and restart—don’t silently exceed it
Rule 7: two conflicting code patterns must “explicitly pick one” (the newer one, or the one with more tests), explain why you picked it, and mark the other for cleanup; mixing the two patterns is the worst choice
Rule 8: read first to understand before writing code—read the exports file, the direct caller, and shared utilities; “looks orthogonal” is the most dangerous wording—if you’re not sure, ask
Rule 9: tests must validate “intent,” not just “behavior”—a test only counts if you can write one that would fail when the business logic changes; otherwise you’re only giving Claude confidence, with no real protection
Rule 10: multi-step tasks need checkpoints—after each step, summarize “what you did, what you verified, and what remains”; if you can’t clearly describe the state, don’t continue
Rule 11: follow existing codebase conventions, even if you disagree—snake_case stays snake_case; class components stay class component; if you don’t agree, treat it as a separate discussion, don’t fork unilaterally
Rule 12: failures must be loud—“migration completed” is wrong if you skipped 30 items, and “tests passed” is wrong if you skipped any one; default to “actively reveal uncertainty,” not “hide uncertainty”
Mnilax claims that across 30 codebases, testing these 12 rules within 6 weeks reduced the error rate from 41% to 3%, with compliance decreasing only slightly (78% → 76%). This media’s observation: these numbers are the author’s self-reported test results, not independently verified; however, the 8 added rules themselves are solid, and the content aligns with pain points that match today’s Claude Code multi-agent usage scenarios (e.g., Agent View multi-session management, the Multi-Agent Layer in a six-layer architecture).
Applicable scenarios and practical recommendations
Mnilax also plainly points out which approaches you shouldn’t try:
More than 14 rules: compliance drops to 52% (down sharply from 76%), and 200 lines is effectively the hard cap
Use examples instead of rules: the token cost of 3 examples equals 10 rules; Claude is likely to overfit to a single example
Abstract instructions like “Be careful / think hard / really focus”: low verifiability, compliance only 30%
Call Claude “a senior engineer”: identity prompts don’t work for behavior changes; only rule-based instructions are effective
Rely on specific tools: “always use eslint” will fail silently when eslint isn’t installed; use neutral wording like “follow the codebase’s existing style” instead, which is tool-agnostic
This media’s recommended practical approach: CLAUDE.md is a “behavior contract,” not a wish list—each rule must answer which specific concrete mistake it prevents. If your work doesn’t involve multi-step pipelines, Rule 10 (checkpoint) is irrelevant; if the codebase already has lint enforcing a single style, Rule 11 (follow conventions) is redundant. After reading the 12 rules, keep the version that maps to the pitfalls you’ve actually encountered, and delete the rest.
Events to watch next include: whether Anthropic will standardize CLAUDE.md rules (currently only “advisory”); whether Forrest Chang’s repo will enter an official recommended template; whether the community will produce tailored versions for specific domains (frontend/backend/data engineering); and whether compliance changes after updates to the Claude model version.
This article “Karpathy CLAUDE.md smashes 126K stars: Community version compiles advanced 12-rule rules” first appeared on ABMedia Chain News.
