One Markdown File, 188,000 Stars: CLAUDE.md, from Your Kitchen to Karpathy's

On January 27, 2026, a repository appeared on GitHub containing, essentially, one markdown file. Six months later it sits at roughly 188,000 stars — more than most programming languages, editors, and frameworks have collected in their entire lives. No code. No demo. A text file about how to talk to a coding agent.

The file is a CLAUDE.md, and if that name rings a bell, it's because we put one on the fridge in the previous recipe. Today we go deeper: what this file really is, what Andrej Karpathy — the person who coined vibe coding — keeps in his own, and why a distilled version of his complaints became one of the most-starred things on the internet.

The 60-second recap

CLAUDE.md is a plain markdown file in your project root. Claude Code reads it automatically, at the start of every session. That's the entire mechanism — and it's the difference between an agent that wakes up with amnesia every morning and one that walks in already knowing where the knives are.

Two details people miss:

• It stacks. A personal ~/.claude/CLAUDE.md applies to everything you cook; the project's CLAUDE.md travels with the repo so your teammates' agents learn the same rules; a gitignored CLAUDE.local.md holds notes just for you.
• It's context, not law. Claude follows it the way a cook follows kitchen notes: reliably when they're specific ("run npm test before committing"), loosely when they're vague ("test your changes"). Write instructions you could verify at a glance.

Flavor one: the recipe card — Karpathy's actual CLAUDE.md

Karpathy ships CLAUDE.md files in his own projects. His llm-council repo — a 22k-star experiment where several LLMs answer a question, rank each other's answers anonymously, and a "chairman" model synthesizes the result — carries one, and it is magnificently boring. It contains things like:

• The architecture in a few lines: three stages, which module does what, where responses are stored.
• The exact way to start the backend: python -m backend.main from the project root — not from inside backend/, which looks equally plausible and doesn't work.
• The one string the whole pipeline depends on: rankings must carry a strict FINAL RANKING: header, because a parser downstream matches on it.
• What's ephemeral: some metadata never touches storage, so don't go looking for it there.

Notice what this is: facts the code cannot say about itself. Nothing in backend/main.py announces that running it the wrong way breaks imports. No function signature warns that a friendly rewording of FINAL RANKING: silently kills stage two. Karpathy could re-derive every one of these details from memory — he wrote them down so the agent doesn't have to, and doesn't get them wrong.

That's flavor one: the laminated recipe card taped inside the cabinet. Project facts, commands, landmines.

Flavor two: the house rules — the 188k-star file

The viral repo, andrej-karpathy-skills, is not by Karpathy. It's a developer distilling, into one reusable CLAUDE.md, the pitfalls Karpathy described after months of heavy agent-driven coding: models that make wrong assumptions on your behalf and run with them, that overcomplicate code and bloat abstractions, that leave dead code lying around — but that are exceptionally good at looping toward a goal if you hand them concrete success criteria.

The file turns those observations into four house rules:

1. Think before coding. Surface your assumptions; if the request has two readings, ask — don't pick one silently.
2. Simplicity first. Build exactly what was asked. No speculative features, no abstraction for code used once.
3. Surgical changes. Touch only what the task requires. Don't reformat the neighborhood while fixing one faucet.
4. Goal-driven execution. Define verifiable success criteria up front, then loop until they pass.

Read them again and you'll notice why 188,000 people hit the star button: it's every frustration you've ever had with a coding agent, inverted into instructions. This is flavor two — not facts about a project, but rules about behavior, portable to any kitchen.

Cook your own

The best CLAUDE.md files mix both flavors. The recipe:

1. Let Claude draft it. Run /init in your project — Claude reads the codebase and writes the first version itself.
2. Add the three fact groups the draft can't know: the commands that actually work, the architecture decisions you made on purpose, and the gotchas that once cost you an afternoon.
3. Add rules only when they're earned. The moment Claude makes the same mistake twice, that's a line in CLAUDE.md. That's the whole discipline.
4. Be concrete. "Use 2-space indentation" beats "format code properly." If you can't verify a rule at a glance, the agent can't follow it reliably.
5. Keep it lean — under ~200 lines. The file is loaded into every single session; every line spends context budget forever.
6. Steal. The karpathy-skills file is MIT-licensed. Start from its four rules and season to taste.

Full details on locations, imports, and troubleshooting live in the official memory docs.

Order up

One last thing, for flavor: the kitchen you're standing in practices what it preaches. This blog is built and maintained by Claude Code, and as of this week it has its own CLAUDE.md — deploy commands, a warning about which environment variable dies silently, and the pixel-tight rules of the mobile nav. The agent that publishes these posts reads that file before every shift.

Want yours started tonight? Paste this into Claude Code (or any coding agent) inside your project:

Read this project and write a CLAUDE.md for it.

Include:
1. A one-paragraph summary of what this project is.
2. The exact commands to run, test, and deploy it.
3. Architecture facts an agent could plausibly get wrong — versions, where things live, what talks to what.
4. Gotchas: things that look normal but break, and what breaks when they do.

Rules: under 100 lines. Every instruction specific enough to verify at a glance.
Don't invent anything you didn't see in the repo — list open questions for me instead.

Tape it to the fridge. Your next session starts smarter than this one.