Andrej Karpathy's CLAUDE.md: Why a 65-Line File Passed 200,000 GitHub Stars
TL;DR
- CLAUDE.md is the file Claude Code reads first in any project, before anything else, and it sets the AI's project-specific behavior for the whole session.
- A longer CLAUDE.md eats into the same context window used for actual code and conversation, so more rules can make an agent perform worse, not better.
- Karpathy's four rules: think before coding, keep it simple, make surgical changes, and drive execution off a defined success condition.
- The file is public and free to copy into any project root; it takes effect the next time Claude Code reads that directory.
Andrej Karpathy has 3.2 million followers on X and doesn’t tweet about coding agents often. When he did, in January 2026, describing the exact ways he’d watched AI coding agents get things wrong over a few weeks of daily use, a developer named Forrest Chang turned the observation into a 65-line file. It’s now past 200,000 combined GitHub stars across Chang’s personal repo and the organization mirror that followed.
Why did Andrej Karpathy’s tweet carry so much weight?
Karpathy co-founded OpenAI, ran Tesla’s AI team for years, returned to OpenAI once more, then left again in 2024 to start Eureka Labs, an AI education startup. In May 2026, he joined Anthropic’s pre-training team, the group using Claude to accelerate how future Claude models get trained. His Stanford deep learning lectures have been watched by millions of people who’ve never touched a research paper. When he posts about a technical pattern he’s personally observed, it tends to get taken seriously, because the credibility isn’t secondhand.
What he actually wrote was specific, not a vague complaint. Four observations, each describing a distinct failure mode:
“The models make wrong assumptions on your behalf and just run along with them without checking. They don’t manage their confusion, don’t seek clarifications, don’t surface inconsistencies, don’t present tradeoffs, don’t push back when they should.”
“They really like to overcomplicate code and APIs, bloat abstractions, don’t clean up dead code… implement a bloated construction over 1000 lines when 100 would do.”
“They still sometimes change/remove comments and code they don’t sufficiently understand as side effects, even if orthogonal to the task.”
What does CLAUDE.md actually do?
CLAUDE.md is the first file Claude Code reads when it starts working in a project directory. It’s a plain markdown file sitting at the project root, and its contents occupy the model’s context window before the user’s next input even arrives, functioning as a standing manual for how the agent should behave in that specific codebase.
Context windows are large now. Claude Sonnet 5 ships with a full 1 million token window by default, no smaller tier to opt into. But Sonnet 5’s tokenizer also produces roughly 30% more tokens for the same amount of text than the previous generation did, so the practical headroom hasn’t grown as much as the sticker number suggests. Whatever the ceiling, every line spent on CLAUDE.md is a line not spent on the actual conversation, which is exactly the mechanism Karpathy’s rules are built to respect: a long list of instructions can make a model behave worse, not better, once compaction kicks in and something has to get dropped to make room.
What are Karpathy’s four rules?
- Think before coding. Understand and plan before writing anything, instead of jumping straight to output.
- Simplicity first. Build only what was asked. No unrequested features, no speculative flexibility.
- Surgical changes. Touch only the code that needs to change. Leave everything adjacent alone.
- Goal-driven execution. Define what success looks like before starting, and use that definition to judge when the task is actually done.
Karpathy’s own framing of the fourth rule captures why it works: “LLMs are exceptionally good at looping until they meet specific goals… Don’t tell it what to do, give it success criteria and watch it go.” The rule isn’t about restraining the model. It’s about pointing its actual strength, persistent iteration toward a fixed target, at a target that’s been defined clearly enough to hit.
How do you actually use it?
The file lives in Forrest Chang’s repository, mirrored under the multica-ai organization on GitHub. Cloning the whole repo isn’t necessary: copying the CLAUDE.md contents directly into a project’s root directory is enough, and Claude Code picks it up starting with the very next session.
References
You might also like