Andrej Karpathy skills: four rules against AI code that does too much

Ask an AI coding assistant to make a button blue and there is a fair chance you get back a diff with a new component structure, a CSS refactor and two helper functions nobody asked for. Andrej Karpathy described that behaviour on X in January 2026. Jiayuan Zhang, forrestchang on GitHub, turned it into four behaviour rules and published them on GitHub as andrej-karpathy-skills. What is in it, what does it fix, and where does it stop?

Updated on 5 November 2026: the repository has moved to multica-ai/andrej-karpathy-skills, the author is Jiayuan Zhang, and the article now has install steps and sources. The four rules themselves have not changed since January.

In short. The Andrej Karpathy skills are four behaviour rules for AI coding assistants in a single 65-line file: Think Before Coding, Simplicity First, Surgical Changes and Goal-Driven Execution. Karpathy did not write them; Jiayuan Zhang derived them from Karpathy's post about coding agents. The repository now lives at github.com/multica-ai/andrej-karpathy-skills and has more than 229,000 stars. In Claude Code you install it as a plugin with two commands; in any other project you put the file in the folder as CLAUDE.md.

What is andrej-karpathy-skills?

andrej-karpathy-skills is not a software library, a framework or an AI model, and Karpathy did not write it. At its core it is a single instruction file, CLAUDE.md, with four behaviour rules for AI coding assistants, derived from Karpathy's criticism of how language models write code.

The repository ships the same rules in three forms: as a Claude Code plugin with the skill karpathy-guidelines, as a plain CLAUDE.md file to drop into your project and, since April 2026, as a rules file for Cursor (.cursor/rules/karpathy-guidelines.mdc). According to the README and the plugin manifest the licence is MIT. There is no separate licence file in the repository; if that matters for use inside a company, point to those two files.

The repository first lived on the forrestchang account and now belongs to the multica-ai organisation. The old address redirects, and the install commands with the old name still work. At the top of the README, Zhang now points to his new project, Multica: an open-source platform for running and managing coding agents with reusable skills.

Why Karpathy's name carries weight: he was one of the founding members of OpenAI and led the computer vision team of Tesla Autopilot from 2017 to 2022. In his post of 26 January 2026 he described his own switch. In November he still wrote about 80 percent of his code himself (with autocomplete) and 20 percent with agents. By the time he posted, that had flipped: 80 percent agent coding, 20 percent edits and touch-ups.

The mistakes Karpathy saw

His complaints about coding agents come down to three things.

Silent assumptions. In his words: "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." A familiar example:

Request:
"Add authentication"

AI:
- picks JWT on its own
- writes middleware
- builds refresh tokens
- changes the database schema

Without first asking what you actually meant.

Too much code. Models like to overcomplicate code and APIs, pile up abstractions and leave dead code behind. Karpathy's example: a bloated construction of a thousand lines where a hundred would do.

Collateral damage. They sometimes change or remove comments and code they don't fully understand, even when it has nothing to do with the task.

Against that he set one strength: language models are very good at looping until they meet a specific goal. His advice: "Don't tell it what to do, give it success criteria and watch it go."

The four rules

The four rules in the file are a fairly direct translation of those complaints.

1. Think Before Coding: assumptions first

The assistant states its assumptions. If a request can be read in more than one way, it presents the options instead of silently picking one. If something is unclear, it stops and asks.

Bad:

User:
"Build a login system"

AI:
- adds JWT
- uses Redis
- builds OAuth
- sets up a complete auth structure

Good:

AI:
"Do you want:
- a simple session login?
- JWT authentication for an API?
- social login?
- Laravel Breeze or Fortify?"

2. Simplicity First: the smallest solution that works

No features beyond the request, no abstractions for code that is used once, no configurability nobody asked for. The file adds a test question: would a senior engineer call this overcomplicated? And a rule of thumb: if you wrote two hundred lines and it could have been fifty, rewrite it.

Bad:
- service layer
- repository
- adapter
- factory
- interface
  ... for a single calculation

Good:
- one function
- a clear name
- works straight away

3. Surgical Changes: touch only what you must

Possibly the most important rule. The assistant changes only what the task requires: no unrequested refactors, no reformatting, no "improvements" to neighbouring code. It follows the existing style, even if it would do things differently. Dead code it comes across gets mentioned, not deleted. Whatever its own change makes redundant (an import, a variable) it does clean up.

The test from the file: every changed line should trace back to the request.

Request: "Add a phone number field"

Too much:
- entire form component rewritten
- new validation layer
- new UI library

Enough:
+ input field
+ database migration
+ validation rule

4. Goal-Driven Execution: work towards something you can check

This is where Karpathy's positive point comes in. A vague task becomes a goal you can verify. "Fix the bug" becomes "write a test that reproduces the bug, then make it pass". "Add validation" becomes "write tests for invalid input, then make them pass". In a multi-step task, every step gets a check.

Success criteria:
- user can log in
- session survives a reload
- logout works
- tests pass

With criteria like these the assistant can keep going on its own until it is right. With "make it work" it keeps coming back to you.

Installing: Claude Code, a single project or Cursor

In Claude Code you first add the marketplace and then install the plugin. Type in a session:

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

The rules then apply in all your projects. Claude loads the skill itself when it writes, reviews or refactors code; to call it by hand, use /andrej-karpathy-skills:karpathy-guidelines. The commands come from the README and still use the old account name; that works because GitHub redirects.

If you only want the rules in one project, fetch the file. In a new project:

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

If the project already has a CLAUDE.md, append the rules instead of overwriting the file:

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

For Cursor, copy .cursor/rules/karpathy-guidelines.mdc from the repository into the same folder in your own project.

According to the README, you can tell it works from your diffs: fewer changes you did not ask for, fewer rewrites because the first version was too complicated, and questions before the code instead of after the mistake.

Why an instruction file is not a guarantee

A CLAUDE.md is a request, not a lock on the door. Anthropic's Claude Code documentation says Claude treats these files as context, not as enforced configuration. If you really want to block something, use a hook: a script Claude Code runs at a fixed point that can stop an action. The documentation also advises keeping a CLAUDE.md under 200 lines: longer files use more context and are followed less consistently. The file with the four rules has 65, so there is room for your own project rules.

The rules have a cost too, and the repository says so itself: they favour caution over speed. A typo or a one-line change doesn't need a round of questions. And because the assistant only mentions the dead code it finds, that code stays until you ask for a clean-up. That is a deliberate choice: better a small diff you can read than a big one you have to trust.

Rule 4 only works if there is something to check. If your project has no tests, "tests pass" is not a success criterion but a wish.

Are these actually skills?

Not quite. In Claude Code a skill is a folder in .claude/skills/ with a SKILL.md file, which Claude loads only when it is relevant, while CLAUDE.md is loaded in every session. OpenAI uses the word too, for reusable workflows in ChatGPT.

The Karpathy rules are not a task-specific workflow but general behaviour rules that always apply, so they belong in CLAUDE.md more than anywhere else. "Skills" is mostly packaging. The Claude Code plugin does ship them as a skill, karpathy-guidelines, with a description that says when it applies: when writing, reviewing or refactoring code.

Try it yourself

Put the four rules in the CLAUDE.md of a project where you already use an AI assistant, and check one thing in the next diff: does every changed line trace back to what you asked for? That is also why I find this small repository interesting. The best AI assistant is not the one that does the most, but the one that does exactly what is needed and nothing more.

Further reading on this site

• Getting started with Claude Code in November 2026: the complete guide to Python, IDE and database
• Claude Code in PhpStorm: setup, the plugin and the habits that work
• Cognitive debt in 2026: what we now know about AI code in web applications
• PHP and AI in 2027: the models already write your code, you prove it works

Sources

• Andrej Karpathy, post on X about coding with agents (26 January 2026)
• Jiayuan Zhang, multica-ai/andrej-karpathy-skills on GitHub: README, CLAUDE.md and SKILL.md; move, stars and commits via the GitHub API (accessed 5 November 2026)
• Multica, multica-ai/multica on GitHub
• Anthropic, How Claude remembers your project: CLAUDE.md as context, hooks, under 200 lines
• Anthropic, Skills in Claude Code: when a skill loads and how plugin skills are named
• Anthropic, Discover and install plugins