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
model_hint	standard
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 .