andrej-karpathy-skills

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

1. 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")

2. Added self-verification checklists — Before responding, Claude checks explicit criteria to catch violations before they happen

3. Added explicit anti-patterns — "NEVER Do This" sections call out specific bad behaviors like "Strategy/Factory patterns for single implementations" or "Change quote styles"

4. Created supporting examples file — skills/karpathy-guidelines/examples.md allows Claude to reference detailed before/after examples when the skill is invoked

5. 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: