/karpathy-principles

name: karpathy-principles
description: Pre-implementation gate covering think-first, simplicity, surgical edits, and verifiable goals. Use when starting implementation to verify the approach.
alwaysApply: false
category: discipline
tags:
- karpathy
- coding-pitfalls
- synthesis
- entry-point
- discipline
- anti-overengineering
- TDD
dependencies:
- imbue:scope-guard
- imbue:proof-of-work
- imbue:rigorous-reasoning
- leyline:additive-bias-defense
- conserve:code-quality-principles
tools: []
usage_patterns:
- pre-implementation-gate
- code-review
- diff-hygiene
- task-reformulation
complexity: foundational
estimated_tokens: 900
modules:
- modules/anti-patterns.md
- modules/senior-engineer-test.md
- modules/verifiable-goals.md
- modules/tradeoff-acknowledgment.md
references:
- references/source-attribution.md
role: entrypoint

> 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

• Match the module's existing model of the concern

as well as its style. During a migration, use the target model and never copy the superseded one, even when it is the majority. See `Skill(conserve:elegant-code)` rung 2

• 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 ass