karpathy-guidelines

The Problem Karpathy Named

Andrej Karpathy — former Director of AI at Tesla, co-founder of OpenAI — posted a thread on X about the failure modes of LLM coding agents. Someone turned it into a single CLAUDE.md file. It now has 93k+ stars.

In his words: "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." They overcomplicate code, bloat abstractions, and "implement a bloated construction over 1000 lines when 100 would do."

These aren't edge cases — they're the default behavior of every coding LLM when you don't give it structure. The fix isn't a better model, it's a better contract. That's what this file does.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

• State assumptions explicitly — if uncertain, ask rather than guess
• Present multiple interpretations when ambiguity exists
• Push back when a simpler approach exists — say so before implementing
• Stop when confused — name exactly what's unclear

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was explicitly asked
• No abstractions for single-use code
• No "flexibility" or "extensibility" that wasn't requested
• If 200 lines could be 50, rewrite it to 50

The test: would a senior engineer call this overcomplicated? If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

• Don't "improve" adjacent code you weren't asked to touch
• Don't refactor things that aren't broken
• Match existing style, even if you'd do it differently
• Remove only imports/functions YOUR changes made unused — not pre-existing dead code

The test: every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

LLMs are exceptionally good at looping until they meet specific goals. Don't give them instructions — give them success criteria. The agent loops until each criterion is met. Example plan format:

11. Extract the auth middleware → verify: all routes still pass tests
22. Add rate limiting → verify: /api/login returns 429 after 5 attempts
33. Write unit tests → verify: 100% coverage on the new module

Installation — Claude Code Plugin (global)

1/plugin marketplace add forrestchang/andrej-karpathy-skills
2/plugin install andrej-karpathy-skills@karpathy-skills

Installation — Per project (CLAUDE.md)

Skill File (CLAUDE.md)

Our version of the Karpathy guidelines with minor additions for clarity. Drop it in your project root, or merge with your existing CLAUDE.md if you have one.

1# Karpathy Coding Guidelines
2
3Derived from Andrej Karpathy's observations on LLM coding pitfalls.
4Source: https://github.com/forrestchang/andrej-karpathy-skills
5
6---
7
8## 1. Think Before Coding
9
10Don't assume. Don't hide confusion. Surface tradeoffs.
11
12Before writing any code:
13- State your assumptions explicitly — if uncertain, ASK rather than guess
14- Present multiple interpretations when ambiguity exists — don't pick silently
15- Push back when a simpler approach exists — say so before implementing
16- Stop when confused — name exactly what's unclear and ask for clarification
17- Never silently adopt an interpretation and run with it
18
19## 2. Simplicity First
20
21Minimum code that solves the problem. Nothing speculative.
22
23- No features beyond what was explicitly asked
24- No abstractions for single-use code
25- No "flexibility" or "extensibility" that wasn't requested
26- No error handling for impossible or highly unlikely scenarios
27- If 200 lines could be 50, rewrite it to 50
28- No premature optimization
29
30The test: would a senior engineer call this overcomplicated? If yes, simplify.
31
32## 3. Surgical Changes
33
34Touch only what you must. Clean up only your own mess.
35
36When editing existing code:
37- DO NOT "improve" adjacent code, comments, or formatting you weren't asked to change
38- DO NOT refactor things that aren't broken
39- Match the existing style and conventions, even if you'd do it differently
40- If you notice unrelated dead code, MENTION it — don't silently delete it
41
42When your changes create orphans:
43- DO remove imports/variables/functions that YOUR changes made unused
44- DO NOT remove pre-existing dead code unless explicitly asked
45
46The test: every changed line should trace directly to the user's request.
47
48## 4. Goal-Driven Execution
49
50Define success criteria. Loop until verified.
51
52For multi-step tasks, state a brief plan first:
531. [Step] → verify: [specific check]
542. [Step] → verify: [specific check]
553. [Step] → verify: [specific check]
56
57Strong, specific success criteria let you loop independently until each criterion is met.

How to Know It's Working

• Cleaner diffs— only the lines you requested show up changed; no drive-by reformatting
• Simpler first pass— concise from the start, no 400-line solutions to 20-line problems
• Questions before mistakes— clarifying questions come before implementation, not after a wrong path
• Self-verifying outputs— the agent loops against success criteria and tells you when something can't be verified

Source

Source on GitHub (opens in a new tab) · Original Thread on X (opens in a new tab)