Karpathy posted four notes about Claude Code. The CLAUDE.md they spawned has 110K GitHub stars.

Andrej Karpathy opened his X thread on January 26 with a line that has aged into a mantra. “I rapidly went from about 80% manual+autocomplete coding and 20% agents in November to 80% agent coding and 20% edits+touchups,” he wrote. The thread ran four posts. By morning it had three million views.

A day later a developer named Forrest Chang pushed a single file to a brand-new GitHub repo. It was 70 lines of markdown, named CLAUDE.md, derived almost verbatim from Karpathy’s four notes. It has not stopped trending since.

A 70-line file at 110,000 stars

forrestchang/andrej-karpathy-skills is, by file count, a smaller artifact than most CLI tools. It is one markdown file plus a few satellites: a CURSOR.md for Cursor users, an EXAMPLES.md, and a thin plugin directory. The README is shorter than this article. The reason that file matters is the thing it fixes: every developer using a coding agent has run into the same gallery of bugs Karpathy named, and nobody had a short, copy-pasteable contract for the agent until Chang wrote one.

Yet it now sits at roughly 110,000 stars on Chang’s personal account, with another 132,000 on an organization mirror at multica-ai/andrej-karpathy-skills. Tech Times put the combined total above 220,000 and noted the repo grew 5,828 stars in a single day on April 13, briefly the second most-starred project on GitHub that day. It has held the top weekly Trending slot for 28 consecutive weeks and ranks 94th globally by star count.

Karpathy did not write it. He has not publicly endorsed it. The repo carries his name because the content is a clean transcription of his observations, and he tagged Chang in a follow-up to confirm the attribution is accurate. The disproportion between code size and impact is unusual even for AI tooling: a 70-line markdown file outranks every agent framework, every IDE plugin, and most of the Python LLM libraries that ship a few hundred files apiece.

What the four rules actually say

The file reads like a stripped-down code-review checklist. Each rule has a one-line headline and a short bullet list. The four rules, in order:

1. Think Before Coding. “Don’t assume. Don’t hide confusion. Surface tradeoffs.” The agent should state assumptions explicitly, present multiple interpretations when ambiguous, and stop to ask when something is unclear instead of guessing.

2. Simplicity First. “Minimum code that solves the problem. Nothing speculative.” No features beyond what was asked. No abstractions for single-use code. No error handling for impossible scenarios. The file’s stress-test line: “If you write 200 lines and it could be 50, rewrite it.”

3. Surgical Changes. “Touch only what you must. Clean up only your own mess.” Don’t improve adjacent code. Don’t refactor things that aren’t broken. Match the existing style even if you’d do it differently. The test, quoted from the file: “Every changed line should trace directly to the user’s request.”

4. Goal-Driven Execution. “Define success criteria. Loop until verified.” Transform vague tasks into measurable goals. “Add validation” becomes “write tests for invalid inputs, then make them pass.” “Fix the bug” becomes “write a test that reproduces it, then make it pass.” Strong success criteria let the agent loop without constant clarification.

The file closes with a one-line working theory: it’s doing its job if diffs shrink, rewrites drop, and clarifying questions arrive before mistakes instead of after.

Why this took off, when “be concise” prompts didn’t

Engineers have written prompts asking Claude to be careful, terse, and surgical for as long as Claude has been writing code. They didn’t catch on. Chang’s file caught on because it does three things those one-shot prompts don’t.

It maps to a behavior that frustrates everyone equally. The single most common complaint about LLM coding agents, in the Hacker News discussion of Karpathy’s original thread, is that the model improves your code by default. Renaming a variable becomes a refactor; a one-line fix turns into a 200-line PR. Rule 3 names that failure mode and refuses it.

It loads into the right place. CLAUDE.md is the filename Claude Code reads on every session start, by convention. Cursor reads a .cursorrules or a project-root CURSOR.md. The viral file is the first widely-shared template that matches the loader’s expected filename instead of asking users to copy a long prompt into a system message.

It is short enough that the agent actually follows it. Karpathy’s note, paraphrased by Chang, says compliance starts dropping above 200 lines. The four-rule file lands at 70. Most people who paste it into a project get adherence in the high-80% range, by Chang’s own benchmark, where a 500-line “comprehensive” prompt gets ignored after the third bullet.

What Karpathy actually said

The X thread itself is more pointed than the markdown distillation. “I now mostly program in English,” Karpathy wrote, “somewhat awkwardly explaining to the LLM what code needs to be written, with words.” He called it “easily the biggest change to my basic coding workflow in 2 decades of programming” and said it “happened over the course of a few weeks.”

His specific failure modes are sharper, too. He listed agents that pile on speculative configurability the user didn’t ask for. Agents that “improve” code adjacent to the diff, breaking imports a junior would have left alone. Agents that pick one interpretation of a vague prompt and run with it, then write 400 lines of code committed to that wrong interpretation before surfacing the ambiguity. The HN thread is full of engineers describing the same gallery of bugs.

The four rules in CLAUDE.md are, more or less, the four most-cited failures from that thread compiled into something an agent can read on startup.

How developers are using it

The file is small enough to copy-paste, and most of the public uses we found do exactly that. A handful of patterns are common:

• Drop it in repo root as CLAUDE.md. Claude Code picks it up automatically; it merges with project-specific instructions you append below the four rules.
• Drop a copy as CURSOR.md or .cursorrules. Cursor, Aider, Cline, and Continue.dev have all adopted compatible filename conventions over the last six months; the four rules transfer cleanly.
• Lift the four headlines into a custom system prompt. Some teams paste only the four bolded one-liners into their internal agent’s system prompt because the elaboration below them eats too many tokens at scale.

The skeptical take, voiced loudest in the HN thread, is that the rules are common sense and the popularity says more about the state of AI tooling than about the file’s content. That’s probably true. It is also why it works: the rules are obvious in isolation, and not obvious to a coding agent trained on millions of pull requests where someone did improve the adjacent code.

What this means for you

If you’re using Claude Code or Cursor on a project that has accumulated even modest complexity, the four rules are worth pasting into your repo’s CLAUDE.md for a week and seeing what changes. The agreement we’ve seen from engineers who tried it is small but consistent: diffs get shorter, PRs touch fewer files, and the “agent introduced a subtle bug in code I never asked it to edit” frustration drops measurably.

The bigger point is that the file is a forcing function on how you write tickets. Rule 4 asks you to convert “fix the bug” into “write a test that reproduces it, then make it pass.” If your team’s tickets routinely read “fix the bug,” the agent’s failures are downstream of the prompt, not the model. The file makes that legible. That’s a thing a 70-line markdown can be, apparently, worth 110,000 stars.