Andrej Karpathy's Skill: One CLAUDE.md File to Improve Claude Code

Andrej Karpathy's skill is a short CLAUDE.md file you drop at your repository root: it packs four rules that stop Claude Code from making its most common coding mistakes — silent assumptions, bloated code, and drive-by edits to unrelated files. It works by adding behavioral rails Claude reads at the start of every session — not by retraining or changing the model itself.

The rules distill Karpathy's observations about the "snakes that bite" — recurring failure modes LLMs hit — from his shift to mostly agent-driven coding. The core problem isn't a weak model; it's a model confident enough to pick one interpretation of an ambiguous task and run with it silently. Configure CLAUDE.md well and your diffs (the line-by-line code changes) get cleaner, stay closer to the request, and carry far fewer self-inflicted regressions.

Four behavioral rails from a CLAUDE.md file guiding an AI coding agent to write code more carefully

What is "andrej-karpathy-skills"?

This project grew out of Andrej Karpathy's shift from mostly manual coding to mostly agent-driven work. During that shift he identified specific "snakes that bite" — recurring failure modes where an LLM picks one reading of an ambiguous task and proceeds silently. He noted that models frequently overcomplicate APIs, bloat abstractions, and modify unrelated code they don't fully understand.

The multica-ai/andrej-karpathy-skills repository (formerly forrestchang/andrej-karpathy-skills) turns those observations into a single instruction set, and has become one of the most-starred community skills for Claude Code. One thing worth being precise about: the failure-mode observations are Karpathy's, but the four rules that tell the model what to do are a community distillation, not Karpathy's own prescription.

Karpathy observed recurring LLM coding failures, and the community distilled them into a single CLAUDE.md file and the karpathy-guidelines skill

The main appeal is a measured drop in error rate — community benchmarks report that applying these guidelines can take Claude's coding-mistake frequency from 41% down to 11%. The project is now packaged as a proper Claude Code plugin under the Multica organization, giving teams a structured way to install it.

The four principles — and the mistake each one blocks

The framework leans on four constraints, each aimed at a reasoning failure that burns tokens and introduces regressions.

Principle	Addresses
Think Before Coding	Wrong assumptions, hidden confusion, and missing tradeoffs.
Simplicity First	Overcomplication, bloated abstractions, and speculative features.
Surgical Changes	Unrelated edits, drive-by refactoring, and style drift.
Goal-Driven Execution	Imperative task drift and weak success criteria.

The four principles and the mistake each blocks: Think Before Coding stops wrong assumptions, Simplicity First stops over-engineering, Surgical Changes stops edits to unrelated code, Goal-Driven Execution stops weak success criteria

1. Think Before Coding

LLMs typically pick an interpretation of a request and start writing immediately. This principle blocks "implementation by guessing." It forces the model to state assumptions explicitly and present multiple interpretations when a request is ambiguous. If the model is confused, it must stop and ask rather than hallucinate a path forward.

2. Simplicity First

Claude's default instinct is to over-engineer — adding error handling for impossible scenarios, or building abstractions for single-use code. This rule applies a senior-engineer filter: if the code is overcomplicated, simplify it. It explicitly forbids adding features, "flexibility," or configurability that nobody asked for.

3. Surgical Changes

This principle targets "drive-by refactoring," where Claude "improves" adjacent code or formatting. It draws a hard boundary: every changed line must trace directly to the request. Crucially, Claude must match the existing style even where it disagrees with the pattern, and must not refactor working code or delete pre-existing dead code unless told to.

4. Goal-Driven Execution

This is the framework's key insight. Instead of imperative instructions ("Add validation"), you give success criteria ("Write tests for invalid inputs, then make them pass"). A verifiable goal lets the model loop against it and iterate autonomously until the condition is met, rather than following a multi-step procedure it can drift away from.

How CLAUDE.md and Skills work in Claude Code

Claude Code relies on persistent instructions that load at launch. Every session starts with a fresh context window, and CLAUDE.md files plus Agent Skills are the two mechanisms that carry knowledge across sessions.

Progressive disclosure

To keep the context window from bloating, the system loads in three levels:

Level 1 (metadata): Claude loads the name and description of every installed skill into the system prompt at startup. This costs minimal tokens.
Level 2 (body): If the model decides a skill is relevant, it reads the full SKILL.md body into context.
Level 3 (linked files): For complex skills, extra files referenced from SKILL.md load only when a specific task triggers the need.

Three-level progressive disclosure: level 1 loads only metadata, level 2 reads the full SKILL.md, level 3 loads linked files only when needed

Loading and resolution order

Claude Code walks up the directory tree from your working directory and concatenates every instruction file it finds, in this order:

Managed policy (e.g. /etc/claude-code/CLAUDE.md): organization-wide standards.
User instructions (~/.claude/CLAUDE.md): personal preferences and shortcuts.
Project instructions (./CLAUDE.md): team-shared standards.
Local instructions (./CLAUDE.local.md): gitignored personal project notes.

Instructions closer to the working directory are read last, so they take final precedence — which is how a project rule overrides an organizational one.

Installing it: plugin, plain CLAUDE.md, or Cursor rule?

You can deploy the guidelines three ways.

Option A: Claude Code plugin (recommended)

Installs the guidelines as a global skill available across every project.

bash

/plugin marketplace add multica-ai/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Option B: project-level CLAUDE.md

To apply the rules without a plugin, pull the raw file into your project root.

bash

curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md

Option C: Cursor

Keep parity across IDEs by saving the guidelines as a committed project rule at .cursor/rules/karpathy-guidelines.mdc.

A valid CLAUDE.md entry or skill follows this shape so the system prompt picks it up:

markdown

---
name: karpathy-guidelines
description: Behavioral rails to prevent over-engineering and silent assumptions.
---
 
# Surgical Changes
 
- Touch only what the request requires.
- Match existing style exactly.
- Do not refactor code that isn't broken.

To check which files loaded into your current context, run the /memory command — it lists every CLAUDE.md location across user and project scopes.

When to use it — and when it backfires

These guidelines bias toward caution over speed. They earn their keep on non-trivial, multi-file work where silent assumptions compound fast. For a typo fix, the full rigor is overkill.

Gaps the community has flagged

Practitioners have named a few gaps in the original set that surface during long agent sessions:

Token budgets: without a budget rule, debugging loops can run indefinitely. Community advice is to cap tokens per task and per session, then summarize and start fresh when you approach the limit.
Multi-step checkpoints: the Goal-Driven rule has no progress reporting. Force Claude to summarize verified work and remaining steps after each significant change, to catch failures before they compound.
Read before write: "Surgical Changes" stops Claude touching adjacent code but doesn't force it to understand it. Have it read exports and immediate callers before writing, to avoid duplicate functions.
Failure to push back: "Simplicity First" can produce lazy code. Instruct Claude to flag when a request deviates from settled industry practice.

The community's "5th rule"

The most-shared addition is an "open to better ideas" clause: it lets the model suggest a better approach or surface design smells. The guardrail that keeps it useful: only trigger when the alternative avoids real risk or wasted work, so every small task doesn't turn into a strategy meeting.

Pick the rules that fit your repo, don't copy the whole file

Treat these rules as code-adjacent infrastructure that has to earn its place in the repo. Their job is narrow: automate away the recurring failure modes, so your judgment goes to the decisions that actually need it. On a complex migration they stop the model from creating regressions through over-ambitious cleanup; if they turn trivial tasks into planning loops, prune them. The whole game is moving from motivational prose ("be simple") to a concrete constraint ("don't add an abstraction unless it removes duplication in at least two call sites").