The Karpathy Guidelines: Four Rules That Stop Agents Going Sideways

There is a specific kind of pain that everyone who has used a coding agent for more than a week knows intimately. You ask for a small change. The agent rewrites three files you didn't mention, introduces an abstraction layer "for flexibility," renames a function for clarity, and then — having drifted far from the original request — declares victory. The diff is four hundred lines. The bug you actually wanted fixed is still there, buried under refactors nobody asked for.

The Karpathy guidelines are a single short file that exists to prevent exactly this. At the time of writing it sits at roughly 174,000 stars, which is an absurd number for what is essentially one Markdown document of behavioral rules. No build system. No agent framework. No clever orchestration. Just four ideas, written down, dropped into your project so the agent reads them before it starts working.

I want to be precise about what this is and what it isn't, because the name causes confusion and the star count causes hype, and I promised you neither.

What this actually is (and the name confusion)

Let's clear up the most common misconception first: Andrej Karpathy did not write this file. The name is a tribute, not authorship.

The lineage is this. In January, Karpathy posted publicly about the recurring ways LLM coding agents fail — the over-eagerness, the unrequested rewrites, the loss of focus, the tendency to add complexity instead of removing it. He wasn't shipping a product. He was naming failure modes that anyone who works with these tools recognizes immediately. The community took that diagnosis and turned it into a prescription: a concrete behavioral file that tells the agent how not to do those things. The repo later moved to the multica-ai org, where it lives today.

So "the Karpathy guidelines" is community-built, derived from his observations, carrying his name out of respect. That matters for how you should treat it. This isn't gospel handed down from an authority. It's a crowd-sourced distillation of hard-won pain, which is honestly a more useful thing. It earned its stars by being recognizable — every developer who reads it nods along, because they've lived every failure it describes.

The file itself is a CLAUDE.md (you can equally name it AGENTS.md, or load it as a Skill). The whole thing fits comfortably on one screen. Installing it is a single command:

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

That's the entire setup. No dependencies, no configuration, no opt-in flags. The agent reads it on session start and adjusts its behavior accordingly. This radical simplicity is the point, and it's why I recommend it as a starting place.

The four rules, and why they exist

Strip away the prose and the file comes down to four ideas. I'll expand each one, but here is the shape of the whole thing:

Rule	What it asks for	Failure mode it prevents
Think before coding	Plan, ask, understand the goal first	Confident code that solves the wrong problem
Keep it simple	Prefer the boring, minimal solution	Premature abstraction, framework sprawl
Make surgical changes	Touch only what the task requires	400-line diffs for a 4-line fix
Stay focused on the goal	Don't wander into adjacent "improvements"	Scope creep, drive-by refactors

None of these is clever. That's deliberate. The reason agents fail isn't that they lack sophisticated reasoning — it's that, left unconstrained, they optimize for appearing helpful rather than being correct and minimal. These four rules are guardrails against eagerness. Let's take them one at a time.

Rule 1: Think before coding

The single most expensive habit a coding agent has is jumping straight to a solution before it understands the problem. It reads your request, pattern-matches to something it has seen a thousand times, and starts typing. Sometimes that's fine. Often it's solving an adjacent problem that merely resembles yours.

The rule asks the agent to pause and do three things before writing any code:

1. Restate the goal in its own words. If the agent can't articulate what you actually want, it doesn't understand it yet. This catches misreadings early, when they're cheap.
2. Identify what it doesn't know. Which file holds the relevant logic? What's the existing pattern for this kind of change? Are there constraints — a database schema, an API contract, a style convention — that bound the solution?
3. Propose an approach, briefly, before committing to it. Not a thousand-word design doc. One or two sentences: "I'll add a guard clause in validateUser and a test for the empty-email case. Sound right?"

The failure mode it prevents

Here's a concrete example I see constantly. You ask: "The signup form lets people through with an empty email — fix it." An agent that doesn't think first might add client-side validation in the React component and call it done. But the real bug is server-side: the API endpoint accepts the empty string, and the client validation can be bypassed with a direct POST. An agent that thinks first asks where validation should live, discovers the server is the source of truth, and fixes it there.

The cost of a wrong assumption compounds. A misread caught during planning costs one sentence. The same misread caught after the agent has written code, run tests, and explained its work costs a full revision cycle — and your trust.

The practical version of this rule, written for the agent, is something like: Before writing code, state the goal in one sentence and your plan in one or two more. If anything is ambiguous, ask rather than guess. That last clause is doing a lot of work. The instinct of an unconstrained agent is to resolve ambiguity by picking the most common interpretation and barreling ahead. You want it to surface the ambiguity instead.

There's a tension here worth naming. "Think before coding" can curdle into "produce a giant plan for a trivial task," which is its own kind of waste. The guideline isn't asking for ceremony. It's asking for a beat of reflection proportional to the task. A one-line fix needs one line of thought. A new subsystem needs more. Calibration is the skill.

Rule 2: Keep it simple

If I had to pick the rule that pays for the whole file, it's this one. LLMs are trained on a corpus that overrepresents "impressive" code — design patterns, abstractions, configurability, enterprise architecture. So their default register is more complex than your problem warrants. Left alone, an agent will reach for a factory when you needed a function, a strategy pattern when you needed an if, a config option when you needed a constant.

Keeping it simple means: solve the problem in front of you, not the problem you imagine you might have later.

Concretely, the rule pushes the agent toward:

• The fewest moving parts that work. No new dependency if the standard library does it. No new abstraction until there are at least two or three real callers that need it.
• Boring, readable code over clever code. The next person to read this — possibly you, in three months — should understand it without effort.
• Deleting before adding. If a change can be made by removing code rather than adding it, prefer that.
• No speculative generality. "We might need to support other providers someday" is not a reason to build a provider abstraction today. Build it when the second provider actually arrives.

The failure mode it prevents

You ask for a function that formats a date as YYYY-MM-DD. The over-engineered response gives you a DateFormatter class with a configurable locale, a strategy for different output formats, an options object, and a factory method. What you needed was:

def format_date(d):
    return d.strftime("%Y-%m-%d")

Three lines, zero abstractions, impossible to misuse. The class version isn't wrong, exactly — it's premature. It pays the cost of flexibility now for a flexibility you may never use, and every future reader has to understand the machinery before they can trust the output.

The discipline this rule encodes is sometimes called YAGNI — "you aren't gonna need it." Agents are particularly prone to violating it because adding flexibility feels like good engineering, and the model has seen a lot of code where flexibility was the right call. The guideline's job is to bias the default the other way: assume you don't need it until proven otherwise.

One caution: "keep it simple" is not "keep it sloppy." Simple code still has error handling, still has tests, still names things well. Simplicity is about minimizing incidental complexity — the complexity you introduce — not about skipping the work. A simple solution to a genuinely hard problem is the highest form of the craft. This rule is asking the agent to do that work, not to dodge it.

Rule 3: Make surgical changes

This rule is about the diff. When you ask for a change, the agent should change as little as possible to accomplish it. The metaphor is surgery: you go in through the smallest incision, fix the specific thing, and leave everything else untouched.

What surgical means in practice:

• Touch only the files and lines the task requires. If the task is "fix the empty-email bug," the diff should be about empty emails. Not about reformatting the file, not about renaming variables you happened to dislike, not about upgrading a dependency you noticed was old.
• No drive-by reformatting. Reformatting an entire file to fix one line buries the real change in noise and makes the diff unreviewable. If the formatting genuinely needs fixing, that's a separate change with its own commit.
• Preserve existing style. Match the conventions already in the file — naming, indentation, error-handling patterns — even if you'd personally do it differently. Consistency with the surroundings beats your local preference.
• One logical change per pass. If the work naturally splits into "fix the bug" and "refactor the surrounding code," do them as separate, reviewable steps, not one tangled diff.

The failure mode it prevents

The classic. You ask to fix a four-line bug. The agent fixes it — and also reorganizes the imports, switches the file from var to const, extracts a helper function, and adds JSDoc comments to neighboring functions. Now your four-line fix is a two-hundred-line diff. When you go to review it, you can't tell the load-bearing change from the cosmetic churn. You either rubber-stamp it (dangerous) or spend twenty minutes untangling it (annoying). Both outcomes are worse than the four-line version.

A reviewer's trust is a budget. Every line of unrequested change spends it. A surgical diff that does exactly what was asked gets approved in seconds. A sprawling diff full of "while I was in there" changes gets scrutinized line by line — and the scrutiny is your time, not the agent's.

There's a deeper reason surgical changes matter for agents specifically: a small diff is a verifiable diff. When the change is minimal, you can actually read it and confirm it's correct. When it's sprawling, you lose the ability to verify, which means you've lost the main safety mechanism you had. Surgical changes keep the human in control.

This rule also makes git blame and git bisect actually work. When each commit is a focused change, your history is a usable record. When commits mix bug fixes with reformatting, the history becomes archaeological mud — you can't tell when a behavior changed because the signal is buried in noise.

Rule 4: Stay focused on the goal

The last rule is about attention over the course of a task. Agents drift. They start on the requested work, notice something adjacent that could be improved, wander over to improve it, notice something adjacent to that, and three steps later they're refactoring a module that has nothing to do with what you asked. Each individual step seemed reasonable. The cumulative result is that the original goal never got finished and you have a pile of half-done tangents.

Staying focused means:

• Finish the requested task before doing anything else. The thing you were asked to do is the thing you do. Adjacent improvements wait.
• Note tangents instead of chasing them. If the agent spots a real problem along the way — a genuine bug, a security issue, a confusing name — the right move is to mention it, not to fix it mid-task. "I noticed the adjacent parseConfig function has a similar bug; want me to fix that separately after this?" That respects your priorities and keeps the current change clean.
• Resist the "while I'm here" impulse. This is the specific instinct that produces scope creep. It feels efficient — "I'm already in this file, I might as well" — but it's the mechanism by which simple tasks metastasize.
• Reconnect to the goal when uncertain. If the agent isn't sure whether some piece of work is in scope, the tiebreaker is: does this directly serve the stated goal? If not, defer it.

The failure mode it prevents

You ask the agent to add a loading spinner to one button. Forty minutes later it has built a global loading-state context, refactored every async call in the app to use it, added spinners to twelve buttons you didn't mention, and broken two of them. The original button still doesn't have its spinner because the agent never circled back. Every step was "helpful." The net result is a mess and an unfinished task.

Focus is what turns a capable agent into a reliable one. Capability without focus produces impressive tangents. Capability with focus produces finished work. For day-to-day development, finished-and-boring beats impressive-and-incomplete every single time.

When four rules are enough — and when they aren't

I'd be doing you a disservice if I oversold this. The honest truth is that some people find the Karpathy guidelines marginal in practice. The reason is that modern frontier models already lean toward some of these behaviors, so on a strong model the file sometimes feels like it's restating instincts the model already has. That's a fair critique, and you should test it for yourself rather than take the star count as proof.

So let me give you a clear decision framework.

Four rules are enough when:

• You're working solo or in a small project where you can review every diff yourself.
• Your tasks are mostly bounded — fix this, add that, adjust this — rather than large multi-step features.
• You want a low-commitment behavioral baseline you fully understand, with no machinery to maintain.
• You're new to agentic coding and want to feel the difference a good CLAUDE.md makes before investing in anything heavier.

You need a full workflow when:

• Tasks span many files and require a real plan-then-execute loop with checkpoints.
• You want persistent context, structured spec documents, verification gates, or multi-agent orchestration.
• You're building something where the cost of an unreviewed mistake is high and you need process, not just behavioral nudges.
• You're collaborating with a team and need shared, enforceable conventions rather than gentle guidance.

This is the genuine difference between the Karpathy guidelines and a heavyweight system like Superpowers. Superpowers is a full methodology — phases, verification, structured artifacts. The Karpathy guidelines are four sentences of behavioral steering. One is a process; the other is a posture. If full workflows feel like too much right now, the guidelines are the right starting point. You can always graduate. And the two aren't mutually exclusive — the four rules are a fine foundation to keep even after you layer a real workflow on top.

The way I'd put it: the Karpathy guidelines are the lowest-effort thing that might help. That's exactly their value. The cost of trying them is one curl command, and the cost of removing them is deleting a file. At that price, you should just try it.

How to adapt this into your own AGENTS.md

The real payoff isn't installing the file verbatim — it's understanding the four rules well enough to fold them into your own project's CLAUDE.md or AGENTS.md, tailored to how you actually work. Here's how I'd approach that.

Start by reading the file and keeping what resonates. Don't adopt rules you don't believe. If "keep it simple" matters most to your codebase and the others feel obvious, keep that one and write it in your own words. A rule you understand and endorse will shape behavior more than a rule you copied because it had stars.

Make the rules concrete to your stack. Generic "make surgical changes" is good; "match the existing error-handling pattern — we use Result types, not exceptions" is better. The more your rules reference the actual conventions, files, and patterns of your project, the more they steer. Abstract rules get ignored; specific ones get followed.

Add your project's non-negotiables. The four rules are about how to work. Your AGENTS.md should also encode what's true about your project: where things live, which commands to run, what's off-limits. Pair the behavioral rules with concrete facts and you get a file that's far more useful than either alone.

Keep it short. The reason this file works is that it's readable in one pass and the agent actually absorbs it. A bloated AGENTS.md of two hundred rules gets skimmed and ignored. Ruthlessly cut anything that isn't earning its place. If a rule hasn't changed agent behavior in a month, delete it.

Iterate from real failures. The best rules come from watching your agent fail and writing down the rule that would have prevented it. When an agent does something you didn't want, don't just fix the output — add one sentence to your AGENTS.md so it doesn't happen again. Over a few weeks this turns into a file that's precisely shaped to your pain, which is worth far more than any file you downloaded.

If you want to go deeper on the broader practice of shaping agent behavior through these files, my write-up on context engineering covers the full picture — what to put in, what to leave out, and why context quality beats context quantity. And if you want the agent to interrogate you before it starts — a natural companion to "think before coding" — look at grill-me, which flips the dynamic so the agent asks the questions.

A worked example: the same task, two agents

Let me make all of this concrete with one scenario, run two ways.

The request: "Users can submit the contact form with an empty message. Stop that."

Agent without the guidelines: Opens the form component. Adds client-side validation. Notices the form's styling is inconsistent and fixes it. Decides to extract the form into a reusable component "for the future." Adds a validation library as a dependency. Refactors the submit handler to be async/await instead of promises. Submits a 250-line diff. The empty-message bug is fixed on the client but still passes server-side. You spend fifteen minutes reviewing, find the server gap, and send it back.

Agent with the guidelines: Restates the goal: "Prevent empty-message contact form submissions." Asks one question: "Should this be enforced server-side, client-side, or both?" You say both. It adds a guard in the API handler (the source of truth) and a matching client-side check for UX. The diff is twelve lines across two files, matches existing patterns, and includes a test for the empty case. It notes: "I saw the form styling is inconsistent — want me to clean that up separately?" You approve in thirty seconds.

Same model, same task. The difference is four rules and the discipline to follow them. That's the entire pitch, and it's an honest one: a small, cheap, removable file that nudges behavior toward finished, reviewable, focused work. Sometimes it's a small difference. Sometimes — on a long task with an eager model — it's the difference between a good afternoon and a wasted one.

Resources & links

External:

• The repo — multica-ai/andrej-karpathy-skills — the file itself, ~174k stars, with the CLAUDE.md you can install directly.
• Install command — curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md — drop it into any project root.
• Anthropic's CLAUDE.md / memory docs — docs.claude.com on memory and CLAUDE.md — the official reference for how these files are loaded.
• AGENTS.md convention — agents.md — the cross-tool standard for agent instruction files, if you want a portable version.

Internal — go deeper:

• Context engineering — the broader craft of shaping agent behavior through what you put in (and leave out of) these files.
• Grill-me — the natural companion to "think before coding": make the agent interrogate you before it writes anything.
• Superpowers — the heavyweight alternative when four rules aren't enough and you need a real workflow.
• The most popular AI coding skills — where the Karpathy guidelines sit in the wider landscape.
• Spec-driven development with AI agents — the next step up in process if you outgrow behavioral nudges.
• The complete prompt engineering guide for 2026 — the foundations under all of this.
• Prompt engineering track — start here if you want the structured path through all of it.