# Karpathy Coding Loop > Use before writing, modifying, or refactoring any code, and at each temptation point inside it: starting an implementation, proceeding on an unstated assumption, choosing between two readings of a request, adding an abstraction, config option, or error handler nobody asked for, editing a line or comment the task did not require, or reporting work done. - Skill: `yshms/karpathy-coding-loop` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add yshms/karpathy-coding-loop` - Raw SKILL.md: https://api.skillmd.com/api/skills/yshms/karpathy-coding-loop/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: yshms (https://skillmd.com/u/yshms) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/yshms/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.