A plain-text Markdown file with not a single line of code has held the number-one spot on GitHub's daily trending chart for three days straight, picking up 44,465 new stars this week. It's called CLAUDE.md — a configuration file that sits in a project's root directory and lays down four rules to rein in the most common failures of AI coding.

What Is CLAUDE.md

CLAUDE.md is a Markdown configuration file placed in the project root. AI coding agents (such as Claude Code and Cursor) automatically read it and follow its rules. The core idea: package a senior engineer's tacit knowledge into instructions an agent can directly understand and execute.

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

The Four Core Principles Explained

The file traces back to a long post Karpathy published on X this January, venting in detail about everything wrong with AI coding agents. Chinese developer Jiayuan Zhang distilled it into four executable rules.

Principle 1: Think Before You Code

The problem: You ask the AI to "add a validation feature", and it won't ask you what to validate or how strict to be — it just guesses the most complex option and writes a pile of code you don't need.

The rules:

• Stop and ask when unsure — never guess
• When multiple readings are possible, list the options and let you choose instead of deciding for you
• Proactively speak up when a simpler approach exists

Principle 2: Simplicity Above All

The problem: You want one simple feature, and the AI writes you a whole enterprise-grade architecture with login authentication, security checks, and rate limiting. You say "keep it simple", and it instantly cuts most of it and says "of course".

The rules:

• No features you didn't ask for
• No abstraction layers for code that runs only once
• No unsolicited "flexibility" or configurability
• No error handling for scenarios that cannot happen

The litmus test: Would a senior engineer look at it and say "this is overcomplicated"? If so, cut it.

Principle 3: Surgical Edits

The problem: You ask the AI to fix one bug, and it fixes the bug and then casually refactors the neighboring code too — renames variables, deletes comments. It touched 30 places, 25 of which had nothing to do with your request.

The rules:

• Touch only the parts you were asked to touch
• Match the project's existing code style
• Mention unrelated problems when you spot them, but don't act on them
• Clean up code your change made unused, but don't touch problems that existed before

Principle 4: Goal-Driven

The problem: AI is great at "looping until it passes", but telling it the concrete steps actually constrains what it can do.

The rules:

• Give acceptance criteria, not steps
• New feature: write the test cases first, then make every test pass
• Bug fix: first write a test that reproduces the bug, then make it pass
• Complex task: lay out a step-by-step plan first, with a verification method for each step

This is the highest-leverage principle of the four when coding with AI. The clearer the acceptance criteria, the longer the AI can execute on its own, and the less often you need to step in.

How to Use It

1. Put the CLAUDE.md file in the project root
2. AI coding agents automatically read it and follow its rules
3. You can also modify and extend the rules to fit your own needs

# Example: adding project-specific rules to CLAUDE.md

## Project Conventions
- Use TypeScript strict mode
- Name component files in PascalCase
- Keep API endpoints together under src/api/
- Write tests before building new features

Why It Went So Viral

As the developer Kraggich put it: "A Markdown file topping the trending chart shows that the bottleneck is no longer the model — it's the scaffolding around the model. These 'glue' layers are the product itself."

Another developer ran the numbers: the model picked the wrong branch and ran for 40 minutes only to slam into a wall. Clarifying up front would have taken 30 seconds.

Karpathy himself said that within just a few weeks, his coding workflow flipped completely from "80% hand-written + 20% AI-assisted" to "80% handed to agents + 20% patching things up myself". This CLAUDE.md is the key tool that makes that flip genuinely reliable.