A CLAUDE.md file allegedly used by Andrej Karpathy is making the rounds in developer communities. The opening line sets the tone:
These are not suggestions. These are rules. Follow them, and the code you produce will not need to be rewritten. Ignore them, and your code may look impressive — and break in production.
It reads like a grizzled veteran of a thousand tech-debt postmortems lecturing a new hire. Except the new hire is not human. The document is written for Claude Code.
For the uninitiated: CLAUDE.md is Anthropic’s project-level instruction file for Claude Code and Claude-integrated editors. Drop it in your project root and Claude reads it automatically when working. You tell it “this project uses React, prefers fetch over axios, prefers function components,” and it remembers. The version circulating under Karpathy’s name spread partly on his fame — but mainly because it does something many developers have vaguely felt and never systematically expressed: it turns the systemic flaws of LLM code generation into a diagnostic manual with a matching process-governance plan.
The Core Problem: The Model Doesn’t Consider Itself Part of the Team
Most developers pair-program with AI daily, and what actually hurts is not that the AI can’t write code. It is that the code it writes is always somehow off. Syntactically correct. Logically correct. And yet, dropped into your project, subtly wrong in a way you feel before you can name.
The document pinpoints the source of that wrongness with precision: when an LLM writes code, it is pattern-matching — retrieving the training-data fragments closest to the current request and generating from them. It did not read your codebase first. This is fundamental. A human developer inheriting a project starts by reading code, studying the file structure, absorbing existing patterns. The LLM’s single inference pass contains no “scan the repository” step. So you get the classic symptoms: axios introduced into a codebase that is all fetch; camelCase variables in a snake_case project; a decorator pattern in a codebase that has never used one. The training data teems with these patterns, and the current input happened to trigger them.
The document’s first rule — before writing any code, read the files you are about to modify — attacks exactly this root cause. It is not teaching the model to read; it is forcing “load the codebase context” to be step one of every write.
Every Rule Maps to One of Five Failure Modes
Read superficially, the document is a pile of how-to instructions covering everything from reading code to writing commit messages. Underneath, the pile targets five systematic LLM failure modes:
Failure one: context blindness — generating without reading the codebase. Symptoms: syntactically valid code in a mismatched style, unnecessary dependencies, patterns copied from projects that don’t exist here. The rule: read before you write — check the imports, check the tests, check how this project already does it.
Failure two: invisible decision-making — guessing instead of deciding out loud. Symptoms: the user says “add authentication” and the model silently picks an approach; the user discovers what they got only after receiving the code. The rule: state your assumptions, state your tradeoffs, never decide on someone’s behalf in silence.
Failure three: premature abstraction — over-engineering from day one. Symptoms: an EmailService with a strategy pattern for a product that sends one kind of email; an abstract base class for a single implementation. The rule: keep it simple — write the minimum code first, abstract when the abstraction is actually earned.
Failure four: confirmation bias — verifying blindly. Symptoms: seeing an error and generating a fix by error type without reading the message; changing three places without knowing which one fixed the bug. The rule: reproduce first. Change one thing at a time. Read the stack trace. Write the test before the fix.
Failure five: knowledge hallucination — inventing what doesn’t exist. Symptoms: an API that was never real, a parameter removed two versions ago, library features that exist only in the model’s imagination. The rule: say so when unsure. Check the documentation. Read the actual source.
None of these failures is random. They are what the LLM’s architecture looks like when it collides with programming: bounded context, reasoning without backtracking, confidence uncorrelated with accuracy. CLAUDE.md is not magic. It is process compensation designed after honestly admitting those limits.
The Framework: From Code Generation to Code Development
The most valuable takeaway from the whole document is not any single rule. It is the hidden premise: what today’s LLMs lack is not code-generation ability — it is the awareness of participating in development as a team member. Abstract the rules into a framework and three stages appear. Stage one: read the code — absorb the project’s context, patterns, constraints. Stage two: make decisions — clarify assumptions, requirements, and tradeoffs; plan before executing. Stage three: write the code — minimal changes, verified correctness, clearly communicated. Most developers using an LLM enter directly at stage three. The result is the endless replay of stage-one failures: the code gets written, and only then does everyone discover the wrong library, the wrong style, the better solution that already existed in the codebase. What CLAUDE.md fundamentally attempts is to convert read → think → write — the workflow every human engineer has internalized — into explicit, executable steps the model runs before every generation.
And it works measurably. A community project, andrej-karpathy-skills on GitHub, assembled from Karpathy’s public complaints reports dropping Claude’s code error rate from 41 percent to 11 percent. That is not a miracle — when the model reads the codebase before writing, bad-code generation genuinely falls.
Where Else the Framework Explains What You’re Seeing
The same analysis travels across tools. Cursor’s Tab mode versus Chat mode: Tab completion’s context is the current file, which is why it excels at style-consistent completions; Chat crosses files, but without an explicit instruction to read the codebase first, it drifts. Copilot CLI’s style and quality problems: teams replacing Claude Code with Copilot CLI internally have found the trade-off is rarely raw capability — it is that multi-turn conversations drift from project style. A project-level constraint file would eliminate much of that wasted token spend. Why the best engineers all maintain their own CLAUDE.md: not because they know some secret art of AI tuning, but because they understand that a project’s code style is sedimented team habit and social convention — something “correct code” cannot capture — and they are making that tacit knowledge explicit. Once you internalize the read-think-write framework, the ceiling of “AI-assisted programming” comes into focus: it was never how complex a program the LLM can write. It is whether the LLM can think of itself as part of the codebase. CLAUDE.md is the bridge that lets it try.
What To Do This Week
If you write code with Claude Code: spend thirty minutes writing a CLAUDE.md for your project. Don’t copy Karpathy’s wholesale — use it as a checklist. Which libraries, which style, which conventions. You will notice the model’s willingness to read before writing improve immediately.
If you use another AI coding tool: check whether it has a project-level constraint mechanism. If not, manually prepend one sentence to your sessions: “Read the project root and the most recent source files first, tell me which libraries and style this project uses, and then we start writing code.”
If you are an independent developer or team lead: fold the CLAUDE.md into your onboarding documentation. The problems it solves — project style, conventions, stack preferences — were always supposed to live in the README or the contribution guide. Nobody read those. The AI does. Writing the version meant for the machine forces you, as a side effect, to write down the knowledge you never documented for humans.
One passage from the original document deserves rereading:
The current failure mode is this: the LLM generates a “correct” piece of code that is completely alien to the codebase it landed in. It runs. But it looks like a different person wrote it — because a different entity did. The human developer must now either rewrite it to match the project’s style, or live with the inconsistency forever. Both outcomes are bad.
When a tool writes code that is 100 percent correct and reduces the codebase’s maintainability by 30 percent, is it helping you or hurting you? The core value of CLAUDE.md is moving that question from postmortem to pre-planning. These are not just rules for an AI to obey. They are the operating manual for the entire AI-assisted programming paradigm.
Sources: 36Kr; Synced (the original Chinese write-up); the andrej-karpathy-skills project on GitHub.
