Stop your coding agent from overbuilding: hands-on with the Karpathy guidelines for Claude Code

A 65-line text file distilled from Andrej Karpathy's observations about coding agents is one of GitHub's most-starred projects this week. This guide installs it in Claude Code and Cursor, explains its four principles, and proves each one on real code — with the honest limits stated.

• Who: multica-ai/andrej-karpathy-skills (MIT) — 226,457 stars, 22,611 forks, 28 commits, created January 27, 2026; core file 65 lines; plugin version 1.0.0.
• What: four behavioural principles for coding agents — think before coding, simplicity first, surgical changes, goal-driven execution — plus a Cursor rule, a skill package, and a 522-line examples file.
• When: verified October 29, 2026: curl download, append path, plugin manifest, Cursor rule frontmatter, and a Python before/after demo with passing tests.
• Requirement: Claude Code or Cursor, curl, git, Python 3 for the demo. No API key for the install, no GPU, no payment.

Why this file is everywhere right now

Open GitHub's weekly trending page this week and, among the agent frameworks and design skills, sits a repository whose entire product is one short text file. The project, multica-ai/andrej-karpathy-skills, holds 226,457 stars and 22,611 forks at the time of writing, on just 28 commits since its creation on January 27, 2026. Its core file, CLAUDE.md, is 65 lines long. It contains no code, no model, and no tooling. It is a list of behavioural rules for a coding agent, distilled from observations Andrej Karpathy published about the ways large language models mishandle coding work.

The reason it spreads is that the failures it names are ones every developer who has used a coding agent recognises instantly. The agent silently picks an interpretation of an ambiguous request instead of asking. It builds a configurable framework where a twenty-line function would do. It "improves" neighbouring code nobody asked it to touch, and the resulting diff is three times the size of the change. It declares a task done without ever running a check that could prove it. Karpathy's point, as the repository frames it, is that these are not reasoning failures so much as missing work habits — and work habits can be written down.

This tutorial installs those habits in your own projects, shows exactly what each rule says, and proves the install with commands you can run yourself. One honest limit up front: this run had no Claude Code subscription in its sandbox, so it does not measure how much an agent's behaviour changes once the file is installed. What was verified here, command by command, is everything a reader needs to install the file correctly: the download, the file's contents, the plugin manifest, the Cursor rule, and a worked example of each principle applied to real code. Where a step comes from the project's documentation rather than from a sandbox run, the article says so.

What you'll need

• An agent host. Claude Code for the main path, or Cursor for the rule-file path. The guidelines themselves are plain text; any tool that reads a CLAUDE.md or a Cursor rule can use them.
• curl and git. Both are used below and both are verified in this guide.
• Python 3. Only for the worked example in Step 5, which runs its checks with the standard library — no packages to install.
• No API key, no GPU, no payment. Installing the guidelines costs nothing. The only cost in real use is whatever you already pay for the agent itself.

Step 1: Install it in one project

The simplest install puts the file at the root of a project, where Claude Code picks it up automatically. For a new project, download it directly:

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

For a project that already has a CLAUDE.md with its own instructions, append instead of overwriting — your project rules come first, the guidelines second:

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

Both commands were run for this tutorial. The download is 65 lines, and a check that the appended file contains all four principles passes:

grep -c "Surgical Changes" CLAUDE.md
# 1

One detail worth knowing: the repository began under the account forrestchang and now lives under multica-ai, while the plugin manifest still names the original owner. Both raw file addresses return HTTP 200 at the time of writing, so the older install commands in the project's documentation still work — but the current canonical address is the multica-ai one used above.

Step 2: Install it everywhere with the plugin (documented path)

If you want the guidelines in every project rather than one, the repository ships as a Claude Code plugin. Inside Claude Code, add the marketplace and install the plugin:

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

This path is quoted from the project's documentation and was not run in this tutorial's sandbox, which has no Claude Code subscription. What was verified is the manifest behind it: the cloned repository contains .claude-plugin/marketplace.json declaring a marketplace named karpathy-skills and a plugin named andrej-karpathy-skills, version 1.0.0, whose description names exactly the four principles covered below. The same clone also contains the guidelines as an installable skill under skills/karpathy-guidelines/SKILL.md, so agent hosts that install skills rather than plugins have a route too.

Step 3: The Cursor path

Cursor users get the same rules as a project rule file. The repository carries .cursor/rules/karpathy-guidelines.mdc, and copying it into your project is enough:

mkdir -p .cursor/rules
cp /path/to/andrej-karpathy-skills/.cursor/rules/karpathy-guidelines.mdc .cursor/rules/

The rule file's frontmatter was checked in this run: it is marked to always apply, and its description states the same four aims — avoiding overcomplication, making surgical changes, surfacing assumptions, and defining verifiable success criteria. Replace /path/to/andrej-karpathy-skills with wherever you cloned the repository in Step 1's companion clone, or download the single file from the repository's .cursor/rules/ directory.

Step 4: What the four principles actually say

The whole file is short enough to read in two minutes, and you should read it — but here is what each principle demands, in plain terms.

1. Think before coding. Before writing anything, the agent must say what it is assuming, out loud. If the request has more than one reasonable reading, it presents them instead of quietly choosing one. If a simpler approach exists, it says so and pushes back. If something is unclear, it stops, names the confusion, and asks. The failure this targets is the confident silent guess: the export feature that exports every user, to a file nobody chose, in a format nobody approved.

2. Simplicity first. Write the smallest code that solves the problem and nothing speculative: no features beyond the request, no abstraction that serves a single use, no configurability nobody asked for, no error handling for situations that cannot happen. The file's own test is a question to ask of any generated code: would a senior engineer call this overcomplicated? If yes, rewrite it shorter.

3. Surgical changes. Touch only what the request requires. Do not tidy adjacent code, comments, or formatting. Do not refactor working code. Match the surrounding style even when you would personally write it differently. If your change strands an import or a variable, clean up your own orphan — but leave pre-existing dead code alone unless asked, mentioning it instead of deleting it. The test: every changed line should trace back to the user's request.

4. Goal-driven execution. Turn instructions into goals with a check attached, then loop until the check passes. "Add validation" becomes "write tests for invalid inputs, then make them pass." "Fix the bug" becomes "write a test that reproduces it, then make it pass." The insight behind it is that language models are good at looping toward a specific target and bad at knowing when an open-ended task is finished — so give them the target.

The file closes with two practical notes. First, the tradeoff is explicit: these rules bias toward caution over speed, so for trivial work — a typo fix, an obvious one-liner — judgment overrides the full ritual. Second, it tells you how to tell whether it is working: diffs carry fewer unrelated changes, fewer rewrites happen because the first attempt was overcomplicated, and clarifying questions arrive before implementation instead of after mistakes.

Step 5: See the principles on real code

Principles are cheap to quote, so here is a concrete before-and-after, both executed for this tutorial. The request is deliberately small: "add 13% tax to a price."

The unguided version invents a configuration class with a tax rate, a discount, a currency, and a rounding mode — four decisions the request never made:

class PricingConfig:
    def __init__(self, tax_rate=0.0, discount=0.0, currency="USD", rounding="half-up"):
        self.tax_rate, self.discount, self.currency, self.rounding = tax_rate, discount, currency, rounding

def price_with_config(base, cfg):
    subtotal = base * (1 - cfg.discount)
    return round(subtotal * (1 + cfg.tax_rate), 2)

Run with its defaults, it does not even answer the request — it returns the price unchanged, because the default tax rate is zero and applying tax requires extra setup the user never asked for:

python3 -c "
from demo_pricing import price_with_config, PricingConfig, price_with_tax
print('bloated default config:', price_with_config(100.00, PricingConfig()))
print('minimal, as asked:', price_with_tax(100.00))
"
# bloated default config: 100.0 (no tax applied without extra setup)
# minimal, as asked: 113.0

The simplicity-first version is one function that does exactly the asked job:

def price_with_tax(base, tax_rate=0.13):
    return round(base * (1 + tax_rate), 2)

And the goal-driven version of the same task starts from the check, not the code. Write the test first, stating the success criteria in numbers:

from demo_pricing import price_with_tax

def test_tax_examples():
    assert price_with_tax(100.00) == 113.00
    assert price_with_tax(49.99) == 56.49
    assert price_with_tax(0) == 0.0

python3 test_demo_pricing.py
# 3/3 tax examples pass.

Finally, the surgical-change principle has its own one-command check. Make a change in a git repository and inspect the diff before committing. In this tutorial's demo, a rounding fix touched exactly one file, one line added, one line removed:

git diff --stat
# calc.py | 2 +-
# 1 file changed, 1 insertion(+), 1 deletion(-)

If your agent's diff routinely shows files you did not mention, that is the signal the third principle is not holding — and it is a cheaper diagnostic than reading the whole diff.

Step 6: Make it yours, then watch the diffs

The file is designed to be merged, not worshipped. Append your own project rules to the same CLAUDE.md — the file itself says to merge it with project-specific instructions. A useful addition is a short section naming your stack's conventions (test runner, formatter, the one command that proves a change) so the "loop until verified" principle has a concrete loop to run in your project.

Then judge it the way the file suggests: over the next few agent sessions, watch three things. Are diffs smaller and confined to what you asked? Do first attempts come back simpler, needing fewer "rewrite this more simply" rounds? Do clarifying questions arrive before code instead of apologies after it? If none of those move, the file is installed but not loaded — check that your host actually reads project CLAUDE.md files, or that the plugin install in Step 2 completed. If they move, you have just bought better agent behaviour for the price of a 65-line text file.

When to use this vs alternatives

These guidelines are a behaviour layer, not a methodology. If you want a full development workflow with roles, phases, and review gates, a framework like Superpowers — covered in this blog's hands-on guide to the agentic skills framework — is the bigger commitment, and it pairs naturally with these rules rather than replacing them: the framework says how work proceeds, the guidelines say how each step should behave. If you want to write your own agent instructions from scratch, the guide to building an Agent Skill with SKILL.md covers that route; starting from the Karpathy file and editing it is faster than starting blank, and its four principles are a good checklist for anything you write yourself. And if you only need a one-off correction — "keep this change small" typed into one session — a prompt works for that session and is forgotten by the next; the point of installing the file is that the correction persists across sessions without retyping.

What this file is not: a benchmark, a model, or a guarantee. It cannot make a weak model strong, and on trivial tasks its caution costs more than it saves — which is why its own tradeoff note tells you to use judgment there. Treat it as a default posture for non-trivial coding work, not as a law.

The takeaway

The most popular coding-agent artefact on GitHub this week is not a tool at all. It is a reminder, written down where the agent cannot miss it: ask before assuming, build the smallest thing that works, touch only what was requested, and define done before starting. Install it with one curl command, verify it with one grep, and let your next few diffs tell you whether it earned its place. The file is free, the install takes a minute, and the habit it teaches is the one senior engineers spend years acquiring — state the goal, prove it, and leave everything else alone.