Andrej Karpathy's CLAUDE.md: What It Is, Why It Has 101K Stars, and How Skills Go Further

Quick Answer: Andrej Karpathy's CLAUDE.md is a single-file behavior guide for Claude Code that prevents common LLM coding failures. It has 101K+ GitHub stars and encodes four rules: no silent assumptions, no over-engineering, no orthogonal changes, and explicit verification steps. It's a CLAUDE.md file (always active) not a SKILL.md skill (task-triggered). For domain-specific capabilities beyond behavior rules, SKILL.md skills on Agensi complement Karpathy's rules.

In January 2026, Andrej Karpathy posted his frustrations with AI coding agents. The models were smart but kept making the same mistakes: charging ahead without verifying assumptions, turning 50-line solutions into 500-line abstractions, and modifying code they were never asked to touch.

Developer Forrest Chang turned those observations into a single CLAUDE.md file with four behavioral principles. The repo hit 101K stars in weeks, making it one of the fastest-growing AI workflow repositories in history. All from a single markdown file with zero runtime dependencies.

What the four rules actually do

Rule 1: No silent assumptions. Before making any change, Claude must verify its understanding of the task. If something is ambiguous, it asks instead of guessing. This prevents the failure mode where Claude confidently builds the wrong thing for 20 minutes.

Rule 2: No over-engineering. The simplest solution that works is the correct solution. This prevents Claude from creating elaborate abstractions, utility functions, and design patterns when a straightforward implementation would do. The 50-line solution beats the 500-line one.

Rule 3: No orthogonal changes. If you ask Claude to fix a bug in the authentication flow, it should not also refactor the logging system it noticed along the way. Stay on task. This prevents scope creep that introduces new bugs in code you weren't looking at.

Rule 4: Explicit verification. After completing a change, Claude runs the relevant tests and verifies the output. No "I've made the changes, they should work." It checks.

Get these skills on Agensi

attack-tree-construction

by LocoLoboZ

$10

User Detection & Session Context Reviewer

by LB Creations

$14.99

ai-team-builder-kanban

by Roy Yuen

$5

Browse all skills

CLAUDE.md vs SKILL.md: they're different things

This confuses a lot of people. CLAUDE.md and SKILL.md serve different purposes.

CLAUDE.md is a project configuration file. It lives at the root of your project and is always active. Every Claude Code session in that project reads it. It sets behavioral rules that apply to everything: coding style, verification steps, communication patterns. Karpathy's file is a CLAUDE.md.

SKILL.md is a task-triggered capability. It lives in the skills directory and only loads when the task matches the skill's description. A code-review skill loads when you ask for a review. A testing skill loads when you ask for tests. They add domain-specific expertise for specific tasks.

They're complementary. Karpathy's CLAUDE.md makes Claude behave better across all tasks. SKILL.md skills make Claude better at specific tasks. Use both.

For a detailed comparison of all configuration file types, read AGENTS.md vs SKILL.md vs CLAUDE.md vs .cursorrules.

How to install Karpathy's CLAUDE.md

Clone the repo and copy the file to your project root:

git clone https://github.com/forrestchang/andrej-karpathy-skills.git
cp andrej-karpathy-skills/CLAUDE.md ./CLAUDE.md

Or just create a CLAUDE.md file at your project root and paste the four rules. The file is short enough to read in two minutes.

Restart your Claude Code session. The rules are now active for every interaction in this project.

Skills that complement Karpathy's rules

Karpathy's rules fix behavior. They don't add capabilities. Here's where skills fill the gap.

Code review skills complement Rule 3 (no orthogonal changes) by reviewing Claude's output and flagging any changes outside the requested scope. The skill catches what the behavioral rule might miss.

Testing skills complement Rule 4 (explicit verification) by generating comprehensive tests before Claude even starts coding. Instead of verifying after the fact, the skill creates the verification criteria upfront.

Architecture skills complement Rule 2 (no over-engineering) by giving Claude explicit patterns to follow for your stack. Instead of inventing abstractions, Claude follows your established architecture. The skill turns "don't over-engineer" from a vague instruction into a specific template.

Browse skills that pair well with Karpathy's rules at agensi.io/skills.

Why it went viral

Three reasons. First, it validated a frustration every Claude Code user felt but couldn't articulate. The failure modes Karpathy described were universal. Second, the fix was absurdly simple: a single text file, no dependencies, no installation. Third, Karpathy's name carries weight. When the former director of AI at Tesla says "this is how to fix AI coding agents," people listen.

The deeper lesson: AI agents are only as good as their instructions. A raw Claude Code session with no guidance is a brilliant engineer on day one at a new company. Karpathy's CLAUDE.md gives it the "how we work here" brief. SKILL.md skills give it the "here's how to do this specific task" playbook. Both are just markdown files. Both dramatically improve output quality.