The Karpathy CLAUDE.md: One File That Makes Claude Ask Before It Guesses
TL;DR
andrej-karpathy-skills is a single CLAUDE.md file with over 216,000 stars on GitHub. Andrej Karpathy didn't write it: developer Jiayuan Zhang (forrestchang on GitHub) built it from Karpathy's January 2026 notes on X about the mistakes coding models make, and the repo now sits under multica-ai. It gives Claude Code 4 rules: think before coding, simplicity first, surgical changes and goal-driven execution. Drop it in your project root. The full file is below.
In January 2026 Andrej Karpathy posted "a few random notes from claude coding" on X. His top complaint was that models "make wrong assumptions on your behalf and just run along with them without checking." A developer turned those notes into one CLAUDE.md file with four rules, and it now has over 216,000 stars on GitHub. Here's the whole file and how to add it to your project.
216,686 stars on October 3, 2026. Holds the CLAUDE.md, a Claude Code plugin version, a Cursor rule and an examples file. The README says MIT license.
January 26, 2026: "A few random notes from claude coding quite a bit last few weeks." The section on fallibility is where the four rules come from.
What the 4 rules do
- Think Before Coding. State assumptions, lay out the options when a request can be read two ways, push back when there's a simpler way, and stop and ask when something is unclear.
- Simplicity First. Only the code that was asked for. No speculative features, no abstractions for one-time code, and rewrite 200 lines if 50 would do.
- Surgical Changes. Touch only what the task needs, match the existing style, and mention unrelated dead code instead of deleting it.
- Goal-Driven Execution. Turn tasks into checks, like "write a test that reproduces the bug, then make it pass", and loop until they pass.
The full file
Save this as CLAUDE.md in your project's root folder. It's copied exactly from the repo as of October 3, 2026.
markdown# CLAUDE.md
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
## 1. Think Before Coding
**Don't assume. Don't hide confusion. Surface tradeoffs.**
Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
## 2. 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.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
## 3. 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.
- If you notice unrelated dead code, mention it - don't delete it.
When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
## 4. Goal-Driven Execution
**Define success criteria. Loop until verified.**
Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
---
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.Add it to your project
New project, no CLAUDE.md yet. Run this in your project folder:
bashcurl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.mdYou already have a CLAUDE.md. Append it instead, so you keep your own rules:
bashecho "" >> CLAUDE.md
curl https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.mdEvery project, as a plugin. Inside Claude Code, run:
text/plugin marketplace add multica-ai/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skillsThen start a new Claude Code session. Anthropic's docs say CLAUDE.md files load at the start of every conversation, from ./CLAUDE.md or ./.claude/CLAUDE.md in your project, or from ~/.claude/CLAUDE.md for all your projects.
How to tell it's working
- Fewer unrelated changes show up in your diffs.
- Fewer rewrites because the first version was overbuilt.
- Claude asks its clarifying questions before it writes code, not after a mistake.
- Smaller, cleaner pull requests with no drive-by refactoring.
Make it yours
The file leans toward caution over speed, and the README says to use judgment on trivial tasks like a typo fix. Add your own project rules underneath it, like the README's example:
markdown## Project-Specific Guidelines
- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`Now you just code with a Claude that checks before it acts. Inside the Claude Code Club we share the CLAUDE.md setups and rules we actually use, and help each other tune them. It's nine dollars a month at https://www.skool.com/claudecodeclub/about. Everything on this page works without it.
Common questions
Did Andrej Karpathy write this CLAUDE.md?
No. It was written by developer Jiayuan Zhang (forrestchang on GitHub), based on a post Karpathy shared on X in January 2026 about the mistakes coding models make. The README describes it as derived from Karpathy's observations, and the repo now lives under multica-ai.
Does it stop Claude from hallucinating?
No. It pushes Claude to state assumptions, ask when unsure and keep changes small, which makes wrong guesses less likely. Anthropic's docs say CLAUDE.md is treated as context, not enforced configuration, so keep reviewing what Claude changes.
Where do I put the CLAUDE.md file?
In your project root as ./CLAUDE.md (or ./.claude/CLAUDE.md). To use it in every project, put it in ~/.claude/CLAUDE.md or install the plugin version. Start a new session so it loads.
Will it slow Claude down?
On small tasks it can, because it leans toward caution over speed. The README says to use judgment on trivial changes like typo fixes. The payoff is on bigger work where a wrong assumption is costly.
Does it work in Cursor?
Yes. The repo includes a Cursor project rule at .cursor/rules/karpathy-guidelines.mdc with the same guidelines, plus a CURSOR.md with setup notes.
Keep going
Want the rest of our Claude Code setup?
Get 650+ plug-and-play skills, MCPs & prompts, plus 8,000+ members - $9/mo, cancel anytime.
Join the Club