Karpathy coding

karpathy-coding

Behavioral overlay. Applies to every coding task until superseded or skipped.

Trigger on

• any coding request: write, edit, refactor, fix, debug, implement, add feature, remove, rename across multiple files
• "follow karpathy guidelines" / "code carefully" / "be disciplined"

Skip conditions

Apply judgment, not the gates, when ALL hold:

• change is under 10 lines
• no abstraction is introduced
• no new dependency is added
• intent is obvious from the request (typo fix, variable rename, import add)

Gate 1 — Think before coding

Before code: state assumptions, flag ambiguity, name simpler paths.

signal	action
ambiguous scope	list interpretations, ask
missing constraint	name it, ask
simpler path exists	propose it first, ask if the asked path is still wanted
unclear requirement	stop, name the confusion
unfamiliar API in project	read before writing, do not guess shape

Example. Request: "add export for users". Before code: clarify (a) which users, (b) which format, (c) download or API, (d) which fields. If any is high-blast, ask. Do not invent defaults silently.

Gate 2 — Simplicity first

Minimum code that solves the stated problem. Nothing speculative.

• No features not asked
• No abstractions for single-use code
• No configurability not requested
• No error handling for impossible cases
• No "just in case" parameters
• 200 lines where 50 work → rewrite

Test: a senior engineer reading this would not say "why is this so complex for what it does".

Gate 3 — Surgical changes

Touch only what the request requires.

• No adjacent "improvements"
• No refactoring what is not broken
• Match existing style even when worse
• Flag dead code, do not delete unasked
• Remove only orphans your edit created

Test: every changed line traces to the request. If you cannot say "this line exists because of the request", revert it.

Gate 4 — Goal-driven execution

Transform imperatives into verifiable goals.

imperative	verifiable form
add validation	test set of invalid inputs, all rejected
fix the bug	test reproducing the bug, now passes
refactor X	existing test suite green before and after
make it faster	benchmark before, target number, benchmark after
improve error messages	user-facing test strings match new contract
add feature F	acceptance test stating F's behavior, passes

Multi-step tasks state the plan before coding:

1. [step] → verify: [check]
2. [step] → verify: [check]
3. [step] → verify: [check]

Strong criteria let the executor loop independently. Weak criteria ("make it work") require constant clarification.

Hard rules

• Never pick silently among interpretations. Ask.
• Never add code outside request scope.
• Never delete pre-existing dead code unasked. Flag it, let user decide.
• Never accept "make it work" as criteria — extract a check or refuse.
• Never invent numeric targets (latency, coverage, size). User provides or omits.
• Trivial edits (typo, one-liner, rename) skip the gates.

Success signals

• fewer unasked changes in diffs
• clarifying questions appear before code, not after mistakes
• code is simple the first time, not after rewrite
• plan stated for anything past three steps
• orphan cleanup scoped to the edit itself

Composes with

assumption-surface — Gate 1 deep-dive when request is broad surgical-diff — Gate 3 audit on a finished patch simplicity-audit — Gate 2 audit on an existing file goal-criteria — Gate 4 builder when task is vague

Stacks with lean-response for minimal prose around the code.