Andrej Karpathy’s critique of LLM coding behavior has been turned into a single CLAUDE.md file, and it is worth reading not because the advice is new, but because it reveals how the AI coding ecosystem is maturing. The GitHub repository, published by a developer going by forrestchang, distills Karpathy’s observations into four principles: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. The file is designed to be dropped into Claude Code as a plugin or appended to a project’s CLAUDE.md, and it also ships with a Cursor rules file for users of that editor.
The source material quotes Karpathy directly on the core problems. “The models make wrong assumptions on your behalf and just run along with them without checking,” he wrote. “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.” The other two quoted failure modes: overcomplicating code with bloated abstractions, and changing or removing code and comments the model does not sufficiently understand. None of this is new to anyone who has watched an agent produce a 1,000-line refactor when a 100-line fix was needed. What is new is the packaging.
The project’s real contribution is operationalizing Karpathy’s critique into a repeatable prompt structure. The CLAUDE.md file does not just tell the model to be careful. It gives concrete tests. For Simplicity First, the test is: “Would a senior engineer say this is overcomplicated? If yes, simplify.” For Surgical Changes, the test is: “Every changed line should trace directly to the user’s request.” For Goal-Driven Execution, the file offers a transformation table: instead of “Add validation,” write “Write tests for invalid inputs, then make them pass.” Instead of “Fix the bug,” write “Write a test that reproduces it, then make it pass.” The idea, as Karpathy puts it in the repo, is that “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 timing matters. Claude Code has become the default workbench for a large slice of the AI-assisted engineering population, and the community around it has started to treat CLAUDE.md files as a form of software. This repository is one of many now circulating on GitHub and X, each claiming to fix a specific failure mode. What distinguishes this one is the provenance. Karpathy is not just any commentator; he is a former director of AI at Tesla, a founding member of OpenAI, and one of the most-watched voices in the field. His observations carry weight, and forrestchang has done the work of turning them into a usable artifact.
There is a deeper point here about how the industry is learning to work with LLM agents. The first wave of prompt engineering was about getting models to produce better output on a single generation. The second wave, which this project belongs to, is about shaping agent behavior over long, multi-step loops. Karpathy’s insight, as encoded in the Goal-Driven Execution principle, is that the bottleneck is not the model’s ability to execute but the quality of the success criteria it is given. Weak criteria like “make it work” force constant human clarification. Strong criteria let the agent loop independently. That is a genuinely useful framing, and it is the most valuable part of this file.
The tradeoff note in the repository is honest. These guidelines “bias toward caution over speed,” and for trivial tasks like typo fixes, the full rigor is unnecessary. That is the right caveat, but it also points to a limitation. The four principles are written for a model that is already competent. They do nothing for the harder problem of knowing when the model’s confusion is a sign that the task itself is ill-defined, or when the model’s pushback is actually a failure to understand the user’s intent. Karpathy’s critique is about models running along with wrong assumptions; this file gives the model permission to ask, but it does not teach it when asking is the right move versus when it is a dodge.
The customization section anticipates this. The file is designed to be merged with project-specific instructions, and it includes a template for adding rules like “Use TypeScript strict mode” or “All API endpoints must have tests.” That is the correct approach. A generic CLAUDE.md can fix generic failure modes, but it cannot encode the specific context of a codebase. The real gains will come from teams that take these four principles and adapt them to their own repositories, their own testing conventions, and their own definitions of done.
The broader signal is in the distribution mechanics. The repository offers two installation paths: a Claude Code plugin that makes the skill available across all projects, and a per-project CLAUDE.md that can be fetched with curl. The plugin path is the more interesting one. It treats the guidelines as a reusable skill, which is exactly the direction the agent ecosystem is heading. Multica, the project forrestchang plugs in the repo, is described as an open-source platform for running coding agents with reusable skills. The CLAUDE.md file is effectively a demonstration of that concept.
What this means for AI builders is straightforward. The era of treating CLAUDE.md as a place for a few project notes is over. These files are becoming the control plane for agent behavior, and teams that treat them as first-class artifacts, versioned, tested, and iterated on, will get measurably better results from their coding agents. The teams that treat them as an afterthought will keep fighting the same battles: agents making wrong assumptions, bloating abstractions, and touching code they do not understand.
The repository’s “How to Know It’s Working” section is the practical checklist. Fewer unnecessary changes in diffs. Fewer rewrites due to overcomplication. Clarifying questions before implementation, not after mistakes. Clean, minimal pull requests with no drive-by refactoring. Those are measurable outcomes, and they are the right ones to track.
Karpathy’s critique has been circulating in various forms since early 2025, and this file is a faithful encoding of it. The question now is whether the community will treat it as a template or as a finished product. The template reading is the correct one. Fork it, adapt it, and merge it with your own project rules. The four principles are a starting point, not a destination. The file works because it gives the model permission to be cautious, but the real work of defining what “done” looks like still belongs to the humans. That is the part no CLAUDE.md file can automate away.