Karpathy's AI Coding Guidelines: Install the CLAUDE.md That Developers Use

Karpathy’s AI Coding Guidelines: Set Up Your Agent

Andrej Karpathy posted a thread about what AI coding agents get wrong. Someone turned it into a CLAUDE.md template. 158k stars later, it is the most adopted set of guidelines for keeping AI agents in line.

Four principles. Drop them into your project and your coding agent starts acting like it has a senior engineer watching. Here is how to set it up on Claude Code, Cursor, and OpenCode.

The Four Principles

Karpathy noticed that LLMs share specific failure patterns: they make assumptions without checking, overcomplicate code, change things they should not, and drift without clear success criteria. This CLAUDE.md directly addresses each one.

Think Before Coding. Models pick an interpretation and run with it. They do not surface confusion or present tradeoffs. This principle forces them to state assumptions, ask when uncertain, and push back when a simpler approach exists.

Simplicity First. LLMs gravitate toward bloat. They build abstractions for single-use code, add flexibility nobody asked for, and turn 100 lines into 1000. This rule kills that: no features beyond scope, no speculative architecture, no error handling for impossible cases. If a senior engineer would call it overcomplicated, simplify.

Surgical Changes. The worst failure mode. Models change comments they do not understand, reformat code they were not asked to touch, and refactor things that work. This rule says touch only what the task requires and clean up only your own mess. Every changed line must trace to the request.

Goal-Driven Execution. Karpathy noted that LLMs excel at looping toward specific goals but flounder with vague instructions. Instead of “add validation,” write “write tests for invalid inputs, then make them pass.” Clear success criteria let the agent work independently.

Installation

Claude Code Plugin (Recommended)

From inside Claude Code, add the marketplace then install:

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

This makes the guidelines available across all projects without manually copying files.

CLAUDE.md (Per-Project)

For a new project:

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

To append to an existing CLAUDE.md:

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

Cursor

The repo ships with a Cursor project rule at .cursor/rules/karpathy-guidelines.mdc. Copy it into your project’s .cursor/rules/ directory and Cursor will apply the same guidelines automatically.

OpenCode / AGENTS.md

OpenCode uses AGENTS.md and CLAUDE.md for agent instructions. Append the four principles into your AGENTS.md in the behavioral guidelines section:

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

Or copy the relevant sections into your existing ~/.config/opencode/AGENTS.md for system-wide application.

What Changes

Without this file, the agent picks one interpretation silently, builds a 200-line solution with three abstractions, reformats two unrelated files, and delivers code that almost works but misses the edge case you mentioned twice.

With it, the agent says “I see two possible approaches here, which one?” writes 50 lines, touches only the files you asked about, and runs the test you told it to write.

Give it a week and this becomes muscle memory. Clarifying questions start appearing on their own. PRs shrink. The agent stops “improving” things that were fine.

How to Know It Is Working

If the agent starts asking questions before writing code, making smaller changes, and flagging ambiguity instead of guessing, it is working. If it still charges ahead like before, the CLAUDE.md probably is not loaded. Check the file exists at your project root.

Customization

The template is designed to merge with project-specific rules. Add your own sections below the four principles:

## Project-Specific Guidelines
- Use TypeScript strict mode
- All API endpoints must have tests
- Follow error handling patterns in src/utils/errors.ts

The project-specific section gets appended after the Karpathy principles so both apply.

Tradeoff

The whole point is caution over speed. For a typo fix or an obvious one-liner, you do not need the full process. The guidelines say so themselves: use judgment on simple changes, run the full thing on complex work.