Karpathy Coding Guidelines

// Overview

This project packages four coding-agent principles into a rule file, shipped as a Claude Code plugin (with marketplace metadata and a `skills/karpathy-guidelines` skill), a drop-in `CLAUDE.md`, and a committed Cursor project rule. It is derived from Andrej Karpathy's public observations about how LLMs fail at coding: they make wrong assumptions and run with them, they don't manage their own confusion or surface tradeoffs, they overcomplicate code and bloat abstractions, and they change or remove code they don't sufficiently understand.

Each principle targets one of those failures. **Think Before Coding** requires stating assumptions explicitly, presenting multiple interpretations instead of silently picking one, pushing back when a simpler approach exists, and stopping to name what is unclear. **Simplicity First** bans features beyond what was asked, abstractions for single-use code, unrequested configurability, and error handling for impossible scenarios. **Surgical Changes** forbids improving adjacent code, refactoring what isn't broken, or deleting pre-existing dead code — every changed line must trace to the request, and only orphans your own edit created get cleaned up. **Goal-Driven Execution** converts imperative tasks into verifiable ones ("write a test that reproduces the bug, then make it pass"), on the reasoning that strong success criteria let the model loop independently while weak ones force constant clarification.

The repo is candid about the tradeoff: the guidelines bias toward caution over speed, and the README says to use judgment on trivial changes rather than applying the full rigor to a typo fix. It also names the signals that it is working — fewer unnecessary changes in diffs, fewer rewrites from overcomplication, clarifying questions arriving before implementation instead of after mistakes, and clean minimal PRs with no drive-by refactoring.

// What it does

• Installs as a Claude Code plugin from its own marketplace, making the skill available across every project
• Also usable as a plain `CLAUDE.md` you curl into a project, or appended to an existing one
• Ships a committed Cursor project rule (`.cursor/rules/karpathy-guidelines.mdc`) so the same guidelines apply in Cursor
• Four principles with concrete tests attached — "would a senior engineer call this overcomplicated?", "does every changed line trace to the request?"
• A transformation table for turning imperative instructions into verifiable goals, plus a plan-with-verification-steps format
• Designed to be merged with project-specific instructions rather than replacing them; English and Simplified Chinese READMEs

// Getting started

Pick the plugin route if you want the guidelines everywhere, or the CLAUDE.md route to scope them to one repository.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Stop a coding agent from silently choosing one reading of an ambiguous request instead of asking
• Keep agent-authored PRs small and reviewable by banning drive-by refactoring of untouched code
• Give a team one shared baseline `CLAUDE.md` that project-specific rules extend rather than replace
• Turn vague tasks into test-first goals the agent can loop on without supervision

// How Karpathy Coding Guidelines compares

Karpathy Coding Guidelines alongside other open-source agent skills & plugins tools AI/TLDR tracks, ranked by GitHub stars.