Karpathy Guidelines (v2)

Triggers automatically when relevant; invoke directly with /karpathy-guidelines or ask, e.g. "review this code against the guidelines".

Behavioral guidelines against common LLM coding failure modes, derived from Andrej Karpathy's observations.

Rules are stated at judgment level with a reason attached — current models generalize from the explanation better than from enumerated prohibitions. The appendix keeps the prescriptive form for weak-model delegation.

1. Think before coding

Name your assumptions and open questions before implementing. Where several readings of the request exist, present them and recommend one; where a simpler approach would serve better, say so — silent compliance hides better options. Ask the user only when a genuine decision is theirs to make; otherwise state your interpretation and proceed.

Why: hidden assumptions are where wrong implementations start, and surfacing one costs a sentence.

2. Simplicity first

Do the simplest thing that works well. Scale the code to the problem as it exists today — features, abstractions, and configurability earn their place when the request needs them. Change code directly rather than adding flags or compatibility shims around it. Comments say what the code cannot: constraints, invariants, non-obvious whys.

Why: every speculative branch is code someone must read, test, and maintain against a need that may never arrive.

3. Surgical changes

Write changes that read like the surrounding code — match its comment density, naming, and idiom. Every changed line traces to the request; adjacent code stays as found (mention what you noticed, so the user decides). Clean up the orphans your own change created: imports, variables, functions now unused.

Why: reviewers audit the diff; unrelated churn hides the real change and widens the blast radius.

4. Verifiable goals

Turn the task into a runnable check before starting — "fix the bug" becomes a test that reproduces it. Report completion against tool results from this session (exit codes, test output, screenshots), and say plainly when something is not yet verified.

Why: a stated check lets you work independently, and evidence-grounded claims are what make "done" trustworthy.

5. Let errors surface

Handle an error where you can do something meaningful with it — a retry, a fallback the user asked for, an actionable message. Everywhere else let it fail near its cause, loudly; in unattended jobs a non-zero exit beats running on values nobody chose.

Why: a swallowed error is a bug with a delay — that is how failures go unnoticed for months.

Appendix — v1 prescriptive form, for weak-model delegation

When delegating to haiku-tier models (the smallest/cheapest tier, e.g. Haiku 4.5, typically run as subagents), include the relevant rules below verbatim in the delegation prompt. On frontier models the judgment form above is enough; benchmarks showed no gain from the explicit form there, and on Sonnet it added refusal bias.

• State assumptions explicitly; if uncertain, ask. If multiple interpretations exist, present them — don't pick silently.
• No features beyond what was asked. No abstractions for single-use code. No speculative "flexibility" or "configurability". No error handling for impossible scenarios. If 200 lines could be 50, rewrite.
• Comments only for what the code cannot say — constraints, invariants, non-obvious whys. No narration, no notes to the reviewer, no docstrings on trivial functions.
• Don't "improve" adjacent code, comments, or formatting. Match existing style. Mention unrelated dead code — don't delete it. Remove imports/variables/functions that your changes made unused.
• Define success criteria before starting; loop until verified. Every changed line must trace to the request.
• try/except only where the error is handled meaningfully (retry, requested fallback, actionable message); otherwise let it crash near its cause. Never catch-and-continue with a default that masks a real failure.

Related skills

• universal-loop — the execute-verify iteration engine for §4.
• compounding-engineering — process-level discipline across sessions; these guidelines are code-level.
• writing-claude-md — the same Claude 5 encoding principles applied to instruction files.