225,000 Stars for One Markdown File: Karpathy's Complaints Became Four Rules.

A repository containing a single markdown file has 225,000 stars. It gained about 4,000 more this week. There is no code in it, no build step, no release, no benchmark table — just four principles and a set of instructions about how a language model should behave when asked to change a codebase.

The file is CLAUDE.md, in a repo called andrej-karpathy-skills, maintained by forrestchang. It compresses a set of complaints Andrej Karpathy made about LLM coding behavior into something an agent will actually read at the start of every session. The star count is the interesting data point, not the content, because it suggests something about how agent behavior is currently being patched: unofficially, in prose, by individuals.

The complaints, in Karpathy's words

Three quotes from the original post that the repo is built on:

"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."

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."

Anyone who has shipped agent-written code recognizes all three. The second one is the most common: ask for a validation function, receive an abstract base class, a strategy pattern, a config object, and forty lines of error handling for states that cannot occur.

What the four principles actually say

Think before coding. State assumptions explicitly, present multiple interpretations instead of silently picking one, push back when a simpler approach exists, stop when confused and name what's unclear.

Simplicity first. Minimum code that solves the problem. No features beyond the ask, no abstractions for single-use code, no configurability nobody requested, no error handling for impossible scenarios. The test: would a senior engineer call this overcomplicated?

Surgical changes. Touch only what you must. Don't improve adjacent code or reformat what you're passing through. Match the existing style even if you'd do it differently. If you notice unrelated dead code, mention it — don't delete it. When your changes create orphans, clean up only those. The test: every changed line traces to the request.

Goal-driven execution. Convert imperative instructions into verifiable success criteria. Not "add validation" but "write tests for invalid inputs, then make them pass." Not "fix the bug" but "write a test that reproduces it, then make it pass."

That last one is the only principle that isn't a restraint. It's leverage, and it comes with the best line in the source material: LLMs are exceptionally good at looping until they meet specific goals. Don't tell it what to do; give it success criteria and watch it go.

Install, and the fact that it's two lines

Two routes, both trivial.

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

Or, per project:

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

There's a committed Cursor rule at .cursor/rules/karpathy-guidelines.mdc so the same guidance applies when the project opens in Cursor instead. MIT licensed.

The distribution story is the point. Two years ago, fixing "models overengineer" would have meant a fine-tune, a system prompt shipped by a vendor, or a framework. Now it's a file that a user drops into a repo, and a marketplace listing that puts it in every project on that machine. That's a much shorter feedback loop between a complaint and a fix, and it's why the star count is what it is — the file is the cheapest possible unit of behavior change.

Why I'm skeptical of the framing anyway

Three reservations, offered in the spirit of the file itself.

Principles aren't tests. "Simplicity first" is a preference, not a criterion. An agent reading it will still produce a 300-line solution when 80 would do, because the model has no way to measure complexity. The one principle in the file that actually works — goal-driven execution — works precisely because it replaces a preference with a check: a test that either passes or doesn't.

"Surgical changes" fights the thing agents are good at. If you ask a model for a small edit and it makes a small edit, you've used an expensive tool to save keystrokes. The value of an agent is that it can restructure something you didn't want to touch. The file's answer is that restructuring should be requested, not volunteered — reasonable, but it means the guidelines are optimizing for a specific kind of user: one with an existing codebase and a strong opinion about diffs.

Nobody measures whether it works. The repo lists signals: fewer unnecessary changes in diffs, fewer rewrites, clarifying questions before implementation rather than after. Those are real and observable. But there's no control condition. You installed a file that says "ask before assuming," and now the agent asks before assuming. Did the file cause that, or did the act of writing it down make you notice behavior that was already there?

The author is upfront about the tradeoff, which is to their credit: the guidelines bias toward caution over speed, and for trivial tasks you should use judgment. That's the correct caveat and it's also the tension. An agent that stops to ask about a one-line typo fix is worse than an agent that fixes it.

The version of this I'd actually write

If the file's weakness is that three of its four principles are preferences, the fix is to convert them into checks. Concretely, four lines that survive contact with a real repo:

Before editing, list the files you intend to touch and stop if the list is longer than the request implies. That operationalizes "surgical changes" as a gate rather than a mood.

Before finishing, run the tests and paste the output. That's "goal-driven execution" made non-negotiable, and it's the single highest-leverage instruction you can put in front of an agent.

If a task has more than one plausible interpretation, write both and ask which. That converts "think before coding" from an aspiration into a turn in the conversation.

And a diff budget: if the change adds more than roughly 150 lines for a bug fix, stop and justify each abstraction. Crude, but it catches the failure mode Karpathy described, which is the one that actually costs time.

None of that is in the file, and it doesn't need to be. The file's job is to set a posture. The checks are the job of whoever owns the repo.

What the star count is really saying

Most of the agent tooling released this year is about capability: longer context, more tools, parallel execution. This file is about restraint, and it got more attention than most capability releases.

That gap is informative. The people paying for these tools have concluded that the bottleneck is no longer what the model can do — it's getting it to stop doing things they didn't ask for. A 225,000-star markdown file is an unusually clear signal about where the frustration actually is.

It's also a slightly embarrassing signal for the labs. The most-starred repository in this category is a list of four things the models should already be doing.