A single CLAUDE.md file reached 127K GitHub stars because it addresses a problem developers keep seeing with AI coding agents: messy behavior.
The repo is forrestchang/andrej-karpathy-skills. It takes a few of Andrej Karpathy’s observations about LLM coding failures and turns them into instructions that Claude Code can read before working on a project.
It takes a few of Karpathy’s observations about LLM coding failures and turns them into instructions that Claude Code can read before working on a project.
GitHub currently shows the repo at 127K stars and 12.9K forks.
Andrej Karpathy Skills GitHub. Image by Jim Clyde Monge
The file focuses on four principles:
- Think before coding.
- Keep the solution simple.
- Make surgical changes.
- Define success criteria before implementation.
Those rules map directly to common agent failures. Wrong assumptions. Bloated abstractions. Unrelated edits. Weak verification.
What is CLAUDE.md?
CLAUDE.md is a markdown file that Claude Code reads as a persistent project context. Anthropic’s own docs describe it as a way to give Claude persistent instructions across sessions. Claude Code loads these files at the start of a conversation, alongside other memory systems like auto memory.
That means CLAUDE.md is not just a note for humans. It becomes part of the agent’s working context.
You can use it to tell Claude things like:
## Project commands
- Build: npm run build
- Test: npm test
- Lint: npm run lint
You can also include project-specific rules:
## API conventions
- API errors return { error: string, code: number }
- Dates are stored in UTC
- Feature flags live in config/flags.ts
The important part is that CLAUDE.md should contain information Claude needs in every session. Anthropic recommends adding things when Claude repeats the same mistake, when a code review catches something Claude should have known, or when you keep typing the same correction again and again.
A good CLAUDE.md is not a dumping ground for every preference you have. It is closer to an operating manual for the agent. It should contain a durable context. Build commands. Test commands. Repo conventions. Security rules. Common traps. Repeated lessons from past failures.
The viral repo takes that idea and strips it down even further.
Instead of starting with project architecture, it starts with behavior.
Here is the full CLAUDE.md file from the repo:
# CLAUDE.md
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
## 1. Think Before Coding
**Don't assume. Don't hide confusion. Surface tradeoffs.**
Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
## 2. Simplicity First
**Minimum code that solves the problem. Nothing speculative.**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
## 3. Surgical Changes
**Touch only what you must. Clean up only your own mess.**
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.
When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
## 4. Goal-Driven Execution
**Define success criteria. Loop until verified.**
Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]2. [Step] → verify: [check]3. [Step] → verify: [check]
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
---
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
AI coding agents often fail at execution discipline.
They make silent assumptions, overbuild small fixes, touch unrelated files, rewrite comments, change formatting, and mark tasks as done without verification. The result may look fine in chat, but the diff usually exposes the problem.
A one-file bug fix becomes a six-file review. A small validation change becomes a new abstraction. A quick patch creates behavior changes outside the requested scope.
The CLAUDE.md file sets stricter rules before Claude Code edits the repo.
Here’s what each principle means:
1. Think before coding
This rule targets silent assumptions.
A request like “add validation” can mean client-side validation, server-side validation, schema validation, API validation, test coverage, error messages, or input sanitization.
Claude should not pick one silently. It should state assumptions, surface ambiguity, and ask when the request is unclear.
For non-trivial tasks, one clarification is cheaper than cleaning up the wrong implementation.
2. Simplicity first
This rule targets overengineering.
AI agents often turn small changes into reusable modules, new abstractions, or unnecessary refactorings. That adds names, tests, docs, maintenance, and more behavior to reason about.
The rule is simple: write the minimum code needed. No extra features. No abstraction for single-use code. No configurability unless the task requires it.
3. Surgical changes
This rule targets noisy diffs.
Claude should only touch the code required by the task. No nearby cleanup. No unrelated formatting changes. No variable renames based on preference. No comment rewrites unless they are part of the requested change.
If Claude creates unused imports or orphaned variables, it should remove them. If dead code already existed, it should mention it instead of deleting it.
4. Goal-driven execution
This rule targets weak completion.
“Fix the bug” is too vague. A better instruction is: write a failing test that reproduces the bug, make it pass, then run the relevant test command.
“Add validation” is also weak. A better version is: reject invalid inputs, show the expected error state, and add tests for valid and invalid cases.
Clear success criteria give the agent a target to loop against. Without that, it may stop when the code looks plausible instead of being verified.
What I would add on top of the four rules
The four rules are a good baseline, but I would not stop there for a real project. I would add a thin project layer.
Not a huge architecture essay. Not a full README copy. Not a giant style guide. Just the information that the agent cannot reliably infer or should not guess.
Here is a good structure:
# CLAUDE.md
## Behavior
Use the four Karpathy-inspired rules:
1. Think before coding.
2. Keep solutions simple.
3. Make surgical changes.
4. Define success criteria before implementation.
## Project commands
- Install: pnpm install
- Dev server: pnpm dev
- Typecheck: pnpm typecheck
- Lint: pnpm lint
- Test: pnpm test
- Build: pnpm build
## Project conventions
- Use existing component patterns before creating new ones.
- API errors must return { error: string, code: string }.
- Do not add new dependencies without asking.
- Do not edit generated files.
- Do not change database migrations after they have been committed.
## Watch out
- Auth logic lives in src/lib/auth.
- Payment webhook tests require local environment variables.
- Do not import from internal server modules in client components.
That is enough for many projects.
The uploaded source article also points out that project-specific context should focus on build commands, conventions the code does not show, and lessons from past failures. It warns against duplicating things the agent can already read from the codebase.
That is a good rule.
- Do not paste your entire architecture document into
CLAUDE.mdif Claude can inspect the folders. - Do not list every dependency if Claude can read
package.json. - Do not explain every component if the code is already clear.
- Do not include stale notes that nobody maintains.
Use the file for high-leverage context.
Why developers starred it
The repo went viral because the fix is small and the pain is common.
Most developers using AI coding tools have seen the same issues:
- The agent guesses instead of asking.
- The agent writes more code than needed.
- The agent edits unrelated files.
- The agent stops without strong verification.
The repo gives developers something they can copy into a project in minutes.
No new framework. No new toolchain. No model change. No benchmark setup.
Just a file that improves the agent’s default behavior.
That low-friction setup is a big reason it spread. Developers do not need another complicated agent framework to test the idea. They can add the file, run Claude Code, and inspect whether the diffs get cleaner.
How to use it
The repo supports two main usage paths.
The first is a Claude Code plugin. You add the marketplace, then install the andrej-karpathy-skills plugin.
To install via the marketplace, open Claude Code and run the following command:
/plugin marketplace add forrestchang/andrej-karpathy-skills
Andrej Karpathy Skills installation. Image by Jim Clyde Monge
