Purpose
This project provides a single CLAUDE.md file used to improve the behavior of Claude Code. Its content is derived from Andrej Karpathy's observations on LLM coding pitfalls, with the goal of enabling coding agents to reduce costly errors in non-trivial tasks.
Karpathy points out that models make wrong assumptions on behalf of users and execute directly without checking; they do not manage their own confusion, do not seek clarification, do not expose inconsistencies, do not present trade-offs, and do not push back when they should. Models also tend to overcomplicate code and APIs, inflate abstractions, fail to clean up dead code, and write 1,000 lines when 100 lines would suffice. In addition, they sometimes modify or delete comments and code they do not fully understand, even when these are unrelated to the task.
Main capability: four principles
1. Think before coding
Do not assume, do not hide confusion, and present trade-offs. This principle requires explicit reasoning: clearly state assumptions, and ask rather than guess when uncertain; when ambiguity exists, present multiple interpretations rather than silently choosing one; when a simpler solution exists, raise an objection; when confused, stop, point out what is unclear, and request clarification.
2. Simplicity first
Use the minimum amount of code needed to solve the problem, without any speculative design. Counter the tendency toward overengineering: do not add features that were not requested; do not create abstractions for one-off code; do not add unrequested "flexibility" or "configurability"; do not write error handling for impossible scenarios; if 200 lines can be written as 50 lines, rewrite it. The test: would a senior engineer consider this overly complex? If so, simplify it.
3. Surgical changes
Touch only what must be touched, and clean up only the mess you created. When editing existing code: do not "improve" adjacent code, comments, or formatting; do not refactor things that are not broken; match the existing style, even if you would use a different approach; if you notice unrelated dead code, mention it but do not delete it. When your own changes produce orphaned code: remove imports, variables, and functions that became unused because of your changes; unless asked, do not remove pre-existing dead code. The test: every changed line should be directly traceable to the user's request.
4. Goal-driven execution
Define success criteria and loop until verification passes. Turn imperative tasks into verifiable goals: for multi-step tasks, state a brief plan. Strong success criteria let the LLM loop independently; weak criteria (such as "make it work") require constant clarification.
Usage
Option A: Claude Code plugin (recommended)
In In Claude Code, first add the marketplace, then install the plugin. This installs the guide as a Claude Code plugin, making the skill available across all projects.
Option B: CLAUDE.md (per project)
For existing projects, append it to CLAUDE.md.
Using with Cursor
This repository includes a committed Cursor project rule (.cursor/rules/karpathy-guidelines.mdc), so these guidelines also apply when the project is opened in Cursor. For setup, using the rule in other projects, and how it relates to Claude Code, see CURSOR.md.
When to Use
These guidelines are designed to be merged with project-specific instructions. They can be added to an existing CLAUDE.md or used to create a new CLAUDE.md. For project-specific rules, add the corresponding sections.
These guidelines favor caution over speed. For trivial tasks (simple typo fixes, obvious one-line changes), use your own judgment—not every change needs the full process. The goal is to reduce costly errors in non-trivial work, not to slow down simple tasks.
How to Tell If It Is Working
These guidelines are working if the following occurs: fewer unnecessary changes appear in the diff, and only the requested changes are present; fewer rewrites happen due to overcomplication, and the code is simple the first time; clarifying questions come before implementation rather than after errors; PRs are clean and minimal, with no incidental refactoring or "improvements."
Limitations
The material does not provide the project's license, maintenance status, compatible Claude Code version, the specific contents of the installation command, or pricing or fee information.
