The Text File That Broke GitHub Trending: Inside the 91,000-Star CLAUDE.md
You ask your AI coding assistant to fix a bug. It fixes the bug, refactors three unrelated functions, deletes a comment it didn’t understand, and ships you a PR with 400 changed lines. You asked for 10. Sound familiar?
That exact frustration, shared by tens of thousands of developers, is why a single markdown file named CLAUDE.md became the second most-starred repository on April 13, 2026. Not a framework. Not an SDK. Not a library with a flashy website. A text file. Sixty-five lines. 2.3 kilobytes. And it collected 5,828 stars in a single day before eventually crossing 91,200 stars total.
The repo is forrestchang/andrej-karpathy-skills, and if you use Claude Code, Cursor, or any AI coding agent for serious work, you need to understand what it does and why it works.
Why 91,000 Developers Starred a Markdown File
This repository crossed 91,000 stars, accumulated 8,700 forks, and attracted 472 watchers : for a file you could read on your phone during a coffee break.
The signal that matters most isn’t the total count. It’s the velocity. Seven out of seven tracked platforms GitHub, Hacker News, Reddit, X, AI YouTube, Tech YouTube, and Substack , all lit up on the same day. That kind of synchronized response across completely different communities is extraordinarily rare. It tells you something: a lot of people had the same problem, didn’t have a name for it, and recognized the solution the moment they saw it.
The problem Andrej Karpathy named in a January 2026 post on X started this entire chain reaction. Karpathy, co-founder of OpenAI and the person who coined the term “vibe coding,” had been using Claude Code heavily and started writing down what bothered him. His observations were blunt: the models make wrong assumptions without checking, they overcomplicate code, they touch things they shouldn’t. Developer Forrest Chang read that post and did something practical. He converted those observations into a structured CLAUDE.md configuration file that AI agents actually read and follow. Not a blog post. Not a tweet thread. A machine-readable file.
That’s why it spread. It solved a problem every professional AI user had already felt.
The Four Karpathy Principles, Explained
The entire CLAUDE.md file distills Karpathy’s frustrations into four principles. Each one targets a specific failure mode. Understanding each principle tells you exactly why your AI assistant has been misbehaving.
The first principle is “Think Before Coding.” The core instruction is simple: don’t assume, don’t hide confusion, surface tradeoffs. LLMs pick an interpretation silently and sprint toward implementation. This principle forces the agent to state its assumptions explicitly, present multiple interpretations when ambiguity exists, push back if a simpler approach is available, and stop cold when something is unclear rather than guessing. The downstream effect is fewer rewrites. When the agent asks before acting, you don’t spend an hour undoing confident mistakes.
The second principle is “Simplicity First.” The guideline reads: 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. The built-in litmus test is sharp: “Would a senior engineer say this is overcomplicated?” If yes, rewrite it. This directly targets what Karpathy called building “a bloated construction over 1000 lines when 100 would do.”
The third principle, “Surgical Changes,” is the one most developers describe as the biggest immediate win. Touch only what you must. Clean up only your own mess. When editing existing code, don’t improve adjacent code or comments, don’t refactor things that aren’t broken, match the existing style even if you’d do it differently. The verification test is unambiguous: every changed line should trace directly to the user’s request. If a line changed and you can’t explain why the user’s request required it, that line shouldn’t have changed.
The fourth principle is “Goal-Driven Execution,” and it’s where the insight gets genuinely interesting. Instead of telling the AI what to do, you give it success criteria and let it loop. “Add validation” becomes “write tests for invalid inputs, then make them pass.” “Fix the bug” becomes “write a test that reproduces it, then make it pass.” This is exactly what Karpathy observed: “LLMs are exceptionally good at looping until they meet specific goals.” The principle captures that power deliberately. Weak criteria require constant clarification. Strong criteria let the agent run.
The Origin Story: One Tweet That Became a Movement
Karpathy’s January 2026 post wasn’t a product launch or a research paper. It was notes. Personal, specific, slightly exasperated observations from someone who had moved from 80% manual coding to 80% agent coding in a matter of months and kept running into the same walls.
He wrote that agents don’t manage their confusion, don’t seek clarifications, don’t surface inconsistencies, and don’t push back when they should. He wrote that they overcomplicate code, bloat abstractions, and sometimes remove comments and code they don’t fully understand as side effects of unrelated changes. These weren’t abstract criticisms. They were the specific, recognizable failures that anyone using AI coding agents daily had already catalogued in frustration.
What made Forrest Chang’s response so effective is that he didn’t add commentary or interpretation. He took the structure of Karpathy’s complaints and mapped each one directly to a behavioral instruction. The “wrong assumptions” complaint became the “Think Before Coding” principle. The “overcomplicate code” complaint became “Simplicity First.” The “change things they shouldn’t” complaint became “Surgical Changes.” The observation about looping toward specific goals became “Goal-Driven Execution.” The mapping is clean enough that reading the CLAUDE.md file alongside Karpathy’s original post feels like watching a translation happen in real time.
The repo also includes a Cursor rules variant (.cursor/rules/karpathy-guidelines.mdc), making the same guidelines work whether you use Claude Code or Cursor, and a Claude Code plugin for applying the principles across all your projects rather than per-repo.
How to Install It in Three Minutes
Getting this into your workflow takes less time than reading most README files. There are two paths depending on how you work.
If you want the guidelines to apply across every project you touch in Claude Code, install it as a plugin. Open Claude Code and run
/plugin marketplace add forrestchang/andrej-karpathy-skills, then follow with/plugin install andrej-karpathy-skills@karpathy-skills. Done. Every project you open now starts with these behavioral guidelines already loaded.
If you prefer per-project control, which gives you the flexibility to layer project-specific rules on top, use curl. For a new project, run curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md. For an existing project that already has a CLAUDE.md, append instead of overwriting: echo "" >> CLAUDE.md && curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md.
The README includes an important customization note: these guidelines are designed to be a base layer, not a complete solution. Add your project-specific rules on top. TypeScript strict mode requirements, test coverage thresholds, error handling patterns, specific file paths the agent should know about. The Karpathy principles handle universal behavioral discipline; your project rules handle domain-specific context.
One technical constraint worth knowing: keep your full CLAUDE.md under 200 lines. The official Anthropic documentation notes that agent compliance drops noticeably past that threshold. If your file grows, convert rules the agent already follows reliably into hooks (which are deterministic), and trim anything redundant. The CLAUDE.md file is advisory, not guaranteed. Hooks are how you enforce things that must happen every single time.
What 91,000 Stars Actually Tells You About AI Coding in 2026
Here’s the thing that gets underplayed in the coverage of this repo’s growth. The fact that it went viral isn’t really about this repo. It’s about where the developer community is in its relationship with AI coding tools.
A year ago, the conversation was about whether AI could write code at all. Today, the conversation is about behavioral discipline. Developers aren’t asking “can Claude Code do this?” They’re asking “how do I make Claude Code do this the right way every time?” That’s a fundamentally different question, and it’s a sign of a maturing user base. When the community starts building meta-tooling , files that shape how the AI tool behaves, rather than the AI tool itself , that’s a platform hitting maturity.
The andrej-karpathy-skills repo solves what the Dev.to coverage called “the behavioral discipline problem.” Other repos in the same viral wave solved adjacent problems: the amnesia problem (claude-mem), the persistence-and-growth problem (hermes-agent), the community handbook problem (claude-code-best-practice). Four different repos, each addressing a different frustration, all going viral on the same day. That’s not coincidence. That’s a platform reaching the scale where its pain points are shared widely enough to spawn a parallel ecosystem of fixes.
The repo’s tradeoff note is also worth taking seriously: these guidelines bias toward caution over speed. For trivial tasks , obvious one-liners, simple typo fixes : you don’t need the full rigor. Use judgment. The point is reducing costly mistakes on non-trivial work, not slowing down everything. When you’re building something that actually matters, when a wrong assumption or a bloated abstraction or an unintended side effect costs you real time, that’s when four principles in one text file start paying for themselves.
The Real Lesson Behind Four Simple Principles
91,000 developers starred a markdown file. That tells you the problem is real, widespread, and expensive. It also tells you the solution doesn’t have to be complicated.
If you try one thing from this article, add this file to your next project before your next Claude Code session. Not after. Before. Watch what changes in the first few interactions. Count how many times the agent asks a clarifying question instead of assuming. Notice whether the PR diff is clean and traceable. Check whether the code it writes matches the complexity level of what you asked for.
These four principles won’t fix every AI coding problem. Nothing will. But they address the specific, predictable, repeatable failures that made tens of thousands of developers frustrated enough to search for a solution and grateful enough when they found it to star it, fork it, and share it across seven different platforms in a single day.
The AI coding era isn’t about whether the model is capable. It’s about whether you can steer it. That’s the skill that actually scales.