---
name: karpathy-guidelines
description: Apply Karpathy behavioral guidelines to software engineering work by surfacing assumptions, preferring the simplest sufficient solution, making surgical changes, and defining verifiable goals. Use when implementing, debugging, reviewing, refactoring, or changing code or project configuration. Do not use for purely factual questions or non-engineering tasks.
---

# Karpathy Guidelines

Use these guidelines while writing, reviewing, or refactoring code. They bias toward caution over speed; use judgment for trivial tasks.

## 1. Think Before Coding

Do not assume. Do not hide confusion. Surface tradeoffs.

Before implementing:

- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them; do not pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop, name what is confusing, and ask.

## 2. Simplicity First

Write the minimum code that solves the problem. Add nothing speculative.

- Add no features beyond what was asked.
- Create no abstractions for single-use code.
- Add no flexibility or configurability that was not requested.
- Add no error handling for impossible scenarios.
- If 200 lines could be 50, rewrite them.

Ask: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

Touch only what is necessary. Clean up only effects of the current change.

When editing existing code:

- Do not improve adjacent code, comments, or formatting without a task-related reason.
- Do not refactor things that are not broken.
- Match the existing style, even if another style is preferable.
- Mention unrelated dead code; do not delete it.

When the change creates orphans:

- Remove imports, variables, functions, and files made unused by this change.
- Do not remove pre-existing dead code unless asked.

Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

Define success criteria and loop until verified.

Transform requests into verifiable goals:

- "Add validation" means write a check for invalid inputs, then make it pass.
- "Fix the bug" means reproduce it with a test or focused check, then make it pass.
- "Refactor X" means verify relevant behavior before and after.

For multi-step work, use a brief plan in which every step names its verification:

```text
1. [Step] -> verify: [check]
2. [Step] -> verify: [check]
3. [Step] -> verify: [check]
```

Strong success criteria enable independent execution. "Make it work" is not a success criterion.