A Deep Dive into Karpathy's AI Coding Rules: Why a 65-Line Markdown File Earned 16k Stars

Andrej Karpathy — former Tesla AI Director and OpenAI co-founder — commands attention with every word he says in the AI community. He posted a tweet about his AI coding experience that racked up 7.63 million views and over 39,000 likes. Shortly after, a developer systematized his observations into four actionable rules, wrote them into a mere 65-line Markdown file, and dropped it on GitHub — where it promptly earned 16,000 stars.

The project, called Karpathy Skills, contains zero code and zero dependencies, yet it strikes right at the heart of every AI coding user's pain points. This article breaks down each of the four rules and explains why they matter so much.

Karpathy's Three Complaints: The Fatal Flaws of AI Coding

In the tweet that set social media ablaze, Karpathy candidly shared how his coding workflow has undergone a massive transformation: from 80% hand-written code with 20% AI assistance, to 80% AI-generated code with only 20% manual edits. He even said he's essentially "programming in English" now.

But while enjoying the productivity gains, he pulled no punches in calling out three fatal problems with AI coding:

AI Coding Problem #1: Wrong Assumptions

Karpathy's exact words: "The models will make wrong assumptions for you and then run with them without looking back." They don't manage their own confusion, don't seek clarification, don't surface contradictions, don't present trade-offs, and don't push back when they should.

This means when you give a vague requirement, the AI won't stop to ask "what exactly do you want?" — it just picks a direction on its own and charges full speed ahead.

AI Coding Problem #2: Over-Complication

AI has a particular fondness for over-complicating code and APIs — inflating abstraction layers and leaving dead code uncleaned. A problem solvable in a hundred lines? It'll write a thousand. This kind of "show-off coding" is catastrophic in real-world engineering, because every extra line of code adds maintenance cost.

AI Coding Problem #3: Collateral Damage

AI sometimes modifies or deletes comments and code it doesn't fully understand, even when they're completely unrelated to the current task. You ask it to fix a bug, and it might "optimize" half the file along the way, introducing new problems.

Anyone who's used AI for coding will deeply relate to all three of these issues.

Four AI Coding Rules: From Complaints to Actionable Solutions

Developer Forrest Cheung did something clever: he systematized Karpathy's complaints into four actionable behavioral rules and wrote them into a CLAUDE.md file. Simply drop this file into your project, and the AI's behavior changes significantly.

Rule 1: Think Before You Code (Addresses "Wrong Assumptions")

The core principle: Don't assume, don't hide confusion, surface trade-offs.

Four specific guidelines:

• State your assumptions explicitly; if unsure, ask
• If multiple interpretations exist, list them all — don't silently pick one
• If a simpler approach exists, say so; push back when appropriate
• If something is unclear, stop, explain what's unclear, and ask

Example: A user says "add a user export feature." The wrong approach is for the AI to assume exporting all users, writing to a local file, in JSON format. The right approach is to ask first: Export all users or only filtered results? Browser download or background task? Which fields to include? How large is the dataset?

The essence of this rule is transforming the AI from an "executor" into a "collaborator" — aligning on requirements before writing any code.

Rule 2: Keep It Simple (Addresses "Over-Complication")

The core principle: Solve the problem with the least code possible. No speculative development.

Five specific guidelines:

• Don't add features that weren't requested
• Don't create abstractions for single-use code
• Don't add flexibility or configurability that wasn't asked for
• Don't add error handling for scenarios that will never happen
• If you wrote two hundred lines but fifty would suffice, rewrite

The key litmus test: Would a senior engineer consider this code over-engineered? If the answer is yes, simplify.

Example: A user says "add a discount calculation function." The wrong approach is building a full strategy pattern — abstract classes, factory pattern, configuration classes, totaling fifty-plus lines. The right approach is three lines of code in a single function.

This rule directly targets the classic anti-pattern of "premature abstraction" in software engineering — and AI's tendency toward this is especially severe.

Rule 3: Surgical Changes (Addresses "Collateral Damage")

The core principle: Only touch what must be touched. Only clean up what you caused.

Four specific guidelines:

• Don't improve adjacent code comments or formatting
• Don't refactor things that aren't broken
• Match the existing code style, even if you'd do it differently
• If you spot unrelated dead code, mention it — don't delete it

There's an important distinction here: if your changes cause certain imports or variables to become orphaned, you should clean those up. But pre-existing dead code? Don't touch it unless asked.

The ultimate litmus test: Every single line changed should be directly traceable to the user's request.

Example: A user says "fix the bug where an empty email crashes the validator." The wrong approach is also tweaking comments, adding docstrings, enhancing email validation logic, and adding username validation. The right approach is changing only the two or three lines that handle empty emails — not a single character more.

Rule 4: Goal-Driven Execution (An Additional Distilled Insight)

The core principle: Define success criteria, then loop until verification passes.

This is the most essential part of the entire project. Karpathy has a famous quote: "LLMs are particularly good at looping until they achieve a goal. Don't tell it what to do — give it success criteria and watch it deliver."

The approach is to convert imperative tasks into verifiable goals:

• "Add validation" → Write a test with invalid input, then make it pass
• "Fix the bug" → Write a test that reproduces the bug, then make it pass
• "Refactor X" → Ensure tests pass both before and after the refactor

For multi-step tasks, create a brief plan with a verification checkpoint after each step. Strong success criteria let the LLM loop independently; weak success criteria (like "make it work") require constant clarification.

Why Did a Markdown File Go Viral with 16k Stars?

This project's explosion wasn't accidental — it was the convergence of multiple factors:

1. Precisely hitting pain points: Everyone who codes with AI has experienced these problems, creating instant resonance when they see the rules
2. Celebrity effect: Karpathy's authority in the AI field provides natural credibility
3. Extremely low barrier to entry: One file, one command to install, zero learning curve
4. Comprehensive real-world examples: The project includes 14+ code comparison examples — not empty theory
5. Perfect timing: It caught the wave of the plugin ecosystem explosion for AI coding tools like Claude Code

Summed up in a formula: Real pain points + Celebrity endorsement + Minimal solution + Solid examples = Viral spread.

Final Thoughts

This project's success reveals a deeper truth: The bottleneck in AI coding isn't AI's capability — it's how humans collaborate with AI. When we constrain AI's behavior with the right rules, it transforms from an "unreliable intern" into a "dependable collaborator."

65 lines of Markdown, not a single line of code, yet it may boost your AI coding efficiency more than many complex tools ever could. That in itself is the best footnote to the "Keep It Simple" principle.