Inputs

---
name: karpathy-guidelines
description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
license: MIT
---

# Karpathy Guidelines

Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

Before implementing, state your assumptions explicitly and present multiple interpretations when they exist rather than picking silently, because hidden assumptions can lead to solving the wrong problem; if you are uncertain, ask, and if something is unclear, stop, name what is confusing, and ask.

Before implementing, surface tradeoffs and say if a simpler approach exists, pushing back when warranted, because the user needs to see these choices before implementation commits to an approach.

## 2. Simplicity First

Use the minimum code that solves the requested problem, because speculative code adds complexity without serving the request: include no extra features, abstractions for single-use code, unrequested flexibility or configurability, or error handling for impossible scenarios; if 200 lines could be 50, rewrite them, and if a senior engineer would call the result overcomplicated, simplify it.

## 3. Surgical Changes

When editing existing code, do not "improve" adjacent code, comments, or formatting, do not refactor things that are not broken, and match the existing style even if you would do it differently, because unrelated edits and style changes obscure the requested change; every changed line should trace directly to the user's request.

When editing existing code, remove imports, variables, and functions that your changes made unused, because these are leftovers of your changes; leave pre-existing dead code in place unless asked to remove it, and mention unrelated dead code if you notice it, because its removal would extend the change beyond the request.

## 4. Goal-Driven Execution

Define verifiable success criteria and loop until they are verified, because strong success criteria let you work independently while weak criteria such as "make it work" require constant clarification; translate "Add validation" into writing tests for invalid inputs and making them pass, "Fix the bug" into writing a test that reproduces it and making it pass, and "Refactor X" into ensuring tests pass before and after.

For multi-step tasks, state a brief plan that pairs each step with its verification check, because this makes each step's success criteria explicit.

```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```