Karpathy’s Four Coding-Agent Rules Need Production Hardening

Karpathy’s four coding-agent rules work because they compress senior engineering taste into a small prompt surface. Think Before Coding. Simplicity First. Surgical Changes. Goal-Driven Execution. Good defaults. Better than the usual instruction soup.

But a rule set that works in a demo can still fail in production. Production coding agents do not merely write code. They edit tests, change build files, infer conventions, summarize pull requests, ask clarifying questions, and report completion to humans who are trying to decide whether to trust the diff. That is where the original four rules are too soft.

The evidence points in a specific direction. Change size and diffusion predict defect risk.^[1] Review effectiveness drops when a change grows past a few hundred lines.^[2] Google’s own engineering guidance says a 100 line changelist is usually reasonable, while 1000 lines is usually too large.^[3] Those findings support Surgical Changes and Simplicity First. The weaker point is Goal-Driven Execution: tests pass is not a success criterion when the agent can author or weaken the tests. SWE-bench+ found that 31.08% of passing patches in its reviewed sample were suspicious because weak tests let incorrect or incomplete changes pass.^[4]

So I rewrote the four principles as production controls. The rewrite keeps the spirit. It adds what production needs: named anti-patterns, a distinction between prototype and trust-boundary code, an explicit test-gaming firewall, and a fifth rule, Calibrated Communication, because agents fail review when the message and the diff disagree.

The original rules do three useful things. They slow the agent down before editing. They push against speculative abstraction. They discourage drive-by refactors. They tell the agent to verify instead of narrate.

The problem is not direction. The problem is operational underspecification. Think Before Coding does not say when a question is worth the user’s attention. Simplicity First does not separate prototype shortcuts from production boundary checks. Surgical Changes does not define how to surface adjacent defects without silently expanding scope. Goal-Driven Execution does not protect the verification loop from test-gaming.

That matters because LLM coding agents are not failing like junior developers only. They have agent-specific failure modes: confident hallucination about APIs they did not read, sycophantic agreement when challenged, over-editing disguised as helpfulness, weak-test passing, and phantom completion reports. The rule set has to name those shapes. If the anti-pattern has no name, the agent cannot be instructed to avoid it and the reviewer cannot point to it cleanly.

The production rewrite is therefore not a longer motivational poster. It is a small control layer: thresholds, labels, and stop conditions.

The original Think Before Coding rule is right to resist blind implementation. It is wrong if it becomes a permission slip for interrogation.

There are three different uncertainties hiding under the same sentence. spec_uncertainty means the user’s intent is structurally ambiguous. Ask. code_uncertainty means the agent does not know how the codebase works. Read files, tests, and conventions. model_uncertainty means the agent is unsure whether its approach is correct. State the risk and verify.

The threshold is structural. Ask only when two plausible interpretations would change the schema, API contract, file touched, user-visible behavior, or failure mode. If the difference is naming, style, or a reversible detail, state the assumption and proceed.

The hardened rule also kills the menu anti-pattern. Agents love to list three options and make the user adjudicate. That feels collaborative. It is often decision avoidance. Recommend one path. Justify it in one sentence. Ask once only if the choice would be expensive to reverse.

Simplicity First is easiest to abuse when an agent treats every safeguard as speculative. That is not simplicity. That is deleting the contract.

The production calibration is the important addition. In prototype code, the smallest working path is often the right path. In production code, inputs crossing a network, file, process, model, user, or dependency boundary need validation. Not because every impossible state deserves ceremony, but because impossible must mean excluded by the type system or control flow. It cannot mean the model did not expect it.

The abstraction rule should also be sharper. Use duplication until the second or third real use case proves a stable shape. Prefer deep modules: small interfaces with enough implementation behind them to hide complexity. A 200 line function with two inputs can be simpler than a 50 line framework with twelve knobs and one caller.

Surgical Changes has the best empirical backing. Change diffusion matters. Review size matters. File count matters. The agent should feel friction when a one-file task turns into a five-file patch.

The operational handle is declared scope. Before editing, the agent names the files it expects to touch. If it needs another file, that is not forbidden. It is a scope expansion event. The agent states why the file entered scope. This turns invisible drift into a reviewable decision.

The second addition is a structured place for adjacent issues. The original advice, mention it, do not delete it, is directionally correct. It needs a format: Noticed but not changed, with file:line, one sentence, and a suggested follow-up. That resolves the Boy Scout trap. The agent does not use adjacent cleanup to inflate the diff, but it also does not bury a real defect because the prompt said surgical.

Loop until verified sounds disciplined. It becomes dangerous when the loop treats any green check as success.

The evidence is blunt. SWE-bench+ found solution leakage and weak-test passing large enough to collapse reported performance.^[4] A later study of SWE-bench Verified found that 29.6% of plausible patches behaved differently from ground truth under differential patch testing.^[5] Passing tests can be a weak signal. Passing tests the agent wrote can be a tautology.

The hardened rule starts by defining success before coding. A failing test that will pass is ideal. A manual reproduction step can work. A static property can work. What does not work: I will make the tests pass without saying which behavior those tests protect.

It also gives the agent a stopping rule. Three attempts is often enough to tell whether the agent is converging or thrashing. If the verification stack does not pass, stop and report the exact failure. A partial but honest state is safer than a green diff produced by weakening assertions.

The original four rules stop at implementation. Production review does not. A coding agent also has to report what it did. That report is part of the system.

This is where ego-signaling enters. Great question, I carefully reviewed, this should survive production, and production-ready are not evidence. They are verbal confidence markers. Calibration research on code generation finds that generative code models are not well calibrated out of the box.^[8] So the agent’s confidence language is not the thing to trust.

Trust the artifact. Trust the verification. Trust the explicit list of what was not checked. The hardened completion schema is deliberately boring: DONE, VERIFIED, NOT VERIFIED, ASSUMED, NOTICED, NEXT. It creates a stable review surface and makes phantom completion harder.

The rule also protects partial completion. If the agent cannot finish, it should stop and report state. A clean failure report is better than a superficial patch that looks complete until a human spends an hour discovering what was not done.

The fastest win is to drop the five principles into the agent instruction file. That improves the default. It does not enforce anything.

Enforcement starts with two hooks. First, a pre-edit hook that compares Edit and Write targets against the declared scope list. If a file is outside scope, the agent has to record a scope expansion reason before the edit. Second, a test-file hook that detects changes to *_test.*, *.test.*, test_*, or __tests__/* in the same session as production files. That hook does not block all test edits. It forces a declaration: new failing test, contract change, or test-only stale expectation.

The third hook is post-completion. Reject completions that lack DONE, VERIFIED, and NOT VERIFIED. This is not style policing. It is review hygiene. A reviewer should not need to infer whether bun run test ran from a confident paragraph.

The useful version of the Karpathy principles is not more polite. It is more falsifiable.

Think Before Coding becomes a rule about uncertainty type. Simplicity First becomes a rule about boundaries and earned abstractions. Surgical Changes becomes a declared-scope contract. Goal-Driven Execution becomes adversarial verification with a stop rule. Calibrated Communication makes the final report reviewable.

That is the production move: less agent personality, more state. Less confidence, more evidence. Less green-test theater, more independent verification. The prompt should not ask the agent to be a better developer in the abstract. It should make the bad moves expensive and the honest moves easy.