Sumit Pandey dissected a phenomenon that is hard to walk past: a single CLAUDE.md file from the andrej-karpathy-skills repository collected roughly 91,000 stars on GitHub without a line of code — four behavioral rules distilled from Karpathy's observations. "Think before coding," "simplicity first," "surgical changes," "goal-driven execution." Pandey makes a precise diagnosis and closes with the line that made the piece loud: «it is winning because it is not a layer. It is a contract». I run a large, layered CLAUDE.md on top of machine context-routing — and that is exactly why I want to argue with that thesis. Not to refute it. To pin down the boundary past which it stops holding.
My thesis: he is right for the median, but "contract" and "layer" are not opposites — they are two points on one scale
Pandey is right about the main thing: for the median user a flat file of four rules is not simplicity born of poverty but earned simplicity. Most projects should start exactly that way. But I would rotate his metaphor. "Contract" and "layer" are not opposites you must choose between. The flat file is a contract precisely as long as a single sheet of rules suffices to express every obligation. Layers (my three-axis routing is an already-published story, and I will not retell it here) are not an abandonment of the contract but earned complexity you pay for exactly once: when you acquire a problem the flat file is physically unable to write down without contradiction. Before that moment, layers are noise. After it, the flat file itself becomes the noise, and its rules rot.
Where he is right: the four rules close a real gap, and the virality is a vote for the problem
The strongest part of the piece is not the rules themselves but the honesty about why they are needed. Pandey describes his own failures verbatim: an agent bolted dependency injection and a class with eight methods onto a three-line cache; another agent, fixing date parsing, «reformatted the entire file» and rewrote non-adjacent functions. I recognize every line — this is not exotic, it is the default. The rules are obvious to a senior engineer and not obvious to the model; that is exactly the gap the file closes. And Pandey reads the virality correctly: 91,000 stars are «not a vote on the file. It is a vote on the problem». Silent assumptions, overcomplexity, scope creep — the three walls everyone who works seriously with agents hits. The file names them in plain language and installs in thirty seconds. I agree fully: the barrier to entry decides, and for most people this is the right first and only step.
Where he is incomplete: "improves the distribution of behavior" is itself the fault line
The most important sentence in the piece is not the loud one but the quiet one in the caveats: the file «improves the distribution of behavior. It does not guarantee specific behavior». Pandey honestly puts it on the table and moves on. I stop on it, because this is the seam that decides what you can even write into a CLAUDE.md.
A markdown instruction is a probabilistic bias, not a guarantee. For soft preferences that is enough: naming style, framework choice, test policy, "do not refactor neighboring code." If the model violates the style one time in twenty, I will survive — review will catch it. But there is a class of rules for which "improved distribution" is a failure, not a success. Compliance and production safety cannot be expressed as a preference. A precedent a prompt cannot honestly write down: "for remotes of the form github.com/OEM-WEB/*, commits and PRs must not contain the Co-Authored-By: Claude trailer." A flat behavioral file can ask for this. It cannot guarantee it — because a prose instruction is by definition non-binding, and a client's legal requirement does not divide into "improved distribution."
Hence my hard line in authoring. Soft preferences live in markdown — that is where they belong, and the flat file is enough there for almost everyone. Compliance and prod-safety I mechanize: remote detection before a commit, a named-approval gate before actions against production, injection of the needed context by a hook at session start. Not because I love layers — I do not, they cost maintenance. But because a prompt is unenforceable by nature, and the only way to turn "asked" into "guaranteed" is to lift the rule out of prose into an executable mechanism. This is exactly the case where Pandey's "contract-as-text" breaks and must yield to "contract-as-harness."
What to do about it: start flat, layer only when scale forces it
From this comes the rule by which I would build a CLAUDE.md today — and it almost always returns the answer "stay flat."
Start with a flat file. Pandey's four rules plus your project conventions — naming, framework, tests. That is a contract, and for one project in one organization it is self-sufficient. Do not build routing you have no reason to build.
Do not layer by taste — layer on a tripwire. So that this is not a hedge, you need a falsifiable threshold. My trigger for layers fires when at least one holds: (a) you have two or more organizations with conflicting compliance rules that the flat file cannot record without self-contradiction; or (b) a rule has appeared that must be guaranteed, not asked — that is, a violation costs not a review but an incident. Until one of the thresholds fires, the flat file is strictly better. Layers added earlier are complexity you pay for without the problem it solves.
Separate what you ask from what you guarantee. Before adding a line to CLAUDE.md, ask: is this a preference or an obligation? A preference goes into markdown, and thanks to Pandey for showing how little it takes. An obligation goes from prose into a mechanism: a hook, a gate, a pre-commit check. If a rule matters exactly enough that "improved distribution" is not enough — then it does not belong in a file that only improves distribution.
The conclusion is short. Pandey is right, and his rightness matters more than the loudness of the thesis suggests: almost everyone needs a flat contract, and almost everyone overcomplicates it. But the flat file and layered routing are not camps — they are two ends of one scale of earned complexity. Start on the left. Move right only when you hold a compliance problem a sheet of rules cannot express, or a requirement you cannot leave as a request in prose. And then the honest takeaway from Pandey's piece is not "the contract beat the layers" but "write in prose everything you can ask for, and mechanize everything you must guarantee."