andrej-karpathy-skills: The CLAUDE.md File That Became a Viral Plugin
If you’ve spent time with Claude Code, you’ve probably already hit the wall that Andrej Karpathy described publicly: the model makes assumptions without asking, turns a 50-line solution into 400, or rewrites half your codebase when you asked it to fix a single function.
Karpathy said it plainly: LLMs make incorrect assumptions on your behalf and move forward without verifying. They don’t manage their confusion, don’t ask for clarification, don’t present tradeoffs, don’t push back when they should. And they love to complicate code: unnecessary abstractions, accumulated dead code, 1000 lines where 100 would have sufficed.
These aren’t reportable bugs — they’re structural complaints about how LLMs approach code by default. Forrest Chang took those observations and did something deceptively simple: he turned them into a CLAUDE.md. That file now has over 15,000 stars on GitHub.
What it actually does
The andrej-karpathy-skills plugin is a single CLAUDE.md with four behavioral principles:
1. Think Before Coding — Think before you code
Before writing a single line, Claude must declare its assumptions explicitly. If multiple interpretations of a task exist, it must surface them — not silently pick one and run with it. If something isn’t clear, it must stop, name what’s confusing, and ask.
2. Simplicity First — The minimum that solves the problem
No features beyond what was asked for. No abstractions for single-use code. No “flexibility” or “configurability” that nobody requested. No error handling for impossible scenarios. If you wrote 200 lines and they could be 50, rewrite them. The file even includes a self-check: “Would a senior engineer say this is too complicated? If yes, simplify it.”
3. Surgical Changes — Touch only what you need to touch
When editing existing code: don’t “improve” adjacent code, comments, or formatting. Don’t refactor things that aren’t broken. Respect the existing style even if you’d do it differently. If you detect unrelated dead code, mention it — don’t delete it on your own initiative. Every modified line should trace directly back to the user’s request.
4. Goal-Driven Execution — Define success, loop until verified
Transform vague tasks into verifiable objectives:
- “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” → “Make sure tests pass before and after”
For multi-step tasks, Claude must declare a brief plan with explicit verification points before starting.
These four principles directly counter the four failure modes Karpathy identified: silent assumptions, overcomplication, scope creep, and vague success criteria.
How to install it
Option A: via Claude Code’s plugin marketplace (recommended)
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
This installs the guidelines as a global plugin — available across all your projects automatically.
Option B: curl directly to your project
For a new project:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
To add it to an existing CLAUDE.md:
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
The file is designed to blend with your project-specific instructions. Your business rules go at the top; Karpathy’s guidelines go at the end as a base behavioral layer.
Why it went viral
This isn’t really about Claude Code specifically. It’s about an increasingly widespread realization: how you configure your AI coding assistant matters as much as which one you choose.
The plugin treats the model’s defaults as a starting point to correct — not as fixed behavior you have to work around with clever prompts session after session. And that resonates. The repo has already spawned ports for Cursor (.cursorrules) and VS Code Copilot (.github/copilot-instructions.md), which says something broader: the community is converging on a shared diagnosis of LLM failure modes in code, regardless of which tool they use.
CLAUDE.md, .cursorrules, and Copilot instruction files are becoming the new configuration layer for AI coding. And Karpathy’s observations are functioning as de facto standards in that layer.
What makes this micro-genre possible — prompt engineering as open source — is that CLAUDE.md is plain markdown that any LLM can read. That means a well-crafted file can be versioned, forked, discussed, and iterated like any other code project. With stars, forks, pull requests, and community debate. Exactly what’s happening.
Is it worth it?
The README itself is honest about the tradeoff: “These guidelines bias toward caution over speed. For trivial tasks, use judgment.” That’s the right framing. For a one-line fix, you probably don’t need the model to stop and enumerate assumptions. But for any non-trivial work — anything where an incorrect assumption costs you an hour reverting changes — the principles make sense.
The metric the plugin proposes: fewer unnecessary changes in diffs, fewer rewrites from overcomplication, clarifying questions before implementation instead of apologies after mistakes.
That’s a reasonable bar. And 15,000 stars suggest plenty of developers think it clears it.
Links
Do you use CLAUDE.md in your projects? Do you have your own rules you add to Karpathy’s? Share your setup in the comments 