A Single CLAUDE.md File That Tries to Curb Claude Code's Worst Habits

What This Repository Actually Is

This is not a code library or a framework. It is a single CLAUDE.md file, plus a Cursor rule file, that encodes four behavioral guidelines for Claude Code. The guidelines come from a post by Andrej Karpathy that criticizes LLMs for making wrong assumptions, overcomplicating code, and making unrelated edits. The repository's README quotes Karpathy directly, and the file translates those complaints into actionable rules for the model. If you are an engineer who uses Claude Code, this is a prompt-level intervention. It does not change the model, only the instructions it receives. That is both the appeal and the weakness: it is trivially easy to adopt, but its effectiveness depends on how well Claude Code follows a long list of instructions in a markdown file.

The Four Principles and What They Target

The CLAUDE.md file organizes its guidance into four principles. Think Before Coding forces the model to state assumptions explicitly, present multiple interpretations when ambiguity exists, and push back when a simpler approach is available. This targets Karpathy's observation that models 'make wrong assumptions on your behalf and just run along with them without checking.' Simplicity First is a direct counter to overengineering: no features beyond what was asked, no abstractions for single-use code, no error handling for impossible scenarios. The README even includes the blunt rule: 'If 200 lines could be 50, rewrite it.' Surgical Changes addresses the problem of models modifying code they do not understand. The rule is to touch only what the user requested, match existing style, and never delete unrelated dead code; you can mention it, but not remove it. Goal-Driven Execution transforms imperative tasks into verifiable goals. Instead of 'add validation,' the model should 'write tests for invalid inputs, then make them pass.' Each principle maps to a specific failure mode from Karpathy's post, which gives the file a clear internal logic.

How the File Works in Practice

The mechanism is simple: Claude Code reads CLAUDE.md at the start of a session, and the instructions become part of its context. The repository offers two ways to apply the file. The first is a Claude Code plugin, which you install from a marketplace using the command '/plugin marketplace add forrestchang/andrej-karpathy-skills', then '/plugin install andrej-karpathy-skills@karpathy-skills'. This makes the skill available across all your projects. The second is per-project: you download the raw CLAUDE.md file and either create a new one with 'curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md' or append it to an existing one. For Cursor users, the repository includes a committed rule file at .cursor/rules/karpathy-guidelines.mdc. The README also suggests adding project-specific rules after the general guidelines, with examples like 'Use TypeScript strict mode.' There is no code to compile, no dependencies, and no configuration beyond placing the file where Claude Code expects it. That is the entire installation process.

The Key Insight: Success Criteria Over Imperative Commands

The most interesting part of the file is the Goal-Driven Execution principle. Karpathy's insight, quoted in the README, is that LLMs are 'exceptionally good at looping until they meet specific goals.' The file operationalizes this by telling the model to convert tasks like 'fix the bug' into 'write a test that reproduces it, then make it pass.' It even provides a template for multi-step tasks: each step lists a verification check. This is a shift from telling the model what to do to giving it a target and letting it iterate. The README argues that weak criteria like 'make it work' force constant clarification, while strong criteria let the model loop independently. This is a practical technique that could reduce back-and-forth in a session. However, it assumes the model can write a meaningful test for every task, which is not always true for tasks like refactoring or UI changes. The file does not address that limitation.

A Real Limitation: It Is a Prompt, Not a Guarantee

The biggest limitation is that this file relies entirely on the model's compliance. A CLAUDE.md file is advisory; Claude Code may ignore it, especially if the task is complex or the model's context is full. The README itself acknowledges a tradeoff: these guidelines bias toward 'caution over speed.' For trivial tasks like a typo fix, the full rigor is overkill. The file tells the model to use judgment, but that is a vague instruction. Another limitation is that the file does not enforce anything. There is no linter, no test runner, no CI check. If the model decides to overengineer anyway, the file cannot stop it. The only feedback loop is the human reviewing the diff and deciding whether to revert. That means the value of this repository is proportional to how often you review the model's output. For teams that rely on autonomous agent runs, this file may reduce mistakes, but it will not eliminate them.

Alternative Approaches: Prompting vs. Enforcement

A more robust alternative is to use a tool that enforces constraints rather than suggesting them. For example, you could write a custom pre-commit hook or a script that checks for common overengineering patterns, such as excessive abstraction or dead code. That is a different approach: it catches violations after the fact, not by influencing the model. Another alternative is to use an agent platform, like the Multica platform that the README mentions as the author's new project. Multica is described as an open-source platform for running coding agents with reusable skills. That is a different approach because it would give you a structured way to define reusable skills, rather than relying on a single prompt file. CLAUDE.md is a suggestion; if you need guarantees, you need enforcement, not prompting.

Maintenance and License Implications

The README declares an MIT license (GitHub metadata records none and there is no LICENSE file at the top level), which means you can copy, modify, and redistribute the file freely, even for commercial use. That is a low barrier. The maintenance cost is also low in terms of code, because there is no code. However, the file's effectiveness depends on Claude Code's behavior, which changes over time. If Anthropic updates Claude Code to handle context differently, the file may become less effective or even counterproductive. You would need to monitor that. The README also suggests merging the guidelines with your project-specific instructions, which means you may end up maintaining a custom CLAUDE.md that combines both. That is a modest ongoing cost. The repository itself has no releases and its last push was on 2026-04-20, so you cannot rely on regular updates from the author. You are essentially adopting a static file that you must maintain yourself if you want it to stay relevant.

Editorial conclusion

Adopt this if you use Claude Code or Cursor and want a low-cost way to nudge the model toward caution, simplicity, and verification. It is not a substitute for code review or a test suite; a prompt cannot enforce behavior. Do not adopt it if you expect guarantees or if your workflow depends on speed over rigor. Before using, verify the CLAUDE.md content matches your team's tolerance for slowing down trivial tasks, and test it on a small project to see if the model actually follows the principles. The repository is a single file with MIT license, so the real cost is maintenance: you must keep it updated as Claude Code's behavior evolves, and you must ensure it does not conflict with your project's existing CLAUDE.md.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases