andrej-karpathy-skills: four rules to stop your agent assuming instead of asking

andrej-karpathy-skills is a single CLAUDE.md file — sitting at 202,000 GitHub stars and still climbing — derived from computer scientist Andrej Karpathy's observations on how LLMs fail at coding. Install it once and your agent carries four behavioral rules that address the most common ways it silently goes wrong: assuming instead of asking, overbuilding, touching code it shouldn't, and stopping before it can verify success.

No runtime dependencies. No new MCP server to configure. Just a text file that primes the model before it touches your code.

The four rules

“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.”

— Andrej Karpathy

Think Before Coding — State assumptions upfront, surface ambiguity, ask rather than guess. If the request is genuinely unclear, halt and ask instead of picking an interpretation silently.

Simplicity First — Minimum code that solves the stated problem. No speculative features, no single-use abstractions, no error handling for scenarios that can't happen. The test: would a senior engineer call this overcomplicated?

Surgical Changes — Touch only what the task requires. Preserve existing style. Don't refactor code that isn't broken; don't remove pre-existing dead code that your changes didn't create.

Goal-Driven Execution — Define verifiable success criteria before starting. Loop until a concrete check passes rather than stopping when the code looks right.

When it actually helps

The rules shine on anything where the prompt is ambiguous or the codebase is large. Asking Claude to "refactor the auth module" without this skill loaded often produces a rewrite that quietly touches three adjacent things you never mentioned. With these rules in place, it tends to ask which part, propose minimal changes, and leave the rest alone.

The goal-driven execution rule is the sleeper hit. Reframing a request as "write a failing test that reproduces this bug, then make it pass" genuinely changes behavior — the model keeps iterating until a concrete check passes instead of stopping when the code *looks* right and declaring victory.

The real caveat

These are behavioral priming rules, not guarantees. On genuinely trivial tasks, "Think Before Coding" can generate a paragraph of stated assumptions before doing something that needed three keystrokes. The model doesn't know when to skip the preamble.

More importantly: the rules are only as good as the prompts they receive. If your request is vague, Karpathy's framing won't magic up the right interpretation — it'll ask more questions instead of guessing silently. That's usually better. It's not the same as being specific upfront, and no SKILL.md substitutes for a clear task description.

# Claude Code plugin (recommended)
/plugin install andrej-karpathy-skills

# Or drop the CLAUDE.md directly into any project
curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md

The repo also ships .cursor/rules for Cursor users and a SKILL.md for agents that support the skill format natively. Full source and MIT license at github.com/multica-ai/andrej-karpathy-skills.