Karpathy's 4 CLAUDE.md principles: ask first, write less, change surgically, verify

Andrej Karpathy has described the familiar failure modes of letting an LLM write code: the model makes assumptions on your behalf and runs with them, doesn't ask when it's confused, loves overcomplicating things with needless abstractions, and casually edits unrelated code or comments along the way. The andrej-karpathy-skills repo (about 226K GitHub stars at the time of writing) turns those observations into one CLAUDE.md file with four principles. It's one of the cheapest ways to improve Claude Code's behaviour: a few dozen lines, nothing complicated to install. This post breaks down each principle, how to install it, and when not to apply it mechanically.

The four principles

1. Think before coding

• State assumptions; if unsure, ask instead of guessing.
• If a request can be read several ways, list them instead of silently picking one.
• Push back when there's a simpler way; when confused, name what's unclear.

2. Simplicity first

• No features beyond the request, no "flexibility" or "configurability" nobody asked for.
• No abstractions for single-use code, no error handling for cases that can't happen.
• If 200 lines could be 50, rewrite it.

3. Surgical changes

• Don't "improve" nearby code, comments or formatting; don't refactor what isn't broken.
• Match the existing style, even if you'd write it differently.
• Unrelated dead code: mention it, don't delete it. Only clean up imports and variables your own change made unused.

4. Goal-driven execution

Turn commands into goals with a test: "Fix the bug" becomes "write a test that reproduces it, then make it pass"; "Refactor X" becomes "tests pass before and after". For multi-step work, state a short plan with a check for each step. Clear criteria let Claude iterate on its own until it gets there, instead of asking you constantly.

Installation

• Plugin (recommended in the README): add the repo's marketplace with /plugin marketplace add, then /plugin install as instructed; applies to every project.
• Per-project CLAUDE.md: download the repo's CLAUDE.md into your project root, or append it to your existing CLAUDE.md, then keep project-specific rules in their own sections.
• Cursor: the repo ships a rule in .cursor/rules/.

Because it's only a few dozen lines, it fits the advice to keep CLAUDE.md short: it describes behaviour, something Claude can't read from the code.

Signs it's working

• Smaller diffs containing only the requested changes.
• Fewer rewrites caused by overcomplication.
• Clarifying questions arrive before the code, not after a mistake.
• Clean PRs with no drive-by refactoring.

Tradeoffs and caveats

• The principles favour caution over speed. Trivial work (a typo, an obvious one-liner) doesn't need the full process; the README says so too.
• "Ask first" can become asking too much; if it annoys you, add "for small tasks, just do it and report".
• It doesn't replace tests and review. It reduces mistakes, it doesn't eliminate them.

How to apply it

• Dev: Append the four principles to your CLAUDE.md, work with it for a week, then compare diffs and how often you had to redo things.
• Tech Lead: Make "Surgical Changes" a review criterion for AI-generated PRs: every line must trace back to the ticket.
• PM: "Goal-Driven" applies to the requirements you write too: include verifiable acceptance criteria and both Claude and the developers do better work.