I went looking for Andrej Karpathy's CLAUDE.md file last week. Not the famous one. The actual one. The one he uses on his own projects.

It lives in his llm-council repo on GitHub. It is, by any honest reading, boring. Port numbers. Architecture notes. The kind of file you'd expect from someone documenting a side project so they don't forget what they did. There is no philosophy in it. There are no commandments. There is no "Don't assume. Don't hide confusion." There is a list of services and which ports they run on.

Meanwhile, on a different GitHub repo titled andrej-karpathy-skills, there is another CLAUDE.md. This one has roughly 220,000 stars across its mirrors. It briefly hit #2 on GitHub Trending in April. It opens with "Think Before Coding" and proceeds through three more imperatives: Simplicity First, Surgical Changes, Goal-Driven Execution. It reads like a vow.

Andrej Karpathy didn't write it.

It was written by Forrest Chang, one day after Karpathy posted a thread on X about coding with Claude. Chang named the repo after Karpathy. The repo became viral because of the name. Karpathy has not, to my knowledge, endorsed it.

This is the actual story. Not the file. The fact that someone made it within 24 hours, named it after a person who didn't write it, and the community decided that was close enough to true.

Reading the file honestly

I read it. It is fine. Most of its rules are conventional wisdom from Clean Code (2008) and a hundred software engineering blog posts since. "Match existing style, even if you'd do it differently" is good advice that has been good advice for decades. "Every changed line should trace directly to the user's request" is a clean restatement of the unit-of-work principle. None of this is bad. None of this is new.

What's new is the form. It's written as a commandment tablet. Imperative voice. No qualifiers. Almost monastic. This is not how engineers usually write to each other. It is how someone writes when they have given up on negotiation and want to issue rules.

The 220,000 stars are not a referendum on the technical content. They are a referendum on how exhausted developers are with agents that over-engineer, over-explain, and over-deliver. The community didn't want Karpathy's actual file (which is boring because his actual problems are specific). The community wanted a Karpathy-shaped commandment tablet. Someone built one in a day. Everyone agreed it was probably right.

Two critiques worth taking seriously

Alex Rusin pointed out the obvious technical limitation: CLAUDE.md files instruct LLMs probabilistically, not deterministically. The file nudges the agent's behaviour. It does not enforce it. So the file works at the margin, not at the root. The actual root is in RLHF reward signals and agent-loop design, neither of which a text file can patch.

The Mastering Product HQ critique was sharper. The file fixes code-level mistakes. It doesn't touch the bigger one: shipping the wrong thing, well. A beautifully implemented feature for a problem that doesn't matter. No CLAUDE.md commandment will catch that. Problem framing, scope, instrumentation, decision logging, these are product-level concerns that live outside the agent's editing window.

What changed when I tried it

I used the file for a week on a small Next.js refactor. It changed the agent's behaviour in two ways I noticed.

First, the agent stopped offering me alternatives I hadn't asked for. Before: "I've done X; would you also like me to add tests / extract this into a function / add error handling?" After: silence, until I asked. This was a meaningful win.

Second, the agent's edits got smaller. Not always shorter, but more localised. Less "while I was in here, I also fixed..." This is what "Surgical Changes" buys you in practice.

What didn't change: the deeper failure modes. The agent still occasionally misread my intent and built the wrong thing well. No commandment fixes that. Only better question-asking does, and the file's "surface tradeoffs" rule helps the agent surface tradeoffs after deciding, which is the wrong moment.

What the stars are actually saying

So: yes, install it. It will help. It will not solve the problem. The fact that 220,000 of us are clinging to it like scripture is the more interesting datapoint.

The actual lesson is not in the file. The actual lesson is that we collectively want our AI tools to behave with restraint, and the only way to ask for that right now is to invoke the name of someone who built nanoGPT in his spare time and pretend his name is on a sufficient solution.

It isn't. But it is a vow, and right now the vow is what we needed.