karpathy-principles

Karpathy Coding Principles

Derived from Andrej Karpathy's observations on how LLMs fail at coding. Ported from forrestchang/andrej-karpathy-skills (MIT).

These four principles apply to every coding task — whether you are a captain reviewing a crew's work or a crew member writing code.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

• State assumptions explicitly — if uncertain, ask rather than guess
• Present multiple interpretations when ambiguity exists — don't pick silently
• Push back when warranted — if a simpler approach exists, say so
• Stop when confused — name what's unclear and ask

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked
• No abstractions for single-use code
• No "flexibility" or "configurability" that wasn't requested
• No error handling for impossible scenarios
• If 200 lines could be 50, rewrite

Test: Would a senior engineer call this overcomplicated? If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

• Don't improve adjacent code, comments, or formatting
• Don't refactor things that aren't broken
• Match existing style, even if you'd do it differently
• If you notice unrelated dead code, mention it — don't delete it

When your changes create orphans:

• Remove imports/variables/functions that your changes made unused
• Don't remove pre-existing dead code unless asked

Test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform imperative tasks into verifiable goals:

Instead of...	Transform to...
"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"	"Ensure tests pass before and after"