This GitHub repository offers a set of guidelines for Claude Code, inspired by Andrej Karpathy's observations on the limitations of LLMs in software development. With over 3,400 stars within days, it clearly addresses a need within the community.
Identified problems: Karpathy observed that models tend to make erroneous assumptions without verification and to "head off in a direction" without validating their premises. They often over-complicate solutions, creating unnecessary abstractions when simple approaches would suffice. Finally, they sometimes modify or remove code they do not fully understand, even when unrelated to the requested task.
Four founding principles:
The first principle, "Think Before Coding", requires making assumptions explicit and asking clarifying questions rather than guessing. In case of ambiguity, present several viable approaches. Stop and acknowledge confusion when it occurs.
The second principle, "Simplicity First", prescribes writing the minimal code that addresses only what is requested. Avoid speculative features, unnecessary abstractions, and unsolicited configurability. Remove error handling for impossible scenarios. The test: would an experienced engineer consider this code over-engineered?
The third principle, "Surgical Changes", limits modifications to code directly related to the user's request. Preserve existing style and comments. Remove pre-existing dead code only upon explicit request.
The fourth principle, "Goal-Driven Execution", converts tasks into specific, verifiable success criteria. Rather than "add validation", formulate "write tests for invalid inputs, then make them pass". Use brief numbered plans with verification steps.
Core insight: Models excel at "looping until specific goals are reached". Rather than issuing imperative instructions, define clear success criteria and let the system iterate toward those goals.
Installation and usage: The repository can be installed as a Claude plugin (claude plugins add) or downloaded as a per-project CLAUDE.md file. The guidelines are designed to be merged with project-specific rules.
Success indicators: Diffs contain only the requested changes, code avoids unnecessary complexity on the first attempt, clarifying questions precede implementation, and pull requests remain focused without tangential refactoring.
Caveat: These guidelines prioritize precision over speed. For trivial changes (typos, obvious one-line edits), apply common sense rather than full rigor.