CLAUDE.md: How One Markdown File Cut AI Coding Rework Rates from 41% to 11%

The Sweet Trap of AI Coding: Productivity Soars, But Rework Never Stops

Using Claude or Cursor to write code genuinely boosts productivity. But many developers share the same frustration: AI-generated code can be a disaster. It makes assumptions about your requirements and executes them with total confidence, turns 100-line solutions into 1,000-line bloated architectures, and quietly deletes code it doesn't understand.

A Markdown file with just a few dozen lines is changing all of that. It's called CLAUDE.md, and it has earned over 140,000 stars on GitHub. The core ideas behind it come from Andrej Karpathy — OpenAI co-founder and former Tesla AI Director — and were distilled into an actionable engineering spec by developer Zhang Jiayuan.

About Karpathy: Andrej Karpathy is one of the most influential practitioners in deep learning. He was a co-founding member of OpenAI and led early research on the GPT series. He later joined Tesla as Director of AI and Autopilot Vision, where he oversaw the development of Tesla's neural network perception systems. Known for explaining AI in engineer-friendly terms, his Stanford CS231n course has been studied by millions of developers worldwide. Karpathy's observations on AI coding carry particular weight because he is both a top-tier AI researcher and a hands-on builder of large-scale engineering systems — a dual perspective that lets him precisely identify the structural tension between "highly capable but uncontrollable" in AI-assisted programming.

The Three Fatal Problems Karpathy Identified in AI Coding

Karpathy points out that today's AI coding errors are no longer simple syntax mistakes. They are three deeper, systemic problems.

Problem 1: Wrong Assumptions — AI Acts Without Asking

Models make incorrect assumptions and execute them without hesitation. They don't manage their own confusion, don't seek clarification, don't surface contradictions, and don't present trade-offs. Say you ask to "add user authentication" — the AI might default to building a full OAuth system without ever asking: do you want simple email verification, or complex third-party login?

Problem 2: Over-Engineering — 100 Lines Becomes 1,000

AI genuinely loves making code complicated. It piles on abstractions, leaves dead code untouched, and insists on implementing a 1,000-line bloated architecture for something 100 lines could handle. What you end up with is an over-engineered monster — code that's hard to maintain, hard to understand, and hard to change.

This tendency isn't random error — it's an inevitable consequence of training data distribution. During pre-training, large language models absorb massive amounts of open-source code from GitHub, which carries a significant "showcase bias": developers tend to commit carefully designed code with complete abstraction layers and error handling, not simple one-off scripts. The model learns an implicit rule: "complex = professional = correct." On top of that, RLHF (Reinforcement Learning from Human Feedback) annotators tend to rate more feature-complete code higher. This training bias causes AI to systematically overestimate the engineering complexity required for simple tasks.

Problem 3: Irrelevant Edits — AI Quietly Changes Code You Didn't Ask It To Touch

AI sometimes modifies or deletes code and comments it doesn't fully understand, even when those parts are completely unrelated to the current task. Code review becomes a nightmare because you can't tell which changes were necessary and which ones the AI made "while it was at it."

What's the root cause of all three problems? AI lacks a clear behavioral contract. It doesn't know your engineering philosophy, doesn't know what "good enough" looks like, and only knows one direction — generate as much code as possible.

The Four Golden Rules of CLAUDE.md

Zhang Jiayuan's solution is straightforward: instead of trying to improve the AI model itself, give the AI a clear behavioral contract. These four rules directly address the three problems Karpathy identified.

How CLAUDE.md Works Technically: When Claude Code starts up, it automatically scans the project root directory and injects the contents of CLAUDE.md into the system prompt layer of the conversation. This means the file's content occupies the highest-priority position in the model's context window, taking effect before every conversation begins. Modern large language models typically have context windows of 100,000 to 200,000 tokens, and system prompt content exerts a sustained influence on the model's entire response style. This also explains why shorter CLAUDE.md files work better — overly long rules dilute the weight of each individual instruction, while concise constraints allow the model to follow them more consistently. This mechanism applies equally to Cursor's .cursorrules file and GitHub Copilot's custom instructions.

Rule 1: Think Before You Code

Core principle: No assumptions, no hidden confusion — surface the trade-offs.

This rule directly addresses the "wrong assumptions" problem by forcing the AI to articulate its understanding before taking action:

• State assumptions explicitly; ask rather than guess when uncertain
• Present multiple interpretations when ambiguity exists — don't silently pick one
• Proactively suggest a simpler approach if one exists
• Stop when confused, flag what's unclear, and ask for clarification

For example, if you say "optimize this function," without CLAUDE.md the AI defaults to adding caching, concurrency, and monitoring. With the rule in place, the AI first asks: when you say optimize, do you mean speed, memory, or readability? Where is the current bottleneck?

Rule 2: Simplicity First

Core principle: Solve the problem with the least code possible — don't over-speculate.

This rule directly counters AI's over-engineering tendency. At its core, it uses explicit constraints to push back against implicit training bias:

• Don't add features beyond what was requested
• Don't create abstractions for one-off code
• Don't add error handling for scenarios that will never happen
• If 200 lines can be written as 50, rewrite it

This rule forces the AI to ask itself: Would a senior engineer find this overly complex? If the answer is yes, rewrite it.

Rule 3: Surgical Edits

Core principle: Only touch what must be touched — clean up your own mess.

• When editing existing code, don't improve adjacent code, comments, or formatting
• Don't refactor things that aren't broken
• Match the existing style, even if you'd personally prefer something different
• If you notice unrelated dead code, mention it — but don't delete it

The key standard: every line changed should be directly traceable to the user's request.

Rule 4: Goal-Driven Execution

Core principle: Define success criteria, then loop until you get there.

This rule transforms imperative tasks into declarative goals — instead of saying "do this," you say "reach this state." The distinction has profound implications in software engineering: the imperative approach tells the AI "what steps to take," while the declarative approach tells it "what state to achieve." This aligns closely with the evolution of modern infrastructure tooling — the core design philosophy of Kubernetes, Terraform, and similar tools is declarative configuration: you describe the desired end state, and the system figures out how to get there.

AI excels at looping until a specific goal is reached. Give it a clear, verifiable success criterion, and it will iterate and self-correct until it gets there. This pattern is known as "goal-oriented planning" in AI Agent architectures.