`karpathy-guidelines`: the 65-line CLAUDE.md stopping your agent from confidently doing the wrong thing

Andrej Karpathy (former Tesla AI director, now at Anthropic since May 2026) posted a thread in January about the three ways AI coding agents reliably fail. 1 Within 24 hours, developer Forrest Chang turned those observations into a single 65-line CLAUDE.md. It now has 172,000 GitHub stars and 18,000 forks — making it one of the most-starred behavioral config files in the agent ecosystem. 2

The thread that started it:

View on X

Loading content card…

The three failure modes Karpathy named

Karpathy described his shift from 80% manual coding to 80% agent coding, then catalogued what still goes wrong. Three categories dominated: 1

"The most common category is that the models make wrong assumptions on your behalf and just run along with them without checking."

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a 1,000-line bloated fragile contraption where 100 lines would have worked."

The third: agents silently modify or delete code they don't fully understand — even when it's unrelated to the task at hand. His fourth observation was the one with leverage: "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." 1

Forrest Chang's repo (multica-ai/andrej-karpathy-skills, MIT) encodes these observations as four behavioral principles in a CLAUDE.md file that loads as context at session start. 2

The four rules, decoded

1. Think Before Coding — Don't assume. Surface tradeoffs. Before writing code, state your assumptions explicitly. If a request has multiple valid interpretations, list them. When confused, stop and ask — don't pick the path of least resistance and silently proceed. The check the README suggests: "Would a senior engineer say this is overcomplicated?" 3

2. Simplicity First — Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. No error handling for scenarios that can't happen. If 200 lines can become 50, rewrite. 3

3. Surgical Changes — Touch only what you must. Clean up only your own mess. Don't "improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken. Match existing style. Remove orphan imports/variables you created — but leave pre-existing dead code alone. The check: "Every changed line should trace directly to the user's request." 3

4. Goal-Driven Execution — Define success criteria. Loop until verified. Convert "fix the bug" into "write a test that reproduces the bug, then make it pass." Multi-step tasks should start with a brief step→verify plan. Strong success criteria let the model close the loop without you. 3

The file closes with a note on tradeoffs: "These guidelines bias toward caution over speed. For trivial tasks (simple typo fixes, obvious one-liners), use judgment — not every change needs the full rigor." 4

Install

Three paths, in order of breadth:

Claude Code plugin (recommended — works across all projects):

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

curl into a single project's CLAUDE.md:

# New project — creates a fresh CLAUDE.md
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

# Existing project — appends to your current CLAUDE.md
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Cursor — copy the bundled rule file: 5

# From repo root, copy to your project's Cursor rules directory
cp .cursor/rules/karpathy-guidelines.mdc /your-project/.cursor/rules/

The .cursor/rules/karpathy-guidelines.mdc file carries alwaysApply: true in its YAML frontmatter, so it fires on every session without explicit invocation. 6

Other agents (Codex, Amp, Antigravity):

npx skills add https://github.com/forrestchang/andrej-karpathy-skills --skill karpathy-guidelines

Note: the README still references the old forrestchang/ path in curl commands — GitHub redirects automatically, so both paths work. 2

github.com · GitHub repository

multica-ai/andrej-karpathy-skills

https://github.com/multica-ai/andrej-karpathy-skills

Loading content card…

What the diff looks like in practice

The repo's EXAMPLES.md (522 lines) shows concrete before/after diffs for all four principles. 7 The most telling one is Principle 2:

A user asks: "Add a function to calculate discounts." Without the skill, the agent produces a DiscountStrategy abstract class, PercentageDiscount and FixedDiscount subclasses, a DiscountConfig dataclass, and a DiscountCalculator class — 30+ lines of setup before any discount is calculated.

With Simplicity First active, the output is a 3-line function: calculate_discount(amount, percent).

Principle 3 is equally sharp. A bug report says "validator crashes on empty email." The default agent adds type hints, a docstring, username length validation, and alphanumeric character checks to the whole file. The compliant version touches exactly two lines — the ones that handle the empty string case.

As the EXAMPLES.md puts it: "The 'overcomplicated' examples aren't obviously wrong — they follow design patterns and best practices. The problem is timing: they add complexity before it's needed." 7

The repo on GitHub: 172k stars, 18k forks, 0 open issues, MIT license — multica-ai/andrej-karpathy-skills — 172k stars, 18k forks, 8 contributors. 2

Community reception

Firecrawl's roundup of top Claude Code skills this week describes it as "the most battle-tested behavioral guardrail in the ecosystem. 144k stars reflects that every developer using AI coding agents has hit these exact failure modes." 8

On explainx.ai, the skill carries a 4.4 / 5 from 33 reviews. Recurring phrases in those reviews: "fits our agent workflows well — practical, well scoped, and easy to wire into existing repos" and "the kind of skill you can hand to a new teammate without a long onboarding doc." 9 Total installs across registries: ~4,200 on skills.sh, ~13,900 on the forrestchang branch of claudemarketplaces.com. 10

Reddit's r/AskVibecoders produced an extended 12-rule version that added guidance for agent loops, multi-step tasks, and silent failures. The author claimed the original 4 rules dropped their mistake rate from 41% to 11%; the added 8 rules brought it to 3% across 30 codebases over 6 weeks. 11 Those numbers aren't independently verifiable — no benchmark, no methodology — and AlphaSignal explicitly warns they "should not be cited." 12 The directional signal still holds: multiple independent reviewers across different languages and codebases confirm the diffs get cleaner.

The widely circulated "65%→94% accuracy" claim traces back to an unattributed Instagram reel with no named benchmark. The repo itself contains zero quantitative data. 12 BuildMVPFast's honest framing: "The accuracy jump is directional, not benchmarked. But the behavioral change is real and immediately visible in the quality of the diffs an agent produces." 13

One meta-observation from r/PromptEngineering (u/gvij): the innovation isn't the rules themselves — it's packaging. "SKILL.md gave the community a unit of distribution. You can publish, fork, version, install. That makes prompts shippable in a way they weren't before." 14

When NOT to use this

Trivial tasks get slower. On single-line fixes, typo corrections, and obvious one-liners, the clarification-before-coding rule generates friction where none is needed. The README acknowledges this. Use judgment on whether the overhead is worth it per task type.

Simplicity First blocks legitimate abstractions. "No abstractions for single-use code" is a good default but conflicts with codebases where requirements are expected to grow. If you're building a payment system, you probably want that PaymentProcessor abstraction even before you have multiple payment providers. Treat this rule as a menu item to customize, not a mandate. As Developers Digest puts it: "The fastest way to misuse this repo is to append the whole thing to every project and call it done. Generic rules are helpful until they conflict with local reality." 15

Surgical Changes can miss needed refactors. "Don't refactor things that aren't broken" runs counter to proactive technical-debt management in long-lived codebases. If you're actively paying down debt, remove or relax this rule in your project-specific CLAUDE.md layer.

The file is advisory, not enforced. CLAUDE.md is behavioral context loaded at session start. Anthropic's own documentation notes these guidelines are followed roughly 80% of the time. 12 There's no mechanism to verify whether a specific principle fired on a specific request — you can observe the diff but you can't audit the reasoning.

Karpathy didn't write this and hasn't endorsed it. TechTimes confirms: "Karpathy has not publicly endorsed the repository; it was authored by Chang and carries Karpathy's name because it was directly derived from his January 26 observations." 16 The last commit was April 20, 2026 — roughly 7 weeks ago. The repo has 0 open issues and a single maintainer (Forrest Chang, now focusing on MulticaAI), so future updates aren't guaranteed.

The practical playbook

Install the plugin for Claude Code for cross-project behavioral defaults. Then, per project, layer your own CLAUDE.md section on top — TypeScript strict mode, required test patterns, error-handling conventions, whichever rules are specific to your codebase. The README is explicit: "These guidelines are designed to be merged with project-specific instructions." 4

For Cursor users, copy the .mdc file and verify alwaysApply: true is set — Cursor doesn't read CLAUDE.md by default. The karpathy-guidelines.mdc file in the repo has this configured correctly. 5

The star count doesn't prove it works in your codebase. But the underlying problems it addresses — silent assumptions, scope creep in diffs, missing success criteria — are real failure modes that every agent developer eventually hits. Sixty-five lines of Markdown is a cheap experiment.

Cover image: AI-generated illustration