The Karpathy Claude Code behaviour guide is a single CLAUDE.md file that has become one of the most-starred coding-agent resources on GitHub, with more than 224,000 stars and 22,000 forks at the time of writing. It is not a framework, a plugin with a dashboard, or a new model. It is a short set of behavioural instructions distilled from Andrej Karpathy’s public observations about how large language models actually fail when they write code — and it tells Claude Code, in plain language, to stop making those mistakes. If your team uses AI coding tools and you have ever reviewed a pull request that was three times longer than it needed to be, touched files nobody asked about, or confidently implemented the wrong interpretation of your request, this guide is aimed squarely at that pain.
In this deep-dive we cover what the guide is, the four principles it teaches, how to install it in under fifteen minutes, why it exploded in popularity, and — just as importantly — where it helps, where it gets in the way, and when you should not use it. Everything below is drawn from the repository itself, so you can verify every claim against the source.
What the Karpathy Claude Code Behaviour Guide Actually Is
The repository multica-ai/andrej-karpathy-skills contains one core artefact: a CLAUDE.md file. CLAUDE.md is the file Claude Code reads automatically at the start of a session in a project directory, and it acts as persistent instructions for how the agent should behave in that codebase. Instead of installing a dependency or learning a new tool, you drop this file into a project and the agent’s behaviour changes immediately.
The guide’s author built it from a widely shared post by Andrej Karpathy, the former Tesla AI director and OpenAI founding member, who described the recurring failure modes he sees when models write code. The diagnosis is blunt: models make wrong assumptions on your behalf and run with them without checking, they do not manage their confusion, they do not surface trade-offs, and they do not push back when they should. They also love to overcomplicate: implementing a bloated construction over a thousand lines when a hundred would do, and quietly changing comments and code they do not fully understand as a side effect of the task.
The guide answers that diagnosis with four principles, each phrased as behaviour rather than theory. That distinction matters. Most AI coding advice tells you what good code looks like; this file tells the agent how to act while producing it. There is no configuration, no build step, and nothing to learn — which is a large part of why it spread so fast.
The Four Principles, Explained
1. Think before coding
Do not assume. Do not hide confusion. Surface trade-offs. Before implementing, the agent must state its assumptions explicitly, present multiple interpretations when ambiguity exists instead of silently picking one, push back when a simpler approach exists, and stop and ask when something is unclear. This is the single biggest quality lever in the file. Most bad AI-generated code is not caused by the model being unable to write the right code — it is caused by the model confidently writing code for the wrong interpretation of the request. Forcing the interpretation into the open, before a single line is written, catches that failure at the cheapest possible moment.
2. Simplicity first
Write the minimum code that solves the problem, and nothing speculative. No features beyond what was asked, no abstractions for single-use code, no flexibility or configurability that nobody requested, no error handling for impossible scenarios. The file’s own test is one a senior engineer would recognise: if a senior engineer would say the code is overcomplicated, simplify it. In practice this is the principle that shrinks pull requests. Agents left to their own devices tend to build for imagined futures — a config layer for a value used once, a generic abstraction around two similar functions. This rule forbids that.
3. Surgical changes
Touch only what you must, and clean up only your own mess. The agent must not improve adjacent code, comments, or formatting, must not refactor things that are not broken, and must match existing style even if it would do things differently. If it notices unrelated dead code, it mentions it rather than deleting it. The one exception is its own mess: imports, variables, or functions that its own changes made unused should be removed. The test is simple — every changed line should trace directly to the user’s request. Anyone who has reviewed an AI pull request containing a surprise reformatting of an untouched file will immediately understand the value here.
4. Goal-driven execution
Define success criteria, then loop until they are verified. This principle captures Karpathy’s most-quoted insight: language models are exceptionally good at looping until they meet specific goals, so you should give them success criteria rather than step-by-step instructions and let them work. Instead of “add validation”, the task becomes “write tests for invalid inputs, then make them pass”. Instead of “fix the bug”, it becomes “write a test that reproduces it, then make it pass”. For multi-step tasks the agent states a brief plan where every step names its own verification check. Strong criteria let the model work independently; weak criteria, like “make it work”, force constant clarification.
What It Can Do for Your Team
Used consistently, the guide changes the shape of AI-assisted work in four measurable ways. First, diffs get smaller: only requested changes appear, so reviews get faster and reviewers stop hunting for unrelated edits buried in a pull request. Second, rewrites drop: code tends to be simple the first time, rather than needing a simplification pass after the agent has overbuilt. Third, clarifying questions arrive before implementation instead of after mistakes, which is far cheaper in both time and frustration. Fourth, pull requests become cleaner overall — no drive-by refactoring, no unsolicited improvements to neighbouring code.
There is a second, less obvious benefit. Because the guide is a plain text file, it is trivially customisable. The repository explicitly encourages merging it with project-specific instructions: a section on TypeScript strict mode, a rule that all API endpoints must have tests, or a note about the project’s existing error-handling patterns. The four principles are the shared baseline; your team’s conventions sit on top. That composability is why a single file can work across a solo side project and a production codebase — the file adapts by being edited, not by being configured.
The repository also ships a committed Cursor project rule, so the same guidelines apply when the project is opened in Cursor, not just in Claude Code. For teams where developers use different tools, that cross-tool reach is genuinely useful: one set of behavioural expectations, enforced wherever the agent runs.
How It Works: Installation and Daily Use
Installation is deliberately boring, which is a feature. For a new project, download the file into the project root:
curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md
For an existing project that already has a CLAUDE.md, append the guide to it rather than overwriting your existing instructions. The repository also documents installing it as a Claude Code plugin via the marketplace, which makes the guidelines available across all your projects at once — the better choice if you want the same behaviour everywhere without copying a file into every repo. Once installed, there is nothing to run. Claude Code reads CLAUDE.md automatically, and the principles apply to every subsequent session in that project.
Daily use requires one small adjustment to how you prompt. The guide works best when you give the agent goals and success criteria, not detailed instructions. “Add rate limiting to the checkout endpoint” becomes “checkout rejects requests over 100 per minute per IP with a 429, existing tests still pass, and a new test covers the limit”. That phrasing is what activates the goal-driven principle: the agent now has something verifiable to loop against, and you have something concrete to check in review.
Why It Is Trending Now
The timing is not accidental. AI coding tools crossed from novelty to daily driver for a huge number of developers during 2025 and 2026, and the pain shifted with them. The first wave of adoption was about whether the tools could produce working code at all. The second wave — the one we are in now — is about what that code costs to review, maintain, and trust. A tool that writes a thousand lines in a minute is not obviously a win if a senior engineer then spends an hour untangling what it did and why.
The guide also arrived with the right messenger. Karpathy is one of the few voices in AI whose observations about model behaviour carry weight with practitioners, because he has both built these systems and used them heavily. A set of guidelines explicitly derived from his diagnosis inherits that credibility. And the format helped it spread: a single file is easy to star, easy to fork, easy to try in one project in five minutes, and easy to recommend to a colleague. No sales page, no signup, no lock-in — just a file.
Finally, it solves a problem every team recognises but few have written down. Most teams using AI coding tools have an unwritten list of complaints — the bloated diffs, the silent assumptions, the drive-by refactors. This repository is that list, turned into instructions. That resonance is why it accumulated hundreds of thousands of stars in a short period, and why it keeps being forked: people are not just adopting it, they are adapting it.
From Our Experience: Where It Helps and Where It Bites
Having built production software with AI-assisted workflows for years, our honest assessment is that this guide fixes real problems — but it is a bias, not a cure-all, and biases have costs. The guide itself says so: it deliberately favours caution over speed. That trade is worth making on production code, on shared libraries, and on anything a client will maintain for years. It is a poor trade on a throwaway prototype, a spike, or a Friday-afternoon experiment, where the questions it forces the agent to ask will slow you down more than the bloat it prevents.
Three practical gotchas are worth knowing before you roll it out. First, the “think before coding” principle can turn into question fatigue: if your requests are routinely ambiguous, the agent will now ask about every ambiguity instead of guessing, and that is the point — but it means vague tickets get slower, not faster. The fix is on your side: write requests with the success criteria included, and the questions largely disappear. Second, “surgical changes” can frustrate developers who like the agent to tidy as it goes; if your team values opportunistic clean-up, agree on where that happens rather than letting the agent decide silently. Third, a CLAUDE.md file is only as good as its enforcement: nothing stops the model from drifting from the instructions on a long task, so the guide reduces bad behaviour, it does not eliminate the need for code review. Treat it as a better starting point for review, not a replacement for it.
One more honest limitation: the guide addresses how the agent behaves, not what it knows. It will not fix a model that misunderstands your domain, lacks context about your architecture, or hallucinates an API. Pair it with good project context — a README that explains the architecture, tests that encode real behaviour, and examples of the patterns you actually use — and the principles have something solid to work with. Without that context, you get a polite, minimal, surgically precise implementation of the wrong thing.
Getting Started in 15 Minutes
- Pick one active project, ideally one where AI-generated diffs have annoyed you recently.
- Download the CLAUDE.md file into the project root, or append it to your existing CLAUDE.md if you already have one.
- Add one short project-specific section: your stack’s strictness rules, your test command, and your error-handling convention.
- Give the agent a real task phrased as success criteria, not steps — for example, a bug with a reproduction test as the goal.
- Review the resulting diff against the four principles: is every changed line tied to your request, is the code minimal, and did questions come before code?
- If the diff looks better, roll the file out to your other active projects, or install it as a plugin for team-wide use.
If you want help wiring AI-assisted development into a real delivery workflow — CLAUDE.md conventions, review practices, and automation around them — our AI integration and automation team does this kind of work for clients every week, and our AI tools directory tracks the tools worth your team’s time. You can also talk to us about a specific project.
Frequently Asked Questions
Is the Karpathy Claude Code behaviour guide a plugin or a file?
At its core it is a single CLAUDE.md file. It can also be installed as a Claude Code plugin, which makes the same guidelines available across all projects, and the repository ships a Cursor rule for teams using Cursor. The file is the source of truth either way.
Does it work with tools other than Claude Code?
Yes, with a caveat. CLAUDE.md is a Claude Code convention, but the principles are plain-language behavioural instructions, and the repository includes a Cursor rule for that reason. Other agents that read project instruction files can use the same text, though you may need to place it in the file your tool actually reads.
Will it slow down AI coding?
On trivial tasks, yes, slightly — the guide explicitly biases toward caution over speed, and it will ask clarifying questions instead of guessing. On real production work, it usually saves time overall, because smaller, cleaner diffs are faster to review and cheaper to maintain than bloated ones.
Can I customise it for my project?
Absolutely, and you should. The guide is designed to be merged with project-specific instructions — your language strictness settings, test requirements, and error-handling patterns. Keep the four principles intact and add your conventions as an additional section.
Does it replace code review?
No. It improves the quality of what reaches review: smaller diffs, fewer surprises, clearer intent. Models can still drift from instructions on long tasks and can still misunderstand your domain. Review remains essential — the guide just makes review faster and more pleasant.
The best AI coding setup is not the one that writes the most code the fastest. It is the one whose output a senior engineer can review, trust, and maintain without dreading the diff. The Karpathy Claude Code behaviour guide earns its popularity because it targets exactly that standard, in a single file, for free. Try it in one project this week, judge it on the next three pull requests, and keep it only if the diffs genuinely get better — that is, fittingly, a goal-driven way to decide.