What_Karpathy_Actually_Said

In December 2025, Andrej Karpathy posted a thread on X about running AI agents for around 80% of his coding. What got extracted and circulated was a set of failure modes he had observed - patterns that kept breaking the loop between human intent and agent output. Karpathy's original language was diagnostic, not prescriptive: he was describing what kept going wrong, not publishing a framework.

The CLAUDE.md that most people have read - the one sitting at over 100,000 stars under github.com/forrestchang/andrej-karpathy-skills - is Forrest Chang's work. Chang took Karpathy's field observations and formalised them into a config file that another developer could actually hand to an agent. The attribution matters because the two contributions are different in kind. Karpathy identified the failure modes. Chang gave them a shape that could be operationalised. The rules are Chang's distillation; the diagnosis underneath them is Karpathy's.

The four rules Chang extracted:

Think Before Coding - State your assumptions explicitly before writing anything. If you're uncertain about the requirement, ask. If multiple interpretations of the task exist, present them rather than picking one and proceeding.

Simplicity First - No features beyond what was asked. No abstractions written for single-use code. If 200 lines could be 50 without loss, rewrite it. The right amount of code is the minimum that satisfies the requirement.

Surgical Changes - Don't touch code you weren't asked to touch. Don't "improve" adjacent things. Don't refactor what isn't broken. Match the existing style - the change should be invisible except for the thing that needed changing.

Goal-Driven Execution - Make tasks verifiable, not just executable. "Fix the bug" is not a task - "reproduce the bug in a test, then fix it so the test passes" is. The difference is that one produces a verifiable outcome and the other produces code that might be right.

These rules are responses to three specific failure modes Karpathy had named: silent assumptions (the agent interprets ambiguity rather than surfacing it), overengineering (the agent adds complexity the developer didn't ask for), and collateral edits (the agent improves things it wasn't asked to touch). The rules were written to block those three behaviours - which is exactly the right way to write rules.

Where_the_Language_Overlaps

Before mapping the differences, it is worth sitting with the convergence. Two independent practitioners - Karpathy observing failure modes in solo development, and me building governance for a 12-agent team - arrived at nearly identical language for two of the four rules. The exact phrasing, from both sources:

On scope creep:

Chang's CLAUDE.md: "Simplicity first - no features beyond what was asked."

My global CLAUDE.md: "Don't add features, refactor code, or make 'improvements' beyond what was asked."

On collateral edits:

Chang's CLAUDE.md: "Surgical changes - don't improve adjacent code."

My global CLAUDE.md: "Don't 'improve' adjacent code. Don't refactor things that aren't broken."

The quotation marks around "improve" appear in both. This is not cosmetic. The quotes are doing the same work in both documents - marking the word as an agent rationalisation, not a neutral description. Agents don't label their collateral edits as overreach; they label them as improvements. Both systems identified that framing and pushed back on it with the same punctuation.

This is not a coincidence and it is not imitation - the two systems were developed independently. It is evidence that these failure modes are structural attractors. They appear wherever an AI coding agent is given latitude. The agent does not need a specific permission to scope-creep; it needs a specific prohibition not to. Two practitioners at completely different scales identified that, ran the same experiment, and wrote the same corrective. That convergence is the most interesting finding in the comparison - more interesting than any of the divergences that follow.

Where_My_System_Goes_Further_-_And_Why

For two of Karpathy's four rules, my system has a direct equivalent. The equivalent is not a more rigorous version of the same rule - it is the same instinct expressed through a different mechanism, because the multi-agent context created a problem the solo-developer rule was never designed to solve.

Think Before Coding → Spec-Before-Code + plan confirmation

Karpathy's rule asks the agent to surface ambiguity before interpreting it away. In a solo-developer setup, that plays out as a clarifying question in the same session - the developer answers, the agent proceeds, the context window holds the whole exchange.

My equivalent: any change touching more than two files requires a written brief before implementation begins. Agents check for an existing brief before starting multi-file work. If none exists, they create one and surface it for Owner approval before touching code. The brief is lightweight - task description, affected modules, delegate, acceptance criteria - but it is a record, not a conversation.

The distinction matters because a verbal clarification in one session is not visible to the agent running in the next. When 12 agents are running across 6 repos, context that lives only inside a session window is context that effectively does not exist. The brief is the mechanism that makes "state your assumptions explicitly" legible across sessions. The instinct is the same. The persistence requirement is not.

Goal-Driven Execution → PR Comprehension Gate + post-merge verification

Karpathy's rule transforms "fix the bug" into "reproduce it in a test, then fix it so the test passes." The goal is verifiable task framing - you know the task is done when the test passes.

My equivalent runs the same logic across the full merge cycle. Every agent must answer three questions before merging: What does this change do in one sentence? What fails silently? What is the blast radius? For large projects - those with external calls, multiple consumers, or significant coordination surface - there are four additional questions covering dependency justification, cache strategy, separation of concerns, and failure modes for external calls. After merge, the gate answers are checked against the brief's acceptance criteria.

The extension is not pedantry. "Reproduce the bug in a test" produces a verifiable task. The PR Comprehension Gate produces a verifiable handoff - something another agent can read weeks later and understand what was decided and why. When the agent that wrote a module is not the one debugging it six weeks later, the gate answers are the artefact that makes the handoff legible. As documented in The Dark Factory Is Already Running, this specification layer is what makes lights-off operation safe.

The coordination problem the solo-developer ruleset doesn't need to solve

Karpathy's rules assume one agent, one developer, one context window. Under those conditions, the four rules are complete for the failure modes that exist. There is no coordination problem - there is one conversation, one person with full context, one scope of responsibility.

When three agents touch the same module in three separate sessions, the failure mode is different. Contradictory decisions get made without either agent knowing the other made a decision. Assumptions that were surfaced in session one are invisible in session three. The Spec-Before-Code rule and the Comprehension Gate are not more formalised versions of Karpathy's rules. They are responses to a coordination failure mode that doesn't exist at the solo-developer scale and therefore doesn't need addressing there.

The_Layer_Karpathy_Doesn't_Have

Chang's CLAUDE.md is a single file. My system is a four-layer stack:

Global CLAUDE.md - Methodology, agent coordination protocols, security baselines, module manifest standards. The rules that apply everywhere, regardless of project or agent role.

Project CLAUDE.md - Per-repo conventions, architecture decisions, active constraints, stack-specific rules. What this repo does differently from the global defaults.

Scoped rules - File-type-specific and conditional rules that activate in context. Rules that apply only to TypeScript files, or only when modifying a specific module, or only on merge-to-main.

Agent memory - Cross-session persistence per agent and per project. Structured entries that capture corrections with their rationale, so the same guidance doesn't need to be issued twice. The memory system has its own hygiene rules: an index capped at 30 entries, pointers over content, archived entries for anything that no longer applies.

Each layer answers a different question. Each can change independently. A project CLAUDE.md update doesn't require touching the global rules. A scoped rule for the Labs frontend doesn't affect how the GEOAudit backend agents behave. The layering gives the system a separation of concerns that a single file cannot have.

This is not a criticism of Chang's approach for a solo developer. For a single agent answering to a single developer, a single file is the right structure. It is visible, portable, and requires no coordination. Adding layers to that system would be overengineering - the layers solve problems the solo-developer setup doesn't have.

What a single file cannot do is hold context across 12 agents in 6 repos across 10 projects without becoming unmanageable. It cannot distinguish between a rule that applies to all projects and a rule that applies only to a specific module. It cannot capture why a rule was added, only that it exists. And it cannot persist corrections that agents learn across sessions - corrections that would otherwise need to be issued again in every new conversation.

The coordination failure that single-file governance leaves open is the one that compounds: two agents make contradictory decisions about the same module in separate sessions, neither visible to the other. My system handles this through cross-project awareness artefacts - a decisions.md that logs cross-project decisions for human review, a project-inventory.md that tracks status across all active work - and through agent memory with structured rationale. Karpathy's system has no equivalent because the problem doesn't arise at the scale the system was built for.

One addition worth naming directly. After working through this comparison, I added a standalone "no silent assumptions" rule to my global CLAUDE.md: "No silent assumptions. If a task has multiple valid interpretations, surface them - don't pick one and proceed. Flag ambiguity to the Owner or orchestrator before implementing. A wrong guess costs more than a clarifying question." The instinct behind that rule had always been implicit in the Spec-Before-Code requirement - a brief forces assumptions into writing before implementation begins. But the explicit principle wasn't stated as a standalone. Karpathy named something that was already operative in the system, and gave it cleaner, more direct language. The system absorbed it in a day. That is what a well-structured governance system does: it can take a named principle from outside and place it without restructuring what already exists.

The_Rule_Karpathy_Got_Most_Right

The most transferable insight in the Karpathy thread is not one of the four rules. It is the meta-rule that generates rules. Chang's distillation puts it plainly: "Whenever you need to manually modify AI-generated code, don't just make the change. Record why. Extract it into a general rule. Update it in CLAUDE.md."

This is the highest-leverage observation in the whole conversation about AI coding governance. A correction that lives only in the session that produced it is correction that disappears. A rule extracted from that correction is correction that persists. The conversion rate between the two - how reliably a manual intervention becomes a durable rule - is where governance quality is actually measured.

My feedback memory type is exactly this operationalised. Every structured entry leads with the rule itself, followed by a Why: line (the reason the correction was needed - often a specific incident or a strong preference that surfaced in review) and a How to apply: line (when and where the guidance should activate). The structure exists because the same correction kept needing to be made across separate sessions. An agent that receives a correction in session three and doesn't record it will need the same correction in session seven. An agent that records it - with the reasoning attached - will not.

The mechanism differs from Karpathy's version. In the solo-developer setup, the rule gets written into a single CLAUDE.md file - the developer updates it themselves, in the session where the correction happened, and the next conversation with the agent inherits it. In a 12-agent system, the memory is per-agent and per-project, structured as individual files indexed for fast retrieval, with hygiene rules to prevent accumulation without pruning. The file exists not because the developer updates it manually but because the agent is expected to update it when it recognises a new correction.

The principle is identical. Extract corrections into rules. Give rules a rationale, not just a statement. Systems that do this compound in quality over time. Systems that absorb corrections without recording them repeat the same errors - at any scale.

What_Every_Builder_Should_Take_Away

The practitioner somewhere between a solo developer and a full multi-agent team has a specific question that neither end of this comparison answers cleanly: how much governance is the right amount for where I am right now? Three observations are worth carrying forward.

Start with Karpathy's rules. They address real failure modes with accurate language. If you are running one agent and one developer, the four rules - stated explicitly, in your CLAUDE.md, in Chang's language or your own - are sufficient for the failure modes you will encounter. Scope creep, silent assumptions, collateral edits, vague task framing: these are the things that will break your loop, and the four rules directly address them. Add layers only when the problems those layers solve are actually occurring. Governance built in anticipation of scale you haven't reached yet is the same mistake as code that abstracts for use cases that don't exist.

Watch for the coordination failure signal. The moment to add the next layer is specific. When two separate sessions produce contradictory decisions about the same module - when an agent cannot find the context it needs because that context only existed in a previous conversation - that is the coordination failure signal. It will not announce itself as a governance problem. It will look like a wrong decision, or a duplicated effort, or a bug that should have been caught earlier. When you trace it back and find that the root cause is that two agents didn't have access to each other's context, you have found the problem that the next governance layer solves. Not before.

Extract every correction. This is Karpathy's rule and it holds at every scale - one agent, twelve agents, one project, ten. A correction that stays in conversation is governance that ends when the session ends. Write it down with the reason attached. The Why: matters more than most practitioners initially expect - without it, the rule is a constraint with no context, and the agent applying it cannot judge edge cases. With it, the rule is transferable: another agent, another project, another session can apply it correctly without access to the conversation that produced it. The system that benefits from the correction is not the one running now. It is the next one.