Andrej Karpathy Skills

What it does

Four principles in one CLAUDE.md, directly addressing the pitfalls Karpathy called out: models making wrong assumptions silently, overcomplicating code and APIs, and changing code they didn’t need to touch. Installs as a Claude Code plugin so the skill is available across all your projects.

What Karpathy flagged

The starting point is a post from Andrej Karpathy on X describing recurring failure modes when using LLMs for coding:

• ① Silent misjudgement — models make wrong assumptions on the user’s behalf and run with them unchecked — without managing confusion, asking for clarification, surfacing inconsistencies or tradeoffs, or pushing back when warranted.
• ② Overengineering — a tendency to overcomplicate code and APIs, bloat abstractions, and leave dead code in place — shipping thousand-line structures when a hundred would do.
• ③ Side-effect edits — changing or removing comments and code the model doesn’t sufficiently understand, as side effects of otherwise unrelated work.

On the direction of the fix, Karpathy points out that LLMs are exceptionally good at looping against a clear success criterion — so give them criteria to verify against instead of imperative instructions. The plugin’s four principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) map onto these three problems and the fix direction. See the linked post for the original framing.

The four principles

• Think Before Coding — Don’t assume. Don’t hide confusion. Surface tradeoffs.

  State assumptions explicitly, present multiple interpretations when ambiguity exists, push back when a simpler approach exists, and stop to ask when confused instead of picking one interpretation silently.

• 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 200 lines could be 50, rewrite it.

• Surgical Changes — Touch only what you must. Clean up only your own mess.

  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. 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. “Add validation” → “Write tests for invalid inputs, then make them pass.” “Fix the bug” → “Write a test that reproduces it, then make it pass.” Karpathy’s insight: 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

• 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 “improvements”

Notes

• Guidelines bias toward caution over speed. For trivial tasks (typo fixes, obvious one-liners), use judgment — not every change needs the full rigor.
• Designed to merge with project-specific instructions. Append to your existing CLAUDE.md and add project rules (TypeScript strict, test policies, etc.) as separate sections.
• Ships with .cursor/rules/karpathy-guidelines.mdc so the same rules apply when the project is opened in Cursor.
• License: MIT.