karpathy-principles

> The models make wrong assumptions on your behalf and

> just run along with them without checking. They don't

> manage their confusion, don't seek clarifications,

> don't surface inconsistencies, don't present

> tradeoffs, don't push back when they should.

>

> (Andrej Karpathy, on agentic coding failure modes)

What This Is

A four-principle contract for reducing the most common

LLM coding pitfalls. Compact entry-point. Each

principle has a deeper-dive skill in night-market;

this skill is the index, not the encyclopedia.

Derivation: distilled by Forrest Chang

(forrestchang/andrej-karpathy-skills, MIT) from

Karpathy's observations. Full attribution in

references/source-attribution.md.

When To Use

• Before starting any coding task larger than a typo
• During code review, to name the failure mode you see
• After writing a diff, to self-audit before claiming

done

• When training a junior engineer to read agent diffs

When NOT to Use

These principles bias toward caution over speed. For

cases listed in modules/tradeoff-acknowledgment.md,

use judgment: trivial fixes, exploratory spikes,

documentation-only edits, and time-boxed prototypes.

The Four Principles

1. Think Before Coding

**State assumptions. Surface confusion. Match tone to

evidence.**

• If multiple interpretations of the request exist,

list them. Do not silently pick.

• If a simpler approach exists, name it. Push back

when the simpler path is correct.

• If something is unclear, stop and ask. Hidden

assumptions are the cheapest bug to prevent and the

most expensive to find later.

• Make claims no stronger than the evidence supports.

Calibrated tone beats confident hand-waving.

Deep dives: Skill(imbue:rigorous-reasoning) for the

sycophancy guard, Skill(superpowers:brainstorming)

for option generation, /spec-kit:speckit-clarify

command for ambiguity drilldown.

2. Simplicity First

**Minimum code that solves the problem. Nothing

speculative.**

> They really like to overcomplicate code and APIs,

> bloat abstractions.

>

> (Andrej Karpathy, on the same agentic-coding thread)

• 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 you wrote 200 lines and it could be 50, rewrite

it

Self-check: would a senior engineer say this is

overcomplicated? See modules/senior-engineer-test.md.

Deep dives: Skill(imbue:scope-guard) for the

worthiness formula and branch budgets,

Skill(leyline:additive-bias-defense) for burden of

proof on every addition,

Skill(conserve:code-quality-principles) for the

KISS / YAGNI / SOLID foundation.

Record the Tradeoff (decision journal)

When this step settles a decision with real alternatives, record it to

docs/tradeoffs.md while the reasoning is live (draft and confirm):

• If leyline is installed, invoke Skill(leyline:decision-journal) and append

a tradeoff entry (the decision, the options weighed, and what was

sacrificed; set phase to plan). Show the draft; append on

confirmation.

• Fallback (leyline absent): append to docs/tradeoffs.md using the in-file

ENTRY TEMPLATE; assign the next TR-NNN id.

3. Surgical Changes

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

mess.**

• Do not improve adjacent code, comments, or

formatting

• Do not refactor things that aren't broken
• Match existing style even when you would do it

differently

• If you notice unrelated dead code, mention it; do

not delete it

• When your changes orphan imports or variables,

remove the orphans you created. Pre-existing dead

code stays unless asked.

The trace-back test: every changed line should trace

directly to the user's request.

Deep dives: Skill(imbue:justify) for additive-bias

audits on diffs, Skill(leyline:additive-bias-defense)

for the burden-of-proof contract, the

bounded-discovery.md rule for read-budget caps.

4. Goal-Driven Execution

**Define verifiable success criteria. Loop until

verified.**

Transform vague tasks into checkable goals:

• "Add validation" becomes "tests for invalid inputs

pass"

• "Fix the bug" becomes "test reproducing the bug,

then make it pass"

• "Refactor X" becomes "tests pass before and after"
• "Make it faster" becomes "benchmark Y under N ms"

For multi-step tasks, state a brief plan with

verification per step. Strong success criteria let

you loop independently. Weak criteria require

constant clarification.

See modules/verifiable-goals.md for the full

reformulation template.

Deep dives: Skill(imbue:proof-of-work) for the Iron

Law (no implementation without a failing test first),

Skill(superpowers:test-driven-development) for the

RED-GREEN-REFACTOR loop.

The Karpathy Self-Check

Before you ship, four questions:

| Principle | Question |

|-----------|----------|

| Think Before Coding | Did I list assumptions, or did I guess silently? |

| Simplicity First | Would a senior engineer call this overcomplicated? |

| Surgical Changes | Does every changed line trace to the request? |

| Goal-Driven Execution | Can I prove this is done with a check, not a feeling? |

Four "yes" answers means ship. Anything else means

iterate.

Modules

• modules/anti-patterns.md - eight named drift rails

with before/after diffs

• modules/senior-engineer-test.md - the

three-question self-check battery

• modules/verifiable-goals.md - vague-to-verifiable

reformulation template with worked examples

• modules/tradeoff-acknowledgment.md - when the four

principles do not apply

References

• references/source-attribution.md - Karpathy

primary citation, Forrest Chang derivation, license,

adjacent prior art

Related Skills

• Skill(imbue:scope-guard) - worthiness formula and

branch budgets

• Skill(imbue:proof-of-work) - Iron Law TDD gate
• Skill(imbue:rigorous-reasoning) - sycophancy and

hidden-assumption guard

• Skill(imbue:justify) - additive-bias diff audit
• Skill(leyline:additive-bias-defense) - burden of

proof on every addition

• Skill(conserve:code-quality-principles) - KISS,

YAGNI, SOLID

• Skill(superpowers:test-driven-development) -

RED-GREEN-REFACTOR

• Skill(superpowers:brainstorming) - generate

options before committing

• See docs/quality-gates.md#skill-level-quality-gate-composition

for the full gate-skill federation graph (this skill

is the synthesis hub)

Required TodoWrite Items

When invoked as a pre-flight gate, create:

• karpathy:assumptions-listed - principle 1 satisfied
• karpathy:simplicity-checked - principle 2 satisfied
• karpathy:trace-back-verified - principle 3 satisfied
• karpathy:success-criteria-defined - principle 4

satisfied

Exit Criteria

• Each of the four principles has been answered with a

concrete artifact (assumption list, scope rationale,

diff trace, verification plan).

• The senior-engineer test was applied at least once.
• Verifiable success criteria are written down before

the implementation begins.

• The chosen approach and its simplicity tradeoff are

recorded to docs/tradeoffs.md (or the in-file

template) when real alternatives were weighed.