The Karpathy CLAUDE.md file promises fewer unnecessary changes and clearer questions from Claude Code. It’s just one short text file, and its GitHub repository has about 228,000 stars.
We wanted to see what it changes, so we ran the same four coding tasks with and without it. It did change Claude Code’s behavior, but only on two of the four tasks in a clear way.
Key takeaway: This file is free and easy to try. In our tests, it made Claude Code ask more on a vague request and add a test to one bug fix, but it didn’t change results on every task.
What the Karpathy CLAUDE.md File Is
It’s a set of behavior rules that Claude Code reads at the start of a session. A CLAUDE.md file gives Claude Code standing instructions for a project, so you don’t have to repeat them.
Despite the name, it isn’t published by Andrej Karpathy. It lives in a repository from the developer account forrestchang, which says the file is derived from Karpathy’s observations on LLM coding pitfalls.
| Rule | What it asks Claude Code to do |
|---|---|
| Think Before Coding | State assumptions and ask when something is unclear |
| Simplicity First | Write the minimum code, with no speculative features |
| Surgical Changes | Change only what the request needs |
| Goal-Driven Execution | Set a success check and loop until it passes |
The file sums up its third rule this way: “Touch only what you must. Clean up only your own mess.” It also warns of the tradeoff: “These guidelines bias toward caution over speed.”
How to Add the Karpathy CLAUDE.md to Your Project
The project’s GitHub repository gives two install routes, a plugin or a single file. We tested the single file, because it stays inside one project.
Use this command only if your project has no CLAUDE.md yet:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.mdIf you already have one, don’t use that command, because it would replace your file. Append the rules instead:
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.mdRead the file before you add it, then start a new Claude Code session in that folder. If you want to write your own rules instead, start with our CLAUDE.md template.
How We Tested the Guidelines in Claude Code
We used Claude Code 2.1.312 and Opus 5.5 on macOS on November 1, 2026. Each of the 24 runs started in a fresh copy of a small Node.js project, with no other project instructions.
For three tasks, we also wrote private tests that Claude Code never saw. The vague request had no right answer, so we read those results by hand.
What Changed With the Karpathy Guidelines
The Vague Request: This Was the Biggest Change
We asked, “Make the user export handle dates properly.” The sample data included 03/05/2024, which could mean March 5 or May 3.
Without the file, Claude Code wrote code in all three runs, adding 25 to 31 lines, and then told us what it had assumed. With the file, it stopped to ask in two of three runs.
All six runs noticed the problem with the date, so the file didn’t make Claude Code smarter here. It changed when you get to make the decision, which matters when a wrong guess is hard to spot.
The third run with the file made an 8-line change. It was much shorter, but unknown date text passed through unchanged, while all three runs without the file rejected it. Shorter code isn’t automatically better code.
The Messy File: Same Fix, One Useful Addition
This task was a trap. The file had dead code, an unused import, odd formatting and an old to-do comment around a simple discount bug.
All six runs changed the same single line and left everything else in that file alone. So Claude Code already stayed surgical here without any extra rules.
The difference was the test. All three runs with the file added a regression test, and none of the runs without it did. That makes the total change larger, but it’s a useful kind of larger.
The Retry Helper: A Small Difference
We asked for a function that retries a failed fetch up to 3 times, a request that leaves room to overbuild. No run in either setup added delays, settings or extra options.
Runs with the file added 10 to 12 lines to the code file, and runs without it added 12 to 17. The gap is small enough that three more runs could change it.
The Clear Bug: No Real Difference
We told Claude Code that parseDuration('1h30m') returned 3600 and should return 5400. All six runs produced the same code fix and added a test, so the file had nothing to improve here.
Does the CLAUDE.md File Slow Claude Code Down?
Not much in our runs, though the totals hide some variation between tasks.
| All 12 runs | Without the file | With the file |
|---|---|---|
| Total time | 274 seconds | 281 seconds |
| Output tokens | 24,504 | 24,104 |
| Claude Code’s cost estimate | $2.56 | $2.69 |
Stopping early on the vague task saved some time and tokens, so these totals don’t show the extra back-and-forth once you answer its questions. On a subscription, watch your usage limits and don’t treat the estimate as a bill.
What Our Test Doesn’t Prove
- Three runs per setup can show a pattern, but they can’t prove the file always helps.
- These were tiny projects. Long sessions and large codebases might behave differently.
- We tested one model. The repository’s last commit was in April 2026, so the file wasn’t written with Opus 5.5 in mind, and we can’t say how older models behave.
- We didn’t test the plugin version or the file’s Cursor setup.
Should You Use the Karpathy CLAUDE.md?
| If you | Our advice |
|---|---|
| Often write short or loose prompts | Try it, since this is where it helped most |
| Want more regression tests on bug fixes | Try it, or add one direct line asking for them |
| Want Claude Code to run with few interruptions | Be careful, because it may stop to ask more often |
| Already write detailed prompts | You may not notice much difference |
| Have a long, well-tuned CLAUDE.md | Copy only the rules you need |
If you want a shorter version, Think Before Coding and Goal-Driven Execution are the ones to start with, since those match the changes we saw. We didn’t test those rules on their own, so treat that as a starting point. For habits that matter just as much, see our Claude Code best practices.
Karpathy CLAUDE.md FAQs
Did Andrej Karpathy write this file?
The repository is from another developer, and it describes the file as derived from Karpathy’s observations. Don’t treat it as his official release.
Is the Karpathy CLAUDE.md free?
Yes, the file itself costs nothing. Its README says it’s MIT licensed, though we didn’t see a separate license file in the repository, so check that if licensing matters to your team.
Will it replace my existing CLAUDE.md?
Only if you use the curl -o command. Use the append command for an existing file, then remove any rules that conflict with your own.
Does the file work in the repository root only?
We tested it in the project root. For where else Claude Code reads these files, see the official Claude Code memory docs.
Do I need a plugin to use it?
No. A plugin is one route, but our tests used only the plain file. If you want a larger framework, compare it with Superpowers for Claude Code.
Conclusion
The Karpathy CLAUDE.md guidelines did change Claude Code’s behavior, but less than the star count might suggest. In our 24 runs, the clearest gains were asking before guessing on a vague request and adding a regression test to one bug fix, while the clear bug barely changed and all of our private checks passed either way. It’s worth a try if you often write loose prompts, as long as you read it first and judge it on your own diffs.
