Karpathy's CLAUDE.md, Annotated (2026)

TL;DR

• Karpathy didn’t write the file. Andrej Karpathy posted observations about LLM coding pitfalls on X in late 2025. Jiayuan Chang turned those observations into a four-principle CLAUDE.md and published the forrestchang/andrej-karpathy-skills repo a few weeks later. The wording is Chang’s; the diagnosis is Karpathy’s.
• It’s short on purpose. The whole file is roughly 60 lines, well under Anthropic’s recommended 200-line target. Every line earns its place.
• Four principles, in order: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution. The order matters — earlier principles gate later ones.
• The verbatim source is below in every section, pulled from the repo’s main branch. Skip ahead to the 50-line starter if you want the template-and-go version.

How it went viral

Karpathy’s thread (X.com link, paywalled) summarised a few weeks of dogfooding Claude Code. Rather than quote behind the paywall, here is the diagnosis as Chang’s README captures it — the wording on which the four principles are built:

“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.”

“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.”

— paraphrased and directly cited in the andrej-karpathy-skills README

Chang’s repo dropped within two weeks of the thread. Akshay Pachaar amplified it on X. It hit Hacker News. Cursor users started copying the same rules into .cursor/rules/. By spring 2026 the repo had 111K stars and 11.1K forks. Crucially, the name — “andrej-karpathy-skills” — did most of the work. People searching for “Karpathy claude.md” or “Karpathy claude code” landed in one place.

The viral arc matters because it shaped a generation of CLAUDE.md files. Most of the templates you see on GitHub now share the same skeleton: four to six numbered principles, terse one-line rules under each, and a closing “these guidelines are working if…” section. That format is Chang’s; the diagnosis is Karpathy’s; the popularity is downstream of both.

What CLAUDE.md actually is (and where it lives)

Before annotating the file, a one-paragraph refresher on the Anthropic format. CLAUDE.md is a markdown file Claude Code reads at the start of every conversation. The official docs describe two complementary memory systems: CLAUDE.md is instructions you write; auto memory is notes Claude writes itself. Only the first concerns us here.

Files load in priority order from broadest to most specific:

• Managed policy (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux) — organisation-wide instructions IT pushes via MDM. Cannot be overridden by individual settings.
• Project (./CLAUDE.md or ./.claude/CLAUDE.md) — checked into git, shared with the team. This is where most CLAUDE.md content belongs.
• User (~/.claude/CLAUDE.md) — your personal preferences across all projects. Karpathy’s guidelines are a good fit here as well as in projects.
• Local (./CLAUDE.local.md) — personal project-specific notes; gitignored so it stays off the team’s repo.

Files concatenate rather than override; content from the filesystem root is read first, files closer to your working directory are read last. Anthropic’s explicit guidance on size is short and sharp:

“Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” — Anthropic’s memory docs.

Their best-practices page is even blunter: “Bloated CLAUDE.md files cause Claude to ignore your actual instructions.” Karpathy’s file is around 60 lines of prose plus headings. That’s the right scale for a cross-project preamble. Project-specific facts (build commands, test runners, naming conventions) are added on top of Karpathy’s file, not instead of it. The whole stack ideally still fits under 200 lines.

If you’re new to the format, our Claude Code best practices primer covers the surrounding ecosystem (skills, hooks, subagents). The rest of this post assumes you know how CLAUDE.md loads and walks the file itself.

The file, line by line

What follows is the full, verbatim CLAUDE.md from forrestchang/andrej-karpathy-skills, broken into sections with annotation between each block. Code blocks are quoted exactly as they appear in the repo (commit on main, May 2026). The wording is deliberate; nothing is paraphrased inside the <pre> blocks.

The preamble

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

Three things to notice. First, the file declares itself. Naming it # CLAUDE.md at the top is harmless on its own but matters when the file gets concatenated with project-level CLAUDE.md content lower down — you want a heading break so Claude can tell them apart.

Second, “Merge with project-specific instructions as needed.” This is the polite way of saying: this is a preamble, not a complete file. The author expects you to paste it on top of build commands, test runners, and conventions that only apply to your project.

Third, the Tradeoff line. Most CLAUDE.md files don’t admit a tradeoff exists. This one does: cautious behaviour is slower than reckless behaviour, and that’s a feature, not a bug. The implicit message “for trivial tasks, use judgment” is the escape valve. Without it, you’d see Claude solemnly asking clarifying questions before fixing a typo.

Principle 1: Think Before Coding

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

Why this works. The four bullets target the first failure mode Karpathy named: silent assumptions. LLMs default to picking an interpretation and proceeding; here the file installs an interrupt. Three of the four bullets end with “ask” or “present them” — actions Claude would otherwise skip.

The bold tagline matters. “Don’t assume. Don’t hide confusion. Surface tradeoffs.” The bold lines under each numbered principle are Chang’s most-copied invention. They function as memorable handles: when Claude is mid-task and has to retrieve the relevant rule, the tagline is the cache key. The surrounding bullets are detail.

When this fails in a different codebase. If your codebase is large, well-conventioned, and your tasks are mostly small — say, a Rails monolith with 200 engineers where most tickets are “fix this typo, add this button” — the rule fires too often. Claude will pause to ask clarification on requests that genuinely have one interpretation. Soften it: “If multiple interpretations exist on changes that touch more than three files, present them.” Trade some safety for speed.

If your codebase has a strong “just ship it” culture, this principle will fight you. Some teams want Claude to default to action and apologise later. That’s fine, but you should know you’re trading away the Karpathy default explicitly.

Principle 2: Simplicity First

## 2. 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 you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

Why this works. Five bullets that all start with “No” — and the format itself is the lesson. Negative rules are easier to verify than positive ones. “Write simple code” is unfalsifiable; “no error handling for impossible scenarios” is verifiable in a diff review. The 200-to-50-lines rule is the only positive instruction in the section, and it’s a concrete heuristic.

The senior-engineer test at the bottom is a model-elicitation pattern. By asking Claude to imagine a reviewer, you trigger a different sub-routine than “is this correct?”. It’s the same trick that “think step by step” exploits: change the framing, get a different inference path.

When this fails. In safety-critical code — payments, auth, anything regulated — “no error handling for impossible scenarios” is dangerous, because what feels impossible during implementation often turns out to be a CVE waiting to happen. Drop or invert that bullet for those modules. A path-scoped rule (.claude/rules/security.md with paths: ["src/auth/**"]) is the cleanest way to do this.

In speculative-prototype work, the rule is almost too good. You wanted Claude to over-engineer because you’re exploring a design space. Soften the wording, or accept that this principle pushes you toward tight, throwaway code by default.

Principle 3: Surgical Changes

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- 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.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

Why this works. This is the longest section, because it’s where Claude misbehaves most. The “drive-by refactor” is the single most common complaint about LLM-generated PRs: you ask for a one-line fix and get a 200-line diff that also “modernises” three unrelated files. Each bullet here is calibrated to a specific Claude failure mode.

The two-clause structure (“when editing existing code” vs. “when your changes create orphans”) splits the harder ethical question. Claude should clean up its own mess; it shouldn’t clean up someone else’s. The bullet that nails this: “If you notice unrelated dead code, mention it - don’t delete it.” That single line saves a thousand bad PRs.

The test sentence at the bottom — “Every changed line should trace directly to the user’s request” — is a falsification rule. You can run a diff review and check it. It also gives Claude a self-check to run before declaring a task complete.

When this fails. If your codebase needs aggressive cleanup — say, you inherited a React 16 monolith and you actually want Claude to modernise during edits — this principle is the wrong default. Either drop it or rephrase: “Match existing style unless the file is on the migration list at docs/migrations.md. In those files, follow the new patterns.”

Match-existing-style also fights you in monorepos with three competing styles where “existing style” is ambiguous. The fix is project-specific: name the canonical style explicitly (“Match the style in src/api/v2/ — that’s the canonical version”) so Claude isn’t left guessing.

Principle 4: Goal-Driven Execution

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform 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"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

Why this works. The three example transformations are the load-bearing piece. They show Claude how to rewrite a prompt into something it can verify. “Add validation” is imperative and vague; “Write tests for invalid inputs, then make them pass” is declarative with a built-in check. The arrow notation (→) is small but visually memorable.

The plan template in the fenced block is doing surprising work. By giving Claude a literal template for multi-step plans, the file removes one degree of creative freedom: when the model gets to step three of a refactor, it doesn’t have to invent a verification step, just fill in the blank. This same idea — structured planning before execution — is what Anthropic’s best-practices page calls “Explore first, then plan, then code.”

The closing line is the entire thesis: “Strong success criteria let you loop independently. Weak criteria (‘make it work’) require constant clarification.” This is the principle that is most directly downstream of Karpathy’s thread: he framed LLMs as exceptionally good at looping toward specific goals, and warned that vague goals burn the loop in useless cycles.

When this fails. Not every task fits the test-then-pass mould. Frontend pixel-tweaks, prose edits, copy-writing, design-token changes — these don’t have a unit-testable success criterion. For visual work, Anthropic’s recommended substitute is screenshots: “take a screenshot of the result and compare it to the original. List differences and fix them.” Add a bullet to your project CLAUDE.md that captures the non-test verification pattern (screenshot diff, lint pass, visual review checklist) so the principle still applies in those domains.

The closing line

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Most CLAUDE.md files end with “Thanks!” or nothing. This one ends with falsifiable signals. If, after a week of using the file, your diffs are not smaller, your rewrites are not fewer, your clarifying questions are not arriving earlier, the file is not working — and you should tune it. That self-falsification clause is a model for every CLAUDE.md you write.

Patterns it popularised

Five conventions in the Karpathy CLAUDE.md have been copied so widely they now read as the de-facto format. Worth naming them so you can use them deliberately.

1. Numbered principles, not paragraphs. Four ## N. Title sections are easier to retrieve than 800 words of prose. Anthropic’s docs agree: “use markdown headers and bullets to group related instructions.”
2. Bold tagline per principle. “Don’t assume. Don’t hide confusion. Surface tradeoffs.” The tagline is the cache key. Sub-bullets are detail.
3. “Don’t X” over “Prefer Y”. Negative rules are easier to verify than positive ones. The Karpathy file uses some flavour of “don’t”, “no”, or “avoid” on roughly half its rules.
4. An explicit test per section. “Would a senior engineer say this is overcomplicated?” “Every changed line should trace directly to the user’s request.” These are self-check prompts Claude can run. They turn rules into procedures.
5. A “working if” clause at the end. Falsifiable signals so you know when to tune the file.

If you’re writing your first CLAUDE.md, those five conventions are the safe defaults. Most homemade files that fail do so by skipping (3) — they pile on positive rules nobody can verify — or by skipping (5), at which point the file just grows.

Derivatives and forks

The Karpathy CLAUDE.md format spawned a small ecosystem. Three derivatives are worth knowing about; each one inherits the four-principle skeleton and adds a different layer.

addyosmani/agent-skills (~27.7K stars)

Addy Osmani’s repo extends the Karpathy skeleton from four principles into a full define-plan-build-verify-review-ship workflow, encoded as 20 skills plus a CLAUDE.md preamble. The repo’s own framing is “Process, not prose.” Each skill ships with step-by-step workflows, anti-rationalisation tables (documenting common shortcuts agents try to take), red flags, and verification requirements.

What it adds beyond Karpathy: phase gating. Define before Plan, Plan before Build, Build before Verify, Verify before Review, Review before Ship. The four-principle Karpathy core is folded in as the build-phase contract. It’s a heavier framework — the Anti-Rationalisation tables alone run hundreds of lines — but if you’re shipping production code with multiple Claude sessions fanning out, that structure earns its keep.

Cursor-rule mirrors

The same andrej-karpathy-skills repo ships a parallel .cursor/rules/karpathy-guidelines.mdc file with the same four principles wrapped in Cursor’s front-matter format. Cursor reads project rules from .cursor/rules/, so dropping the same guidelines into a Cursor codebase is a one-file copy. The lesson here generalises: if your team uses two or more agents, write the rules once and ship two front-matter wrappers.

Anthropic’s own skills repo (~128K stars)

The official anthropics/skills repo is the canonical SKILL.md reference but, perhaps surprisingly, has no CLAUDE.md. Anthropic ships category-organised skills (Creative & Design, Development & Technical, Document Skills) with YAML-frontmatter SKILL.md files. The implicit lesson: long-form behavioural guidelines belong in CLAUDE.md; repeatable workflows belong in skills. Karpathy’s file gets the first job right; Anthropic’s repo shows what the second job looks like.

A 50-line starter you can copy

If you want to start from a Karpathy-style preamble plus the project-specific facts Anthropic recommends, paste the following into ./CLAUDE.md, fill in the blanks, and prune ruthlessly. The total ships well under Anthropic’s 200-line ceiling.

# CLAUDE.md

Project conventions, build commands, and behavioural guidelines for
Claude Code working on this repo. Read top-to-bottom at session start.

## Build & test

- Install: `pnpm install`
- Dev server: `pnpm dev` (Next.js on http://localhost:3000)
- Tests: `pnpm test:unit` for one file, `pnpm test` for all
- Lint: `pnpm lint` (ESLint flat config)
- Typecheck: `pnpm typecheck` after every series of edits

## Architecture (one paragraph)

[2–3 sentences on the one architectural decision you wish you'd
known on day one. Examples: "Static-first; pages don't query the
DB at request time" or "Domain-driven, no shared models across
contexts".]

## Behavioural guidelines

### 1. Think Before Coding
**Don't assume. Don't hide confusion. Surface tradeoffs.**
- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them.
- If a simpler approach exists, say so. Push back when warranted.

### 2. Simplicity First
**Minimum code that solves the problem.**
- No features beyond what was asked.
- No abstractions for single-use code.
- No error handling for impossible scenarios.
- If 200 lines could be 50, rewrite it.

### 3. Surgical Changes
**Touch only what you must. Clean up only your own mess.**
- Don't refactor things that aren't broken.
- Match existing style.
- Mention unrelated dead code; don't delete it.
- Every changed line should trace to the user's request.

### 4. Goal-Driven Execution
**Define success criteria. Loop until verified.**
- "Fix the bug" → "Write a test that reproduces it, then make it pass."
- "Add validation" → "Write tests for invalid inputs, then make them pass."
- For visual changes, take a screenshot and diff against the target.

## Project gotchas

- [List 3–5 non-obvious facts that have bitten the team. Examples:
  required env vars, flaky test workarounds, why a specific function
  exists, what NOT to touch.]

## Working signals

These guidelines are working if: fewer unnecessary changes in diffs,
fewer rewrites due to overcomplication, and clarifying questions come
before implementation rather than after mistakes.

Two changes from the source Karpathy file are deliberate. First, the Build & test block at the top — Anthropic’s docs are emphatic that bash commands Claude can’t guess belong in CLAUDE.md, and a build/test cheat sheet is the single most-used reference in any session. Second, the “Project gotchas” section at the bottom — the place to record “a code review caught something Claude should have known about this codebase” lessons. Anthropic’s rule of thumb: if you typed the same correction last session, it belongs here.

Want to use this same file across multiple repos? Put the Behavioural guidelines section in ~/.claude/CLAUDE.md and the project-specific blocks in ./CLAUDE.md. They concatenate at session start. For a team-wide override that no individual user can drop, use the managed-policy location.

Anti-patterns: what not to do

CLAUDE.md vs Skills vs MCP

Karpathy’s file is the right tool only when the content needs to load every session. The two alternatives, briefly:

Karpathy’s four principles belong in CLAUDE.md because they apply on every task. A migrate-one-component skill belongs in .claude/skills/ because it only runs when you trigger it. Live database queries belong in an MCP server because they need fresh data. Mixing these up wastes tokens.

For the full taxonomy and trade-offs, see our Claude skills vs MCP vs subagents vs CLI decision matrix. If you’re still unsure why CLAUDE.md exists at all, what are Claude Code skills covers the boundary from the other side. And our context bloat guide is the deep version of the “don’t bloat CLAUDE.md” argument.

Frequently asked questions

Sources

Primary repo + the file itself

• github.com/forrestchang/andrej-karpathy-skills — README, install methods, MIT license, ~111K stars (May 2026)
• raw CLAUDE.md on main — the full verbatim file quoted throughout this post
• skills/karpathy-guidelines/SKILL.md — the same content packaged as a Claude Code skill

Karpathy’s thread (paywalled, mirrored)

• x.com/karpathy/status/2015883857489522876 — the original thread (login wall as of May 2026)
• threadreaderapp.com mirror — third-party unrolled thread; quotes in this post are drawn from Chang’s README which paraphrases Karpathy directly

Anthropic docs

• code.claude.com/docs/en/memory — CLAUDE.md format, file locations, load order, the 200-line guidance, auto memory
• code.claude.com/docs/en/best-practices — “Write an effective CLAUDE.md,” bloat warnings, the include/exclude table, hooks/skills ecosystem

Derivative repos

• github.com/addyosmani/agent-skills — ~27.7K stars, 20 skills across define-plan-build-verify-review-ship
• github.com/anthropics/skills — ~128K stars, official SKILL.md reference (no CLAUDE.md, by design)

Internal links

• /blog/claude-code-best-practices — surrounding ecosystem (skills, hooks, subagents)
• /blog/what-are-claude-code-skills — when to put content in a skill instead
• /blog/claude-skills-vs-mcp-vs-subagents-vs-cli-2026-decision-matrix — the full taxonomy
• /blog/mcp-context-bloat-fix-2026-tool-search-code-mode-progressive-disclosure — why bloat hurts even when it’s small
• /blog/claude-code-hooks — for behaviour you want enforced, not just suggested
• /blog/what-is-mcp — protocol primer if you’re looking at MCP servers next
• /blog/context7-vs-deepwiki-vs-ref-vs-docfork-2026 — docs-RAG MCP servers compared
• /best-mcp-servers — curated roundup of MCP servers
• /skills — browse the Claude Code skill catalogue
• /servers — browse all 3,000+ MCP servers