Andrej Karpathy's CLAUDE.md: The 65-Line File With 100K GitHub Stars That Changed How Developers Use AI Coding Agents in 2026

May 3, 2026

Clap

Copy link

Written by

Jay Kim

Andrej Karpathy's CLAUDE.md: The 65-Line File With 100K GitHub Stars That Changed How Developers Use AI Coding Agents in 2026

Andrej Karpathy's CLAUDE.md file hit 100K+ GitHub stars with just four principles. Here's what it does, why it went viral, and how creators can apply it.

Every developer using AI coding tools in 2026 has felt the same frustration. You ask the AI to add a feature. It makes assumptions you never agreed to. It overengineers the solution. It touches code you never asked it to change. And then you spend more time fixing the AI's output than it would have taken to write the code yourself.

Andrej Karpathy, one of the most respected voices in artificial intelligence, felt the same thing. And when he shared his frustrations publicly, something unexpected happened. Developer Forrest Chang distilled Karpathy's viral observations about LLM coding pitfalls into a single, actionable CLAUDE.md file.[2] That file now has over 109,000 GitHub stars, making it one of the most starred repositories in GitHub history.

No framework. No library. No SDK. Just a plain markdown file you drop into your project root. And it fundamentally changes how AI writes code for you.

This post breaks down what the file does, why it went viral, how the four principles inside it work, and what this means for anyone using AI tools to create content, write code, or build products in 2026.

Who Is Andrej Karpathy and Why His Opinion Matters

Before we get into the file itself, you need to understand why one person's coding notes triggered a global phenomenon.

The repo traces directly to a viral tweet by Andrej Karpathy, co-founder of OpenAI, former AI lead at Tesla, and the person who coined the term "vibe coding."[2] He is not a random developer complaining about AI tools on Twitter. He is one of the people who built the foundations of the AI systems everyone uses today.

Karpathy said on January 26, 2026: "Easily the biggest change to my basic coding workflow in 2 decades of programming, and it happened over the course of a few weeks."[4] Karpathy admitted that his workflow changed dramatically in December 2025. In November, he wrote 80% of his code manually; in December, only 20%. The rest is done by agentic AI systems.[6]

But despite this massive shift toward AI-generated code, Karpathy was not blindly optimistic. In the past, he's openly questioned their maturity, arguing that today's agents are unreliable and far from fully autonomous. He's saying these tools are too useful to ignore, but he's also clear they're still messy, fragile, and imperfect.[7]

This tension between "AI is incredibly useful" and "AI keeps making the same mistakes" is exactly what created the CLAUDE.md phenomenon.

If you have been creating content with AI tools, whether it is generating YouTube thumbnails, producing AI music, or writing scripts for YouTube Shorts, you have probably experienced a similar dynamic. The AI gets you 80% of the way, but the last 20% is where things go wrong because of silent assumptions and overcomplication. That same dynamic plays out in coding, and Karpathy's CLAUDE.md file addresses it directly.

What Is CLAUDE.md and Why Does It Exist?

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.[10]

CLAUDE.md is a markdown file you add to your project root that Claude Code reads at the start of every session. Use it to set coding standards, architecture decisions, preferred libraries, and review checklists.[1]

In simpler terms, a CLAUDE.md file is a set of instructions you give to Claude Code (Anthropic's AI coding agent) before it starts working on your project. It shapes the AI's behavior, telling it what to do, what not to do, and how to approach your specific codebase.

This concept is similar to how effective prompts improve AI image generation or how detailed prompts produce better cinematic video results. The better your instructions to the AI, the better the output. The CLAUDE.md file is essentially the developer's version of a well-crafted prompt.

What Did Karpathy Actually Say? The Original Observations

On January 26, 2026, Karpathy posted a thread on X (formerly Twitter) sharing notes from weeks of intensive Claude Code usage. He wrote: "A few random notes from claude coding quite a bit last few weeks. Coding workflow. Given the latest lift in LLM coding capability, like many others I rapidly went from about 80% manual+autocomplete coding and 20% agents in November to 80% agent coding and 20% edits+touchups in..."[3]

His observations about how LLMs fail when writing code were specific and reproducible. From the repo itself, Karpathy identified three core failure patterns:

The first was about silent assumptions. The models make wrong assumptions on your behalf and just run along with them without checking. They do not manage their confusion, do not seek clarifications, do not surface inconsistencies, do not present tradeoffs, and do not push back when they should.

The second was about overcomplication. They really like to overcomplicate code and APIs, bloat abstractions, and do not clean up dead code. They implement a bloated construction over 1,000 lines when 100 would do.

The third was about collateral damage. They still sometimes change or remove comments and code they do not sufficiently understand as side effects, even if those changes are orthogonal to the task.

These observations highlight three fundamental problems with LLM coding behavior: Hidden Assumptions where LLMs silently interpret ambiguous requests without surfacing their assumptions, Overengineering where they create complex abstractions and speculative features that were not requested, and Collateral Changes where they modify unrelated code while performing simple tasks.[6]

These are not theoretical concerns. Anyone who has used AI tools extensively has experienced some version of this, whether in coding or in content creation workflows. When you ask an AI image generator for a "professional YouTube thumbnail" without being specific about style, contrast, and composition, you get unpredictable results for the same reason: the AI fills in the blanks with assumptions rather than asking for clarification. That is why detailed prompting guides for thumbnails consistently outperform vague requests.

The Four Principles: How the CLAUDE.md File Works

Developer Forrest Chang (Jiayuan Zhang) let Claude Code turn Karpathy's post into agent skills. It first generated a bunch of skill files and around 800 lines of descriptions. Then he let it use these agent skills to review itself. It cut itself down to about 70 lines of clean, solid instructions.[7]

The result is a file built around four core principles, each targeting a specific failure mode that Karpathy identified.

Principle 1: Think Before Coding

This principle directly addresses the silent assumption problem. Before the AI starts generating code, it must state its assumptions explicitly. If there are multiple valid interpretations, it should present all of them instead of silently choosing one. If something is unclear, it should stop and ask for clarification rather than guessing.

Before generating code, the AI must state assumptions explicitly, present multiple interpretations when ambiguous, and ask questions when uncertain. For example: "I see two approaches: Option A uses a simple regex for basic validation, Option B implements RFC 5322 compliance with DNS checking. Which fits your needs?" No more silent guesses.[4]

This is functionally the same principle that drives better results in any AI tool. When you write prompts for AI-generated content, specificity eliminates ambiguity. The Think Before Coding principle forces the AI to seek that specificity rather than assuming it.

Principle 2: Simplicity First

This principle combats the overengineering tendency. The instructions are direct: write the 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 was not requested. No error handling for impossible scenarios.

The repo includes a simple test: if 200 lines could be 50, rewrite it. Would a senior engineer say this is overcomplicated? If yes, simplify.

This principle resonates beyond coding. In content creation, the same overcomplication tendency shows up when AI generates YouTube Shorts scripts that are too complex or music prompts that include unnecessary elements. Simplicity produces better results across all AI-assisted creative workflows.

Principle 3: Surgical Changes

When editing existing code, the AI should touch only what it must. It should not "improve" adjacent code, comments, or formatting that the user did not ask to change. It should not refactor things that are not broken. It should match existing style, even if the AI would have done it differently.

The file includes a critical distinction: when your changes create orphaned imports or unused variables, remove them because your changes caused them. But do not remove pre-existing dead code unless specifically asked.

The test is clean: every changed line should trace directly to the user's request.

Principle 4: Goal-Driven Execution

This is arguably the most powerful principle, and it comes directly from one of Karpathy's key insights. From Karpathy: "LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."[3]

Instead of giving the AI imperative instructions ("add validation"), transform them into declarative goals with verification ("write tests for invalid inputs, then make them pass"). Instead of "fix the bug," say "write a test that reproduces it, then make it pass."

Strong success criteria let the LLM loop independently. Weak criteria ("make it work") require constant clarification.[3]

This principle is directly applicable to AI content creation as well. When using Text2Shorts to generate YouTube Shorts, providing specific goals ("create a 45-second explainer about sleep cycles with a hook in the first 3 seconds") produces dramatically better results than vague instructions ("make a video about sleep").

Why a Single Markdown File Got 100K+ Stars

The growth of this repository has been extraordinary. 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. Just a text file you drop into your project root.[4]

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.[10]

Several factors explain the viral growth.

First, the timing was right. Karpathy wrote that "LLM agent capabilities have crossed some kind of threshold of coherence around December 2025 and caused a phase shift in software engineering."[5] Millions of developers were suddenly using AI coding agents for the first time and experiencing the exact frustrations Karpathy described.

Second, the deeper question is not what the file does but 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.[10]

Third, and most importantly, the four principles in the file are not novel. They are articulations of pain points that anyone who's used Claude Code for more than a week has felt. The virality is recognition, not discovery.[10]

The same recognition factor drives viral content across all platforms. When a YouTube Short captures a feeling everyone has experienced, it spreads because viewers see themselves in it. The CLAUDE.md file spread for the same reason: every developer recognized their own frustrations in Karpathy's observations.

How Developers Are Using It in Practice

There are two main ways to install the Karpathy guidelines. The recommended method is as a Claude Code plugin, which makes the skills available across all your projects. From within Claude Code, you add the marketplace and install the plugin. The alternative is to add the CLAUDE.md file directly to a specific project's root directory.

The official docs note that you should keep your CLAUDE.md under 200 lines, as compliance drops off past that threshold.[10] From the official best practices documentation: CLAUDE.md is advisory, meaning Claude follows it about 80% of the time.[10] For anything that must happen deterministically (linting, formatting, security checks), make it a hook. The two mechanisms are complementary, not competing.[10]

Developers are merging Karpathy's four principles with their own project-specific guidelines. The file is designed to be customizable. You can add sections for your specific technology stack, testing framework, coding standards, and architecture decisions while keeping the core behavioral principles intact.

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.[10]

The Broader Shift: From Vibe Coding to Agentic Engineering

The Karpathy CLAUDE.md file represents something larger than a single popular repository. It marks a transition in how the developer community thinks about AI-assisted work.

When Karpathy coined "vibe coding" in early 2025, it described a loose, conversational way of prompting AI. By 2026, the community has matured this into "agentic engineering," a discipline where developers treat AI as a partner requiring clear objectives, defined boundaries, and rigorous testing. The andrej-karpathy-skills repo represents this evolution.[2]

It is not about limiting what AI can do. It is about channeling what it can do through principles that produce better outcomes.[2]

This maturation is happening across every AI-powered creative field, not just coding. In 2025, creators were experimenting with AI image generators and AI video tools in a "vibe" mode, trying random prompts and hoping for good results. In 2026, the most successful creators are the ones who have developed structured, repeatable workflows. They use specific prompt templates for thumbnails, follow proven formats for viral Shorts, and build their content pipelines around tested best practices.

The lesson from Karpathy's CLAUDE.md is universal: the better your instructions to the AI, the better the output. Whether you are coding a web application or creating content, moving from vague prompting to structured, principle-driven instructions is the single biggest quality improvement you can make.

What This Means for Content Creators Using AI

You do not need to be a developer to benefit from Karpathy's four principles. The exact same behavioral problems he identified in AI coding agents show up in every AI content creation tool.

Silent assumptions in content creation. When you ask an AI to generate a YouTube thumbnail with a vague prompt, it fills in dozens of creative decisions without asking you. Colors, composition, facial expression, text placement, background style: all chosen by the AI based on training data patterns rather than your specific needs. The solution is the same as Principle 1: be explicit about your assumptions and force specificity in your prompts.

Overcomplication in AI outputs. AI image generators and cinematic video tools often produce outputs that are visually busy and overcomplicated when a simpler, cleaner result would have been more effective. Principle 2 applies directly: prompt for the minimum visual elements that communicate your message, nothing speculative.

Collateral changes in iterative editing. When you ask an AI to make one change to an image using inpainting tools, it sometimes alters parts of the image you wanted to keep. Principle 3 is surgical changes: be explicit about what should change and what should remain untouched.

Vague goals producing vague results. When you tell an AI "make me a YouTube Short" without clear success criteria, the output is unpredictable. Principle 4 says to define success criteria first. For a Short, that might mean: hook in the first 2 seconds, one clear takeaway, text on screen throughout, loopable ending. Specific goals produce specific results.

How to Apply These Principles to Your AI Content Workflow

Here is a practical framework for applying Karpathy's four principles to content creation with AI tools like Miraflow AI.

Think Before Prompting. Before entering any prompt into an AI tool, write down what you actually want. What is the specific style? What mood? What colors? What should be in the frame and what should not? If you are generating a YouTube thumbnail, specify the facial expression, the background color, the text style, and the composition before you type a single word into the prompt box.

Simplicity First in Prompts. The most effective AI prompts are detailed but not cluttered. Include the essential visual elements and nothing more. A thumbnail prompt that says "person looking shocked at laptop, bright yellow background, bold text saying WAIT WHAT, clean composition, no clutter" will outperform a prompt that tries to include fifteen different elements.

Surgical Edits When Iterating. When using AI image editing or inpainting, make one change at a time. If you need to change the background color, change only the background color. If you need to adjust the text, adjust only the text. Avoid "while you're at it" edits that compound across multiple elements.

Define Success Criteria Before Generating. Before you create any piece of content with AI, write down what "good" looks like. For a YouTube Short, your criteria might include: 30 to 45 seconds long, one clear hook in the first 3 seconds, text overlays on every scene, and a strong call to action at the end. Then prompt toward those criteria specifically.

This approach to AI content creation mirrors what top creators are already doing when they follow structured formats that consistently go viral or use proven thumbnail strategies instead of guessing.

The Bigger Picture: AI Agents Are Getting Better, But They Still Need Guardrails

Stack Overflow's 2025 survey shows 84% of developers use AI tools, yet trust has dropped from 40% to 29%.[5] This gap between usage and trust is exactly what the CLAUDE.md phenomenon addresses. People are using AI tools because they are useful, but they do not fully trust the output because of the behavioral problems Karpathy identified.

Developer Forrest Chang distilled Karpathy's viral observations into four principles that improve AI coding accuracy from 65-70% to 91-94%.[4] Whether those specific numbers hold in every case is debatable, but the directional claim is supported by widespread developer reports of improved output quality after implementing the guidelines.

At Anthropic itself, the majority of code is now written by Claude Code. Engineers focus on architecture, product thinking, and continuous orchestration: managing multiple agents in parallel, giving direction, and making the decisions that shape what gets built.[3]

The trajectory is clear. AI coding agents and AI content creation tools will continue to improve. But even as models get smarter, the need for structured instructions and clear behavioral guidelines will remain. The CLAUDE.md file is not a temporary patch for weak AI. It is a permanent layer of quality control that gets more valuable as AI capabilities increase, because the consequences of silent assumptions and overcomplication grow alongside the scope of what AI can do.

What Creators Should Watch for Next

The CLAUDE.md trend signals a broader shift that content creators should pay attention to.

AI tools across every category are moving toward customizable behavior files. Just as developers use CLAUDE.md to shape how AI writes code, expect content creation platforms to offer similar customization layers. Imagine a file that tells your AI image generator to always use specific color palettes, always place text in the upper third, and always use clean backgrounds. Some platforms already support this through saved style preferences and prompt templates.

The concept of "skills" that can be shared between users is growing rapidly. The Karpathy CLAUDE.md file can be installed as a plugin that applies across all projects. Similarly, communities of content creators are already sharing prompt packs for thumbnails, music prompt templates, and video script formulas that work as reusable "skills" for AI content generation.

The line between "coding with AI" and "creating content with AI" is blurring. Tools like Miraflow AI already provide the entire creative pipeline in one platform, from image generation to video creation to music production to YouTube thumbnail design. As these tools become more agentic (able to execute multi-step workflows autonomously), the same behavioral principles that Karpathy identified for coding will apply to every creative workflow.

Conclusion

Andrej Karpathy's CLAUDE.md file became one of the most starred repositories in GitHub history not because it contained revolutionary new technology. It went viral because it articulated, in clear and actionable terms, the frustrations that millions of people experience every day when working with AI tools.

The four principles in the file are deceptively simple. Think before acting. Keep things simple. Make surgical changes. Define success criteria upfront. These principles apply equally to AI coding agents, AI image generators, AI video tools, and every other AI-powered creative workflow.

The CLAUDE.md file is not a library anyone imports. It is a set of principles anyone can adapt. The recipient's agent customizes it for their specific needs. This is a new kind of open source: not open code, but open ideas.[2]

Whether you are a developer using Claude Code, a creator building YouTube Shorts with AI, or a marketer generating product videos and thumbnails, the core lesson is the same. The better your instructions to the AI, the better the output. Structured principles beat vague vibes every time.

If you are ready to apply these principles to your own content creation workflow, Miraflow AI provides every tool you need in one browser-based platform. From AI image generation and YouTube thumbnails to cinematic video, AI Shorts, and AI music, you can build your entire content pipeline with the same specificity and structure that makes Karpathy's CLAUDE.md so effective.

Frequently Asked Questions

What is Karpathy's CLAUDE.md file?

It is a single markdown configuration file created by developer Forrest Chang, based on Andrej Karpathy's observations about how AI coding agents fail. The file contains four behavioral principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) that you add to your project root to improve how Claude Code writes code.

Who created the andrej-karpathy-skills repository?

The repository was created by developer Forrest Chang (Jiayuan Zhang) on January 27, 2026, one day after Karpathy published his viral observations about LLM coding pitfalls. Karpathy identified the problems; Forrest Chang encoded the solutions into a practical file.

How many GitHub stars does the CLAUDE.md repo have?

As of May 2026, the forrestchang/andrej-karpathy-skills repository has over 109,000 stars, making it one of the most starred repositories in GitHub history despite containing only a single markdown file.

Do I need to be a developer to benefit from Karpathy's principles?

No. The four principles (think before acting, keep it simple, make surgical changes, define success criteria) apply to any AI-powered workflow. Content creators using AI image generators, video tools, and music generators can apply the same structured approach to get dramatically better results from their prompts.

What is Claude Code?

Claude Code is Anthropic's AI-powered coding agent that runs in your terminal, IDE, or browser. It reads your entire codebase, plans actions across multiple files, executes changes, runs tests, and iterates until the task is complete. The CLAUDE.md file shapes its behavior for your specific project.

How do I install the Karpathy CLAUDE.md file?

You can install it as a Claude Code plugin using the plugin marketplace, which applies the guidelines across all your projects. Alternatively, you can download the CLAUDE.md file and add it directly to any project's root directory.

Does CLAUDE.md work with tools other than Claude Code?

The repository includes a CURSOR.md file and Cursor project rules so the same guidelines apply in the Cursor editor. The underlying principles are tool-agnostic and can inform how you interact with any AI coding agent or content creation tool.

What did Karpathy mean by "vibe coding"?

Karpathy coined the term in early 2025 to describe a coding style where you tell the AI what you want and evaluate the result without reading the code. By 2026, the community has matured this into "agentic engineering" where developers treat AI as a partner requiring clear objectives, defined boundaries, and rigorous testing.

References