The Andrej Karpathy Skills project is a set of behavioral guidelines for Claude Code — packaged as a singleDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/multica-ai/andrej-karpathy-skills/llms.txt
Use this file to discover all available pages before exploring further.
CLAUDE.md file and installable Claude Code plugin — that directly address the recurring coding mistakes Andrej Karpathy observed in LLMs. This page explains what those problems are, how the four principles address them, and how you’ll know the guidelines are working.
The problems
From Andrej Karpathy’s observations on LLM coding behavior:“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 really like to overcomplicate code and APIs, bloat abstractions, don’t clean up dead code… implement a bloated construction over 1000 lines when 100 would do.”
“They still sometimes change/remove comments and code they don’t sufficiently understand as side effects, even if orthogonal to the task.”These aren’t occasional edge cases — they’re patterns that cause wasted effort, unnecessary rewrites, and diffs that are hard to review.
The four principles
Each principle targets one of these failure modes directly.| Principle | Addresses |
|---|---|
| Think Before Coding | Wrong assumptions, hidden confusion, missing tradeoffs |
| Simplicity First | Overcomplication, bloated abstractions |
| Surgical Changes | Orthogonal edits, touching code you shouldn’t |
| Goal-Driven Execution | Leverage through tests-first, verifiable success criteria |
Think Before Coding
Don’t assume. Don’t hide confusion. Surface tradeoffs. Before implementing, the model should state assumptions explicitly, present multiple interpretations instead of picking silently, push back when a simpler approach exists, and stop to ask when something is unclear.Simplicity First
Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. No “flexibility” or “configurability” that wasn’t requested. If 200 lines could be 50, rewrite it. The test: would a senior engineer say this is overcomplicated? If yes, simplify.Surgical Changes
Touch only what you must. Clean up only your own mess. When editing existing code, don’t improve adjacent code, comments, or formatting. Don’t refactor things that aren’t broken. Match existing style, even if you’d do it differently. When your changes create orphans — imports, variables, or functions that your changes made unused — remove those. Don’t touch pre-existing dead code unless asked. The test: every changed line should trace directly to the user’s request.Goal-Driven Execution
Define success criteria. Loop until verified. Transform imperative tasks into verifiable goals. “Fix the bug” becomes “write a test that reproduces it, then make it pass.” Strong success criteria let the model loop independently. Weak criteria require constant clarification. From Karpathy:“LLMs are exceptionally good at looping until they meet specific goals… Don’t tell it what to do, give it success criteria and watch it go.”
How to know it’s working
These guidelines are working if you see:- Fewer unnecessary changes in diffs — only requested changes appear
- Fewer rewrites due to overcomplication — code is simple the first time
- Clarifying questions come before implementation — not after mistakes
- Clean, minimal PRs — no drive-by refactoring or unsolicited “improvements”
Next steps
Installation
Install via Claude Code plugin or add to your project’s CLAUDE.md
Customization
Merge these guidelines with your project-specific instructions