Andrej Karpathy's 4 CLAUDE.MD Clauses: The Complete Guide
Problem
When I started using Claude Code for real projects, I noticed something unsettling. The AI would write code that looked correct at first glance but had subtle issues — wrong assumptions about the architecture, unnecessary abstractions, changes to files I didn’t ask about, and confident answers that were just wrong.
The core problem is simple: AI coding assistants don’t know what they don’t know. Without explicit behavioral constraints, they default to “generate first, think later” mode.
The Solution
Andrej Karpathy shared 4 simple clauses for CLAUDE.MD that address exactly these failure modes. These rules were originally designed for models where you can’t fully trust the output, but they work surprisingly well for capable models too.
Here’s the full CLAUDE.MD file:
1. **Ask, don't assume.** If something is unclear, ask before writing a single line. Never make silent assumptions about intent, architecture, or requirements.
2. **Simplest solution first.** Always implement the simplest thing that could work. Do not add abstractions or flexibility that weren't explicitly requested.
3. **Don't touch unrelated code.** If a file or function is not directly part of the current task, do not modify it, even if you think it could be improved.
4. **Flag uncertainty explicitly.** If you are not confident about an approach or technical detail, say so before proceeding.How Each Clause Fixes a Specific Failure Mode
Clause 1: Ask, don’t assume
The most common failure of AI coding tools is silent misalignment. You say “add pagination to the user list” and the AI assumes you want server-side pagination when you actually wanted client-side filtering with a “load more” button.
Without this clause, the AI picks an interpretation and runs with it. You don’t discover the mismatch until you review the code. With this clause, it asks “Server-side or client-side pagination?” before writing anything.
Clause 2: Simplest solution first
LLMs love to over-engineer. Ask for a simple data transformer and you get a factory-pattern-based, dependency-injected, interface-driven solution with plug-in architecture for future extensibility.
This clause forces the YAGNI (You Ain’t Gonna Need It) principle. The simplest working solution is almost always the right starting point.
Clause 3: Don’t touch unrelated code
This is the most dangerous failure mode. The AI sees a file with inconsistent formatting and “fixes” it. Or it renames a variable across the codebase because it looks “cleaner.” These changes introduce bugs in code you weren’t even working on.
I learned this the hard way when Claude Code “helpfully” reformatted an entire CSS file while I asked it to add one button style. The diff was 200 lines for a 5-line change.
Clause 4: Flag uncertainty explicitly
The hallucination problem is well known, but it’s more subtle than making up facts. The AI will confidently implement a solution using an API that was deprecated 2 versions ago, or a library approach that stopped working in the current release.
This clause creates permission to say “I’m not sure about this version’s API — here’s what I think works based on my training data.” You can then verify rather than blindly accept.
Why This Works
These 4 clauses are effective because they target the specific failure modes of transformer-based code generation:
| Failure Mode | Clause | Mechanism |
|---|---|---|
| Silent assumption | #1 — Ask | Forces clarification before action |
| Over-engineering | #2 — Simplest | Constrains complexity |
| Scope creep | #3 — Unrelated | Prevents collateral changes |
| False confidence | #4 — Flag uncertainty | Surfaces doubt explicitly |
Without these guardrails, the AI produces code that looks right but has hidden problems. The clauses make the reasoning process transparent so you can review decisions, not just code.
Summary
In this post, I explained Andrej Karpathy’s 4 CLAUDE.MD clauses and why each one matters. The key takeaway is that AI coding assistants need explicit behavioral rules — without them, the default behavior of “generate and be confident” creates more problems than it solves. Add these 4 lines to your CLAUDE.MD and watch the quality of AI-generated code improve.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments