athola/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.