What It Is
A single CLAUDE.md file derived from Andrej Karpathy's observations about how LLMs go wrong when coding. Four principles aimed at fixing silent assumptions and over-engineering.
The four failure modes it addresses:
- Silent assumptions instead of asking for clarification.
- Overcomplicating code with unnecessary abstractions.
- Unintentionally modifying unrelated code sections.
- Lacking clear success criteria, so iteration drifts.
Language
Markdown. A single CLAUDE.md file, language-agnostic in effect.
Install
Add as a Claude Code plugin, or append the CLAUDE.md file to your project:
curl -L https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
Customize with project-specific rules after appending.
The Four Principles
1. Think Before Coding. State assumptions explicitly. Present alternative interpretations. Ask when ambiguous.
2. Simplicity First. Write minimal code solving only what was requested. No speculative features. No premature abstractions.
3. Surgical Changes. Edit only what the request requires. Match existing style. Don't refactor working code.
4. Goal-Driven Execution. Turn vague imperatives into verifiable success criteria. Lets the model loop toward a measurable target.
Value
Key insight from the repo: "LLMs are exceptionally good at looping until they meet specific goals." Clear success metrics beat step-by-step instructions. Tell the model what "done" looks like, then let it iterate.