Karpathy's CLAUDE.md: 4 Rules That Fix LLM Coding

A single file — CLAUDE.md — just hit #1 on GitHub trending. It encodes Andrej Karpathy’s observations about LLM coding failures into four behavioral constraints. Drop it in your project root and Claude Code follows it from the first task.

The Problem Karpathy Identified

LLMs have predictable failure modes when writing code:

Silent assumptions — they pick one interpretation of an ambiguous request and run with it, never surfacing the alternatives
Overcomplexity — they write 200 lines when 50 would do, adding abstractions nobody asked for
Scope creep — they “improve” neighboring code, refactor what is not broken, and touch files they were never asked to change
Vague execution — they start coding before defining what “done” looks like

These are not model intelligence problems. They are behavioral defaults that a well-structured prompt can override.

The 4 Principles

1. Think Before Coding

If something is ambiguous, ask. Do not pick one interpretation and run.

The file instructs the LLM to:

State assumptions explicitly before writing code
Present multiple interpretations when they exist
Push back when a simpler approach exists
Stop and name what is confusing instead of guessing

This alone eliminates the most expensive failure mode — building the wrong thing because the model assumed instead of asking.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

The constraints are specific:

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 self-check: “Would a senior engineer say this is overcomplicated?” If yes, rewrite it. This targets the LLM tendency to over-engineer — wrapping everything in interfaces, adding config options nobody will use, building for scale that does not exist.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

Do not “improve” adjacent code, comments, or formatting
Do not refactor things that are not broken
Match existing style, even if the model would do it differently
If unrelated dead code is noticed, mention it — do not delete it

The test: every changed line should trace directly to the user’s request. This is the principle I see violated most often in AI-assisted development. The model changes one function and rewrites three neighboring ones “while it’s there.”

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform vague tasks into verifiable goals:

“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”
“Refactor X” becomes “ensure tests pass before and after”

For multi-step tasks, state a brief plan with verification checkpoints. Strong success criteria let the model loop independently. Weak criteria (“make it work”) require constant clarification.

Why It Works

CLAUDE.md is read by Claude Code at the start of every session as a project-level instruction file. It is not a system prompt hack or a jailbreak — it is the intended mechanism for shaping Claude’s behavior in a repository.

The genius of this approach is that it costs zero dependencies, zero configuration, and zero maintenance. One Markdown file in the repo root. Every developer who uses Claude Code in that repository gets the same behavioral guardrails.

My Take: Apply This to Any AI Coding Tool

These four principles are not Claude-specific. They describe good engineering discipline that any LLM coding assistant should follow. I have seen the same failure patterns in GitHub Copilot, Cursor, and other AI coding tools.

If you manage a team using AI-assisted development, consider encoding similar rules in your repository:

For Claude Code: CLAUDE.md in repo root
For Cursor: .cursorrules file
For GitHub Copilot: .github/copilot-instructions.md
For any tool: Include the principles in your CONTRIBUTING.md or code review checklist

The behavioral constraints work because they align the model with how senior engineers actually think: clarify before building, simplify aggressively, change only what is needed, and define done before starting.

Go Deeper with Claude Code

Ready to implement Karpathy’s principles and beyond?

🎓 Claude Code Masterclass (Free on Udemy) — Full course: CLAUDE.md, hooks, MCP servers, autonomous workflows
📘 Claude Code Companion Book (Leanpub) — Enterprise patterns, team setups, and production best practices
📝 5 Mods That Make Claude Code Production-Ready — Ralph Loop, Ultracode, Context7

Karpathy's CLAUDE.md: 4 Rules That Fix LLM Coding

The Problem Karpathy Identified