Karpathy‑Style Programming Principles: Making AI‑Generated Code Viable for Real Engineering

As AI coding assistants become commonplace, a fundamental question arises: do these tools truly understand the developer’s intent?

Project Overview

The repository forrestchang/andrej-karpathy-skills implements Andrej Karpathy’s observations about Claude Code behavior in a carefully crafted CLAUDE.md file that guides AI coding tools to avoid common pitfalls. The project has attracted 9.9k stars on GitHub.

Four Core Principles

1. Think Before Coding

Explicitly state assumptions – ask for clarification instead of guessing.

Present multiple interpretations when ambiguity exists.

Challenge the solution when a simpler alternative is possible.

Pause and request clarification whenever confusion arises.

2. Simplicity First

Do not add any functionality beyond the stated requirements.

Avoid abstracting code that will be used only once.

Do not introduce unnecessary flexibility or configurability.

Do not handle exception scenarios that cannot occur.

If 200 lines can be expressed in 50, rewrite it.

Verification standard: a senior engineer asks, “Is this too complex?” and the answer should be “simplify.”

3. Surgical Changes

Do not “tidily” modify adjacent code, comments, or formatting.

Do not refactor code that is not broken.

Match the existing style even if you would prefer a different approach.

If you discover unrelated dead code, point it out – do not delete it yourself.

Verification standard: every line changed must trace back to the original user requirement.

4. Goal‑Driven Execution

Define success criteria and iterate until they are met.

Transform imperative tasks into verifiable goals. For example:

Don’t say “add validation”; say “write a test for invalid input and make it pass.”

Don’t say “fix this bug”; say “write a reproducing test and make it pass.”

Don’t say “refactor X”; say “ensure tests pass before and after refactoring.”

For multi‑step tasks, declare a brief plan using the pattern:

1. [step] → verify: [checkpoint] 2. [step] → verify: [checkpoint] 3. [step] → verify: [checkpoint]

Strong success criteria enable the LLM to loop autonomously, whereas vague criteria (“make it work”) require continual clarification.

Installation Methods

Method 1: Claude Code Plugin (recommended)

Run in Claude Code:

/plugin marketplace add forrestchang/andrej-karpathy-skills

Method 2: Manual Installation

Download the CLAUDE.md file to the project root:

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

Why This Matters

Current AI coding tools can produce syntactically correct code, but in real engineering environments they often:

Make silent assumptions, selecting unsuitable solutions without explanation.

Over‑design, turning a 100‑line solution into a thousand lines.

Accidentally delete or break unrelated code when modifying a feature.

Lack measurable success criteria, making delivery quality uncontrollable.

These issues may be hidden in small personal projects but quickly amplify in team collaborations. Karpathy’s four principles provide a systematic framework to address them.

Applicable Scenarios

Engineering leads who want to roll out AI coding tools across a team.

Developers seeking more reliable and predictable AI coding assistants.

Teams focused on code quality and engineering discipline.

Users who want AI coding tools to become genuine productivity boosters.

Project URL: https://github.com/forrestchang/andrej-karpathy-skills