Karpathy coding loop

Karpathy Coding Loop

Agent code no longer fails on syntax. It fails with "subtle conceptual errors that a slightly sloppy, hasty junior dev might do" (X status/2015883857489522876, 26 Jan 2026, agent-coding notes): wrong assumptions run with silently, bloated abstractions, dead code left behind, comments and code changed as side effects, no pushback when pushback is warranted. Countermeasure: think -> minimal -> surgical -> verified.

Scope. These rules bias caution over speed. For a typo fix or an obvious one-liner, use judgment — not every change needs the full rigor (tradeoff caveat adapted from multica-ai/andrej-karpathy-skills, MIT).

Scaling down changes the FORM of a rule, never whether it applies. On a trivial edit you skip the written plan and the Assumptions: block. You never skip stating a material assumption in one inline line, and you never skip tracing the diff to the request.

"We're behind schedule" or "no questions" converts assumptions from a question into a one-line preamble. It does not delete them.

The Loop

1. Think before coding

• State assumptions BEFORE code, not after. A material choice — a magic number, a scope boundary, a cache-invalidation policy — is an assumption.
• Multiple reasonable interpretations exist -> present them; do not pick silently.
• A simpler approach exists -> say so. The request looks wrong -> push back with the tradeoff.
• Something is unclear -> stop, name what is confusing, ask.
• Cannot ask -> lead the response with an Assumptions: block and make each one trivially reversible.

2. Simplicity first

• Minimum code for the stated problem. No features beyond the ask, no abstraction for single-use code, no configurability nobody requested, no error handling for impossible scenarios.
• Two heuristics: if you write 200 lines and it could be 50, rewrite it; and Karpathy's observation that agents ship a bloated 1000-line construction and cut it to 100 the moment you ask whether there is a simpler way (Jan 2026 agent-coding notes).
• Senior-engineer test: would a senior engineer call this overcomplicated? If yes, simplify.
• After it works, run one explicit simplify pass: cut abstractions, delete only the dead code YOUR change orphaned.
• The bloated versions are not wrong patterns. They are premature ones.

3. Surgical changes

• Every changed line traces to the request. No drive-by refactors, no improving adjacent code, no altering comments or code you do not fully understand.
• Match existing style even where you would do it differently — including quote style and whether the file uses type hints. Adding type hints to an untyped file while fixing a bug is a side-effect edit.
• Notice unrelated dead code -> mention it, do not delete it.
• Remove imports, variables and functions YOUR change orphaned. Do not remove pre-existing dead code unless asked.
• Keep the diff small enough for a human to audit in one sitting. Karpathy's framing: keep the AI on a leash, work in small incremental chunks (YC AI Startup School / Software 3.0, announced in X status/1935518272667217925, 19 Jun 2025; transcript write-up at latent.space/p/s3).

4. Goal-driven verification

• Define the machine-checkable criterion BEFORE coding. Transform the task:
  • "add validation" -> write tests for invalid inputs, then make them pass
  • "fix the bug" -> write a test that reproduces it, then make it pass
  • "refactor X" -> tests pass before and after
• Multi-step work states a plan first, one verify per step:

1. [Step] -> verify: [check]
2. [Step] -> verify: [check]
3. [Step] -> verify: [check]

• Loop generate -> verify until the check passes. Never claim done without running it.
• Strong criteria let you loop independently; "make it work" forces constant clarification.
• Aim tenacity at the criterion, not at expanding scope.

Before an external API

Do not write against a library or API from recollection. Get its current official docs into context first -> karpathy-context-engineering.

Red flags — STOP

• About to turn an unstated material assumption into code.
• Thinking "I'll note my questions at the end."
• Adding a class, config value, or option "for flexibility."
• Editing a comment or line the task did not require.
• Changing quote style or adding type hints while doing something else.
• Reporting done without having run anything.

Excuse -> Reality

Excuse	Reality
"Team said no questions"	Then state assumptions inline before the code.
"It's a reasonable default"	Unstated != reasonable. One line to state it.
"More robust this way"	Robustness nobody asked for is bloat — the first-listed complaint in the Jan 2026 notes.
"I cleaned it up while there"	Side-effect edits are the second. Revert them.
"I added type hints while I was there"	Style drift is a side-effect edit. Revert.
"The strategy pattern is best practice"	Best practice at the wrong time is bloat. One function until a second case exists.
"My plan step is review and improve"	That is not a criterion. Name the check that will run.
"I'll write the test after"	Then the test encodes the code, not the bug.

Worked examples

Before adding any abstraction, config flag, or class, and before touching a line outside the requested change, open references/examples.md and find the matching BAD/GOOD pair.

Sections map to the four rules: 1 hidden assumptions and multiple interpretations, 2 over-abstraction and speculative features, 3 drive-by refactoring and style drift, 4 vague-vs-verifiable, multi-step verification, and test-first.

Working if

Diffs contain only requested changes; no rewrites caused by overcomplication; clarifying questions arrive before implementation rather than after mistakes.

Sources

X status/2015883857489522876 (26 Jan 2026, agent-coding notes) — the failure-mode list and the 1000-lines-to-100 observation. YC AI Startup School "Software 3.0" talk, announced in X status/1935518272667217925 (19 Jun 2025, talk announcement), annotated transcript at latent.space/p/s3 — the leash and small-incremental-chunks framing. nanochat release thread (HN, Oct 2025) — Karpathy reported coding agents were "net unhelpful" on that repo, possibly because it sits too far off the training distribution.

Rules 1-4, the plan template, the transform table, the tradeoff caveat, the working-if signal, and all of references/examples.md adapt multica-ai/andrej-karpathy-skills (formerly forrestchang/andrej-karpathy-skills), MIT per its README.md and .claude-plugin/plugin.json. Full notice at the head of references/examples.md. That README states the rationale for rule 4 in two fragments it attributes to Karpathy — "LLMs are exceptionally good at looping until they meet specific goals" and "Don't tell it what to do, give it success criteria and watch it go" (README.md, "Key Insight" section) — but pins them to no primary artifact, so treat the attribution as the repo's, not as a verified Karpathy citation.