Code Review & Git · Blog Post
Karpathy-inspired coding guidelines: four rules for a calmer coding agent
Coding agents guess instead of asking, write 200 lines where 50 would do, and tidy up code nobody asked them to touch. This small community project turns Andrej Karpathy's public complaints about exactly that into one 65-line instruction file, available as a CLAUDE.md, a Claude Code skill, and a Cursor rule.
By Mehadi Hasan 6 min read
What it is (and who made it)
andrej-karpathy-skills describes itself as "a single CLAUDE.md file to improve Claude Code behavior." The file is a short set of behavioral rules for a coding agent, grouped under four principles.
One thing to be clear about up front: this is not a Karpathy project. Andrej Karpathy did not write or publish it. The README says the guidelines are "derived from Andrej Karpathy's observations on LLM coding pitfalls" and links to a post of his on X, which it quotes at length. The plugin manifests list the GitHub user forrestchang as author. The repo was created under that account and now lives under the multica-ai organization; the old forrestchang/andrej-karpathy-skills address still resolves to it. The name borrows Karpathy's reputation. The substance is someone else's careful summary of his complaints.
Those complaints will be familiar to anyone who has handed real work to an agent. The README quotes Karpathy saying models "make wrong assumptions on your behalf and just run along with them without checking." He also notes that they overcomplicate code and APIs, and that they change or delete code they don't fully understand as a side effect of an unrelated task.
What's inside
The repo is small, and that's deliberate. The core is CLAUDE.md. The same text ships two more ways: as skills/karpathy-guidelines/SKILL.md, which the Claude Code plugin exposes, and as .cursor/rules/karpathy-guidelines.mdc, a Cursor project rule set to alwaysApply: true. CURSOR.md covers the Cursor setup. EXAMPLES.md is the most useful extra: about 500 lines of before-and-after Python showing each principle being broken and then followed. There's also a Simplified Chinese README.
On licensing, the README ends with "License: MIT", and the plugin manifest and SKILL.md front matter both say MIT. However, as of November 17, 2026 the repo has no LICENSE file, and GitHub doesn't detect a license for it. If you plan to redistribute the text inside a product, treat that gap as something to resolve with the maintainers, not as settled.
How it works: four principles
Nothing executes. The file is plain instructions the agent reads at the start of a session (CLAUDE.md, Cursor rule) or loads when a task looks relevant (the skill). Each principle has a one-line rule and a few concrete do's and don'ts:
- Think Before Coding ("Don't assume. Don't hide confusion. Surface tradeoffs."): State assumptions, lay out competing interpretations instead of picking one silently, push back when a simpler approach exists, and stop to ask when something is unclear.
- Simplicity First ("Minimum code that solves the problem. Nothing speculative."): No features, abstractions, configurability, or error handling that nobody asked for. The check is whether a senior engineer would call the result overcomplicated.
- Surgical Changes ("Touch only what you must. Clean up only your own mess."): Leave adjacent code, comments, and formatting alone, match the existing style, and mention unrelated dead code rather than deleting it. Do remove imports or helpers your own change made unused.
- Goal-Driven Execution ("Define success criteria. Loop until verified."): Turn "fix the bug" into "write a test that reproduces it, then make it pass", and give multi-step work a short plan with a verify step per item.
The fourth principle comes from another Karpathy observation quoted in the README: models are very good at looping until they hit a specific goal. So you give them the goal and a way to check it, not step-by-step orders. In practice the file asks the agent to write plans in this shape:
Plan format from Goal-Driven Execution
1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check]
The file is open about the cost: these guidelines "bias toward caution over speed." For typo fixes and obvious one-liners it tells the agent to use judgment rather than apply the full routine.
Installation
The README recommends the Claude Code plugin, which makes the skill available in all your projects. Run these inside Claude Code:
Claude Code: plugin
/plugin marketplace add forrestchang/andrej-karpathy-skills /plugin install andrej-karpathy-skills@karpathy-skills
To use it in one project only, download the file as that project's CLAUDE.md. If you already have a CLAUDE.md, the README shows how to append to it instead:
Per project: new CLAUDE.md
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
Per project: append to existing CLAUDE.md
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 into your project's .cursor/rules/ folder. CURSOR.md notes that Cursor doesn't read .claude-plugin/ or CLAUDE.md by default, so the plugin route won't reach it. For other tools that only read a single root instruction file, CURSOR.md suggests copying CLAUDE.md in.
The commands use the old forrestchang path, which still resolves. The curl commands pull whatever is on main at that moment straight into your agent's instructions. Read the file before you do that, and pin a copy you've reviewed rather than re-fetching it blindly.
Using it day to day
There's nothing to invoke. Once the rules are loaded, you work as usual and the agent's habits are what change. The README lists the signs that it's working: fewer unnecessary changes in diffs, fewer rewrites caused by overcomplication, clarifying questions before implementation rather than after mistakes, and clean, minimal PRs without drive-by refactoring.
It's built to sit alongside your own rules, not replace them. The README suggests adding a "Project-Specific Guidelines" section for things like TypeScript strict mode or where your error-handling helpers live. The four principles cover general behavior; your section covers how this codebase works.
The best way to get the most from it is to change how you phrase requests. "Fix the checkout bug" leaves the agent to decide when it's done. "Write a test that reproduces the double-charge on retry, then make it pass" gives it a finish line it can check itself, which is exactly the habit the fourth principle is trying to build.
Pricing
Free. There's no paid tier, account, or API key. The only cost is context: about 65 lines of instructions loaded into each session, which is small next to most project CLAUDE.md files.
My take
Most of this is advice a good senior engineer gives a new hire: ask before guessing, don't build what wasn't asked for, keep the diff on topic, prove it works. What makes the file worth having is that it's short and specific. "Every changed line should trace directly to the user's request" is a rule an agent can actually check against. "Write clean code" isn't. And at 65 lines it doesn't crowd out the project instructions that matter more.
Keep your expectations realistic, though. These are instructions, not enforcement. They push the agent in a direction; they don't guarantee anything, and they say nothing about testing infrastructure, security, or your codebase's conventions. If you want a whole process with planning and test-first gates built in, a heavier methodology like Superpowers goes much further. This file is the lightweight option: a sensible default you can paste into any project in a minute and edit freely.
Two caveats. First, the star count reflects the Karpathy name and the timing as much as the contents, so judge it by reading the file, which takes about three minutes. Second, the missing LICENSE file matters if you plan to bundle this text into something you ship.
Frequently asked questions
Did Andrej Karpathy write this?
No. It is a community project. The README says the guidelines are derived from Karpathy's observations on LLM coding pitfalls and quotes a post of his on X, but the plugin manifests list GitHub user forrestchang as author, and the repo now lives under the multica-ai organization.
Should I use the plugin or the CLAUDE.md file?
The README recommends the Claude Code plugin, which makes the skill available across all your projects. Use the CLAUDE.md route if you want the rules in a single repo, versioned with the code, and merged with your own project-specific instructions.
Does it work outside Claude Code?
The repo ships a Cursor project rule (.cursor/rules/karpathy-guidelines.mdc, set to always apply) that you copy into your own project. For other tools that read a single root instruction file, CURSOR.md suggests copying CLAUDE.md in. The text is plain Markdown either way.
What license is it under?
The README, plugin manifest, and SKILL.md all say MIT, but as of November 17, 2026 the repo has no LICENSE file and GitHub does not detect a license. Fine for personal use; if you plan to redistribute the text, confirm with the maintainers first.