Karpathy-Inspired Claude Code Guidelines
A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
Acknowledgements
This work was inspired by the repository https://github.com/forrestchang/andrej-karpathy-skills.
All code and documentation in this repository were generated by Claude Code powered by Opus 4.5.
Improvements Over the Original
This repository enhances the original Karpathy guidelines plugin with structural and behavioral improvements designed to make Claude more self-disciplined.
What Was Improved
| Aspect | Original | Enhanced |
|---|
| Language | Passive guidelines ("Don't assume") | Imperative core rules ("NEVER start until you've stated assumptions") |
| Self-checks | None | "Before You Respond, Verify" checklists for each principle |
| Anti-patterns | Implicit in guidelines | Explicit "NEVER Do This" sections with concrete examples |
| Examples | Separate docs folder only | Also available as examples.md supporting file in skills folder |
| Quick reference | None | 4-point checklist for rapid verification |
How It Was Improved
-
Added imperative "Core Rule" statements — Each principle now starts with a bold, actionable rule that Claude cannot ignore (e.g., "Every changed line MUST trace to the user's request")
-
Added self-verification checklists — Before responding, Claude checks explicit criteria to catch violations before they happen
-
Added explicit anti-patterns — "NEVER Do This" sections call out specific bad behaviors like "Strategy/Factory patterns for single implementations" or "Change quote styles"
-
Created supporting examples file — skills/karpathy-guidelines/examples.md allows Claude to reference detailed before/after examples when the skill is invoked
-
Added quick reference checklist — Four-point summary for rapid self-verification on every coding response
Why These Improvements Matter
| Improvement | Why It Helps |
|---|
| Imperative language | Passive guidelines are easier to rationalize around; imperative rules create hard boundaries |
| Self-check questions | Forces Claude to pause and verify before responding, catching mistakes proactively |
| Explicit anti-patterns | Naming specific bad behaviors makes them recognizable and avoidable |
| Supporting examples | Concrete before/after code is more actionable than abstract principles |
| Quick reference | Reduces cognitive load; Claude can verify in 4 checks instead of re-reading full guidelines |
The Problems
From Andrej's post:
"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."
"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."
"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."
The Solution
Four principles in one file that directly address these issues:
| Principle | Addresses |
|---|
| Think Before Coding | Wrong assumptions, hidden confusion, missing tradeoffs |
| Simplicity First | Overcomplication, bloated abstractions |
| Surgical Changes | Orthogonal edits, touching code you shouldn't |
| Goal-Driven Execution | Leverage through tests-first, verifiable success criteria |
The Four Principles in Detail
1. Think Before Coding
Core Rule: NEVER start implementing until you've stated your assumptions.
LLMs often pick an interpretation silently and run with it. This principle forces explicit reasoning:
- State assumptions explicitly — If uncertain, ask rather than guess
- Present multiple interpretations — Don't pick silently when ambiguity exists
- Push back when warranted — If a simpler approach exists, say so
- Stop when confused — Name what's unclear and ask for clarification
2. Simplicity First
Core Rule: Write MINIMUM code for TODAY's problem. Nothing speculative.
Combat the tendency toward overengineering:
- 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
The test: Would a senior engineer say this is overcomplicated? If yes, simplify.
3. Surgical Changes
Core Rule: Every changed line MUST trace to the user's request.
When editing existing code: