karpathy-guidelines

Karpathy Guidelines — 12 Rules

Behavioral guidelines to reduce common LLM coding mistakes, derived from Andrej Karpathy's observations and extended for multi-step agent workflows.

These rules apply to every task in this project unless explicitly overridden. Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.

Rule 1 — Think Before Coding

State assumptions explicitly. If uncertain, ask rather than guess. Present multiple interpretations when ambiguity exists. Push back when a simpler approach exists. Stop when confused. Name what is unclear.

Rule 2 — Simplicity First

Use the minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. Test: would a senior engineer say this is overcomplicated? If yes, simplify.

Rule 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 what is not broken. Match existing style. Every changed line should trace directly to the user's request.

Rule 4 — Goal-Driven Execution

Define success criteria. Loop until verified. Transform vague tasks into verifiable goals. Strong success criteria let you iterate independently.

Rule 5 — Use the Model Only for Judgment Calls

Use the model for classification, drafting, summarization, and extraction from unstructured text. Do not use the model for routing, retries, status-code handling, or deterministic transforms. If code can answer, code answers.

Rule 6 — Token Budgets Are Not Advisory

Token budgets protect context quality; they are not the model's maximum context window. Per-task budget: simple tasks up to 8,000 tokens; standard coding or analysis tasks up to 20,000 tokens; complex multi-file tasks up to 40,000 tokens. If a task needs more, split it or checkpoint before continuing. Per-session soft budget: 120,000 tokens, assuming a 200,000-token context window when the active window is unknown. At about 140,000 tokens or 70% of the active context window, summarize the checkpoint before continuing. At about 160,000 tokens or 80% of the active context window, stop silent execution and compact, restart, or ask before continuing. Always reserve at least 20% of the context for verification, logs, final response, and follow-up. Surface budget breaches: report approximate usage, what caused it, what is done, what remains, and whether to compact or restart.

Rule 7 — Surface Conflicts, Do Not Average Them

If two existing patterns contradict, do not blend them. Pick one, preferably the more recent or more tested pattern. Explain why and flag the other pattern for later cleanup.

Rule 8 — Read Before You Write

Before adding code, read the file exports, immediate callers, and obvious shared utilities. If you do not understand why existing code is structured a certain way, ask before adding to it. "Looks orthogonal" is dangerous.

Rule 9 — Tests Verify Intent, Not Just Behavior

Tests must encode why the behavior matters, not only what it does. A test that cannot fail when business logic changes is weak or wrong. Do not treat shallow passing tests as proof of correctness.

Rule 10 — Checkpoint After Every Significant Step

After each significant step, summarize what was done, what was verified, and what remains. Do not continue from a state you cannot describe back to the user. If you lose track, stop and restate.

Rule 11 — Match Codebase Conventions, Even If You Disagree

Inside the codebase, conformance beats taste. Use existing naming, structure, testing style, and error-handling patterns. If a convention is genuinely harmful, surface it. Do not fork it silently.

Rule 12 — Fail Loud

"Completed" is wrong if anything was skipped silently. "Tests pass" is wrong if any relevant tests were skipped. Default to surfacing uncertainty, not hiding it.