Karpathy's CLAUDE.md Template: 5,800 Stars and What It Does

A plain markdown file hit 5,828 GitHub stars in a single day — making it the second most-starred repo on the planet on April 13, 2026. No framework. No SDK. No install script. Just a text file you drop into your project root.

The repo is forrestchang/andrej-karpathy-skills, and it contains a single CLAUDE.md configuration file derived from Andrej Karpathy's observations about how large language models fail when writing code. It's not written by Karpathy himself — but it's built on his analysis, carries his name in the title, and clearly struck a nerve. Our cross-source convergence report showed 7 out of 7 tracked platforms lighting up on the Claude Code ecosystem simultaneously on the same day — GitHub, HN, Reddit, X, AI YouTube, Tech YouTube, and Substack — which is about as rare as signals get.

This article breaks down exactly what the file does, why it works, and what its viral moment says about where Claude Code development is heading in 2026.

---

What Is CLAUDE.md, and Why Does It Matter?

Before we get to Karpathy's specific template, it helps to understand the substrate.

CLAUDE.md is a markdown file that lives at the root of your project. When you launch Claude Code, it reads the file automatically and incorporates its contents as context for the entire session. Think of it as a persistent system prompt you control — except unlike a system prompt, it's version-controlled alongside your code, shareable with your team, and editable without touching any configuration UI.

From the official Claude Code best practices documentation:

"There's roughly a 150-200 instruction budget before compliance drops off, and the system prompt already uses about 50 of those. If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise."

This is the first thing most developers get wrong: they treat CLAUDE.md as a dump for every preference and convention they've ever had. The more useful mental model is a behavioral contract — a focused set of rules that correct for the specific ways Claude misbehaves on your kind of project.

Karpathy's template takes this seriously. The entire file is under 200 lines. It has four sections.

For broader context on working effectively with Claude Code, see our complete guide to Claude Code in 2026.

---

The 4 Principles in Karpathy's CLAUDE.md

1. Think Before Coding

Core principle: "Don't assume. Don't hide confusion. Surface tradeoffs."

Before implementing anything non-trivial, the file instructs Claude to state its assumptions explicitly. If there are multiple valid interpretations, present them. If something is unclear, halt and ask.

This principle targets what Karpathy identified as the single most destructive LLM coding behavior: silent assumption-making. Models are trained on massive corpora of human writing, where confident assertion is typically rewarded. The result: when Claude encounters an ambiguous spec, it fills in the gaps with whatever seems plausible — and charges ahead.

The fix isn't complicated. It's forcing a checkpoint before execution.

2. Simplicity First

Core principle: "Minimum code that solves the problem. Nothing speculative."

The file prohibits unrequested features, abstractions for single-use code, unnecessary configurability, and error handling for scenarios that can't actually happen.

There's a self-test embedded in the template: "Would an experienced engineer view this as overengineered?" This is deliberately subjective — it invokes a heuristic judgment rather than a checklist.

The pattern it corrects: LLMs are extraordinarily good at pattern-matching against complex, enterprise-grade code in their training data. When asked to "add a cache," Claude will often produce a full-featured LRU implementation with eviction policies, thread safety, and metrics hooks — because that's what "cache implementation" looks like in most codebases it has seen. That's frequently five times more code than what was needed.

3. Surgical Changes

Core principle: "Touch only what you must. Clean up only your own mess."

When modifying a file, Claude should not "enhance" surrounding code, reformat things it didn't break, or refactor patterns it disagrees with. There's a sharp distinction drawn between dead code you introduced (clean it up) and pre-existing dead code (flag it, don't touch it).

This principle most closely maps to how good human engineers work on unfamiliar codebases. When you open a PR to fix a bug, you don't simultaneously rewrite the adjacent function because it's "not idiomatic" — you fix the bug, get it reviewed, and leave editorial improvements for a separate ticket.

Claude, left unconstrained, tends to interpret "fix this" as implicit permission to improve the surrounding area. That creates noisy diffs, hidden regressions, and review overhead that cancels the efficiency gains you were trying to capture.

4. Goal-Driven Execution

Core principle: "Define success criteria. Loop until verified."

Every task should be converted into a measurable objective with explicit verification steps before Claude starts writing. The difference between "add a login form" and "add a login form — success when: form renders at /login, submits correctly with valid credentials, shows error state on invalid credentials, and passes the existing auth test suite" is not pedantry. It's the difference between an agent that loops productively and one that declares victory on a half-finished implementation.

---

Why It Went Viral: The Priming Mechanism

The deeper question isn't what the file does — it's why a text file with four principles accumulated nearly 6,000 stars in a single day.

Part of the answer is Karpathy's name. He's one of the most credible voices in AI, the person who coined "vibe coding," and the author of the widely-circulated observation that by January 2026 his coding workflow had flipped from 80% manual to 80% agent-driven. As Medium's AI Studio piece on CLAUDE.md notes: "He mentioned a file. A plain markdown file called CLAUDE.md. And the way he talked about it, both what it was supposed to fix and what it still couldn't, turned out to matter more than most people noticed."

But the content itself is load-bearing. The four principles in the file are not novel — they're articulations of pain points that anyone who's used Claude Code for more than a week has felt. The virality is recognition, not discovery.

From Karpathy's X post (3,879 engagements): someone noted that the OpenClaw moment was so significant because it was "the first time a large group of non-technical people (who otherwise only knew AI as synonymous with ChatGPT as a website) experienced the latest agentic models." Karpathy found this framing compelling — and it explains why the CLAUDE.md template spread across both technical and adjacent-technical communities simultaneously.

The larger context: there is now a meaningful split between daily frontier model users and people whose AI mental model is the free tier from 18 months ago. Karpathy's literacy-gap tweet got 26,563 engagements — one of the highest-engagement AI posts in the dataset. The CLAUDE.md template is an artifact of that gap. It's knowledge-encoding: taking hard-won operational experience with Claude Code and turning it into something shareable and replicable.

---

How to Use It in Your Own Stack

The quickest path is to curl it directly:

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

Or install it as a Claude Code plugin so it applies across all projects:

claude plugins install forrestchang/andrej-karpathy-skills

But the more durable move is to treat it as a base layer, not a complete solution.

The four principles are context-agnostic — designed to apply universally. What they don't include is anything about your specific stack: your build system, testing conventions, file structure, naming patterns, or deployment pipeline. The standard pattern is to merge them:

# Project Context

## Stack
- Python 3.12, FastAPI, PostgreSQL
- Tests: pytest with fixtures in tests/conftest.py
- Linting: ruff, enforced in CI

## Key Patterns
- DB queries go through repository layer in app/repositories/
- All API responses use Pydantic response models in app/schemas/

---
<!-- Karpathy base principles below -->

## 1. Think Before Coding
...

From the official best practices documentation: CLAUDE.md is advisory — Claude follows it about 80% of the time. For anything that must happen deterministically (linting, formatting, security checks), make it a hook. The two mechanisms are complementary, not competing.

---

What This Signals About the Claude Code Meta-Ecosystem

The GitHub Trending data for April 13 is worth sitting with.

Four of the five most-starred repos by daily velocity were directly in the Claude Code orbit: hermes-agent (+11,297 stars), andrej-karpathy-skills (+5,828), claude-mem (+3,185), and claude-code-best-practice (+2,477). That's four separate repos, each with a distinct value prop, each pulling thousands of stars in a single day.

From our GitHub digest analysis: "This is what platform maturity looks like: third-party optimization tooling goes viral before the platform even ships half its roadmap. Compare to early npm in 2013 or early k8s operators in 2018."

The comparison to npm and Kubernetes operators is useful. In both cases, the ecosystem tooling boom was a leading indicator — it preceded the period where the underlying platform became load-bearing infrastructure for the broader industry. The developer community doesn't build optimization layers around things they don't plan to depend on.

The HN signal is consistent. A Show HN post about a social media tool built in 3 weeks with Claude and Codex collected 161 points and 109 comments the same day — not because the tool was exceptional, but because the build-speed story is now unremarkable enough to spark meta-debate about what these tools are being used for.

On the same day, a Claude.ai downtime thread hit HN's front page, with the top comment: "basing your entire business on another company's API." That Claude outages are front-page HN news is itself a signal — dependency is deep and widespread. For context on the quota and billing side of that dependency, see our article on Claude Code quota limits and billing changes for 2026.

---

The Limits: What CLAUDE.md Doesn't Fix

There's a counterpoint worth taking seriously. From Mastering Product HQ:

"Your most expensive failure mode is this: Shipping the wrong thing, well. Claude Code will cheerfully implement whatever you describe. It won't stop to ask whose problem you're solving."

Karpathy's template is an engineering discipline tool. It makes Claude's code-writing behavior more predictable and conservative. It doesn't address what gets built — only how it gets built.

The product-mode version of these principles would ask different questions: Who is this for? What changes in their behavior when this ships? What's the minimum change that tests the hypothesis? These are orthogonal to the four principles in the file.

There's also the 80% compliance ceiling from the official docs. CLAUDE.md is advisory. For any rule where consistency matters absolutely — not just most of the time — you need hooks. The two systems work together: CLAUDE.md for behavioral priming, hooks for deterministic enforcement.

---

What the Repo Is Actually Telling You

The 5,828 stars aren't primarily about the file. They're about the signal the file embodies: developers are building a best-practices layer on top of Claude Code faster than Anthropic can ship features.

The CLAUDE.md pattern is part of something larger. claude-mem solves the amnesia problem. andrej-karpathy-skills solves the behavioral discipline problem. hermes-agent tries to solve the persistence-and-growth problem. claude-code-best-practice is a community-compiled handbook. Each going viral on the same day means the Claude Code user base is large enough, experienced enough, and frustrated-about-specific-enough-things to have spawned a parallel ecosystem of meta-tooling.

That's a platform maturity marker. It's the point at which the platform stops being defined by what Anthropic ships and starts being defined by what the community builds on top of it. Karpathy's template is a single file. Its viral moment is an industry signal.

---

How to Get Started

1. Install the base template:

   claude plugins install forrestchang/andrej-karpathy-skills
   

   Or curl it and review before using — 200 lines, reads in 5 minutes.

2. Audit your existing CLAUDE.md if you have one. For every rule: would Claude make this mistake without it? If not, delete it.

3. Add your stack-specific layer — build commands, test runner, key file paths, naming conventions. Keep total under 150 lines.

4. Pair with hooks for any rule that needs to fire 100% of the time.

5. Revisit in 30 days. The best CLAUDE.md files get shorter over time as you delete rules that turn out to be unnecessary.

The file that hit #2 on GitHub trending is a starting point, not a finished product. Adapt it, shrink it, make it yours.

---

For running Claude Code on longer tasks or automating remote work, see our guide on running Claude Code for remote tasks with cloud AI agents.