Four Rules in One File: The CLAUDE.md Behind 220,000 Stars

The most-starred AI coding project of 2026 contains no code. It is a single Markdown file with four headings, and as of today it has more than 220,000 stars on GitHub. Codebook Fusion’s essay “One Small Text File Got 91,000 GitHub Stars” tells the story well. This is our version: what the file actually says, why each rule earns its place, and how many hours of cleanup it is likely saving you.

Where the file came from

In January 2026, Andrej Karpathy described on X how his coding had flipped from mostly hand-written to mostly agent-written in a couple of months, and listed the ways the agents kept letting him down: wrong assumptions made without asking, bloated abstractions, edits to code nobody mentioned, and work declared done without proof. Within days, a repository called andrej-karpathy-skills turned those complaints into one CLAUDE.md. GitHub shows it was created on January 27, 2026.

One correction to the popular retelling: the fourth rule in the file is not “be honest about what you don’t know.” It is goal-driven execution: define success criteria and loop until they are verified. That matters, because it is the only rule that turns the other three from good manners into something you can check.

Why a file, and not a better prompt

The model does not learn from yesterday’s session. Every new session starts from the instructions it is given and the files it reads. Claude Code’s memory documentation describes the layering: a user-level file in ~/.claude/CLAUDE.md for every project, a project file committed with the repository, and folder-level files that load when the agent works in that folder. A personal CLAUDE.local.md holds preferences you do not want to share.

So a correction you make in chat is spent the moment the session ends. A correction you write into the file is paid once and collected every session after. That is the whole economic argument, and it is the same one behind Harness², the harness that rewrites itself.

Rule 1: Think before coding

What it says: state your assumptions, present competing interpretations instead of choosing silently, push back when there is a simpler path, and stop to ask when something is unclear.

Why it is pivotal: an unstated assumption is the most expensive kind of bug, because it is baked in at line two and only discovered at review. Every line written on top of it has to be read, doubted and often rewritten. One clarifying question costs seconds. The rewrite costs the session.

The headache it saves: the double-check tax. When you cannot tell which decisions the agent made on purpose, you have to verify all of them, and the time you meant to save disappears.

Rule 2: Simplicity first

What it says: the minimum code that solves the problem. No features beyond the request, no abstractions for single-use code, no configurability nobody asked for. “If you write 200 lines and it could be 50, rewrite it.”

Why it is pivotal: models are trained on a lot of framework code and reach for its patterns by default. Every unnecessary layer is a permanent maintenance cost and a reading cost for every future change, made by a human or an agent.

The headache it saves: spending longer understanding what the agent built than it would have taken to write it yourself.

Rule 3: Surgical changes

What it says: touch only what the task requires. Don’t improve neighbouring code, comments or formatting. Match existing style. Mention unrelated dead code instead of deleting it, and clean up only the orphans your own change created. The test: every changed line should trace to the request.

Why it is pivotal: review is the bottleneck in agent-assisted work, as we argued in More Agents, One Person Who Signs Off. A diff that mixes the fix with tidying multiplies the reading and, worse, the number of places a regression could hide.

The headache it saves: the slow retreat. After a few surprise edits, people stop letting the agent see the whole codebase and start pasting isolated snippets. At that point a capable agent has been demoted to autocomplete.

Rule 4: Goal-driven execution

What it says: turn tasks into verifiable goals. “Add validation” becomes “write tests for invalid inputs, then make them pass.” For multi-step work, state a short plan with a check for each step.

Why it is pivotal: it replaces “done” with evidence. It is also what lets an agent work for longer without you: strong success criteria let it loop on its own, while weak ones (“make it work”) need you to step in constantly. Anthropic’s guidance on harnesses for long-running agents makes the same point about verifying work before moving on.

The headache it saves: the confident wrong answer. Code that “should work” costs you a debugging session. Code that ships with the passing test costs you a glance.

How to write yours this afternoon

1. Start with what the project is, in one sentence. Stack and purpose, nothing else.
2. Give exact commands, not advice. pnpm test && pnpm lint, not “run the tests.”
3. Mine your corrections. Anything you have told the agent twice is a rule. Anything you have never had to say is noise.
4. Paste the four rules as the behaviour section, then cut what your stack makes irrelevant.
5. Keep it short. Every line is read every session and competes with the others for attention. The memory docs recommend concise, specific instructions; we keep ours well under 200 lines.
6. Promote what keeps getting ignored into a hook, which runs as code and cannot be skipped.

The same file works beyond Claude. AGENTS.md, which OpenAI introduced in August 2025 and which is now stewarded by the Linux Foundation’s Agentic AI Foundation, plays the same role for Codex, Cursor and other agents. Many teams keep one file and point the other at it.

Where the four rules stop

They are behaviour, not knowledge. They do not tell the agent your architecture, your data rules or what must never be touched. That is what the project-specific half of the file is for, and what the twelve parts of the agent harness cover: commands, permissions, hooks, subagents, skills and MCP connections. The four rules also bias toward caution; the file says so itself. For a one-line fix, judgment beats ceremony.

For the practice that surrounds the file, read spec-driven, maker-checker, governed scope and the longer loop engineering field guide.

Four rules went viral because everybody was already paying for their absence. Write them down once and stop paying.