Karpathy-Inspired Claude Code Guidelines
Less guessing, simpler code, verifiable changes
Explicitly distilled from Andrej Karpathy's public commentary on common LLM coding pitfalls; the four guidelines are concrete and actionable (e.g. 'every changed line should trace to the user's request'), not generic best-practice filler.
A pure behavioral-guideline document (think before coding, simplicity first, surgical changes, goal-driven verification) — takes no actions, touches no data or network, near-zero risk surface.
The star count (191,284) is implausibly high for a single-file behavioral guideline's likely reach; the cause wasn't investigated and doesn't affect this content-based score.
What it does & when to use it
This repository provides a single CLAUDE.md file intended to improve Claude Code behavior, based on Andrej Karpathy's observations about common LLM coding pitfalls. Its guidance is organized around four principles: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. The rules encourage explicit assumptions, minimal implementations, narrowly scoped edits, and verification through tests or other stated success criteria. The README also documents a Cursor rule, while the repository metadata lists the license as unknown even though the README states MIT.
The project supplies behavioral guidance for coding agents rather than a framework, library, or standalone execution tool. It instructs an agent to clarify ambiguity before implementation, avoid unnecessary complexity, limit edits to the requested scope, and turn tasks into verifiable goals.
- Reduce silent assumptions in Claude Code and encourage clarification when requirements are ambiguous.
- Prevent overengineering by avoiding single-use abstractions and unrequested flexibility or configurability.
- Keep maintenance changes focused by avoiding unrelated refactoring, formatting changes, or comment edits.
- Apply test-first or otherwise verifiable workflows to validation work, bug fixes, and refactoring.
- Combine general agent behavior rules with project-specific TypeScript, API testing, or error-handling instructions.
Pros & cons
- Directly addresses four recurring agent problems: hidden assumptions, overengineering, unrelated edits, and weak verification.
- Provides concrete constraints, such as avoiding abstractions for one-time code and preserving pre-existing unrelated dead code.
- Encourages tests that reproduce bugs or validate new behavior, making success easier to check.
- Can be merged into an existing project CLAUDE.md and is accompanied by a Cursor rule.
- SKILL.md is not available in the source, so the standard Agent Skills metadata and complete skill structure cannot be verified.
- The guidance explicitly favors caution over speed, which may add process overhead to trivial tasks.
- It is a set of instructions, not a testing framework, code analyzer, or automated verification system.
- The repository name and the GitHub owner used in the README installation commands do not match, so the installation source should be checked.
How to install
The README gives two installation options. For the Claude Code plugin, run /plugin marketplace add forrestchang/andrej-karpathy-skills, followed by /plugin install andrej-karpathy-skills@karpathy-skills. For a project-level installation, a new project can run curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md; an existing project can run echo "" >> CLAUDE.md and then curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md. The source repository is identified as multica-ai/andrej-karpathy-skills, but the README installation commands use forrestchang/andrej-karpathy-skills, so the source references are inconsistent.
How to use
After plugin installation, the README says the guidelines are available across projects. For project-level use, place the content in the project's CLAUDE.md. The repository also includes .cursor/rules/karpathy-guidelines.mdc and refers to CURSOR.md for Cursor setup. During a task, state assumptions or ask clarifying questions, choose the simplest adequate implementation, keep the diff focused, and define a check or test for each planned step.
Compared to similar skills
Compared with giving a coding agent only imperative instructions, this project emphasizes explicit success criteria and verification loops. Compared with project-specific rules, it supplies general behavioral principles that can be merged with language, API, and testing conventions in an existing CLAUDE.md. The source does not provide feature comparisons with other specific coding-agent skills.