CLAUDE.md Rules: How to Cut AI Coding Mistakes from 40% to 3% in 2026

TL;DR Summary

• Andrej Karpathy's original 4-rule CLAUDE.md cut Claude coding errors from ~40% to ~11% by enforcing clarification, simplicity, surgical scope, and verification
• The 12-rule extension (claude-code-pro-pack) adds 8 more rules targeting agent-orchestration failures and pushes error rates to ~3% — a ~10x improvement over no rules
• Two leading open-source implementations exist: the 12-Rule Pro Pack (~700 tokens, 5 skill templates, Karpathy-provenance) and Ten Commandments for Coding Agents (~400 tokens, portable across all agents.md tools)
• The key insight: past ~200 lines of CLAUDE.md, compliance drops sharply — rules get buried. 12 rules with minimal boilerplate is the sweet spot
• These are drop-in files. Copy one into your project root. The agent picks it up on the next run. No framework, no config.

Direct Answer Block

CLAUDE.md is a markdown file in your project root that AI coding agents read at session start. Karpathy's original 4 rules addressed the highest-frequency failure modes: silent assumptions, overbuilt code, unintended edits, and unverified claims. The 12-rule extension layers agent-orchestration safeguards: token budget limits to stop debugging spirals, conflict-surfacing to prevent "averaging" two codebase patterns, and read-before-write to block uninformed edits. Together they form a behavioral contract between you and the AI agent — and the data says it works.

Introduction

You've experienced it: you ask an AI coding agent to fix a one-line bug, and it rewrites three functions, reformats adjacent code, adds a "helpful" abstraction layer, and introduces two new edge cases. The problem isn't the model — it's the absence of constraints. AI coding agents are prompt-optimizers: they fill ambiguity with creativity. CLAUDE.md removes the ambiguity. It replaces "be careful" with concrete, actionable, negative-example-rich directives that survive long conversational contexts. This article breaks down the rules that actually work, the failure mode each one closes, and how to choose between the two leading implementations.

Why do AI coding agents keep making the same mistakes — and how does CLAUDE.md fix this at the system level?

AI coding agents fail in predictable patterns. The Claude Code Pro Pack's documentation — built from real-world agent failures across 30+ codebases — identifies four root causes:

1. Silent assumptions: The agent guesses your intent when requirements are vague. It builds what it thinks you want, not what you actually want.
2. Overbuilt code: A simple feature request triggers a cascade of "while I'm here" improvements — abstractions, refactors, helper utilities — none of which you asked for.
3. Unintended edits: The agent touches adjacent code, renames variables, reformats files, and cleans up "messy" patterns that were intentional.
4. Scope creep: A focused task ("add error logging to the payment handler") expands into a system-wide logging framework with configurable backends.

CLAUDE.md works as a behavioral control layer rather than a prompt. Traditional prompting says "please do X carefully." CLAUDE.md says:

• "Surface uncertainty — if requirements are unclear, ask"
• "Keep changes surgical — touch only what the task requires"
• "Choose simplicity — write the minimum code that correctly solves the problem"

The difference is specificity. "Be careful" doesn't survive 50 turns of conversation. "Do not refactor, rename, reformat, or clean unrelated code" does.

"Past ~200 lines of CLAUDE.md, compliance drops sharply — rules get buried. The pack holds at 12 rules + minimal boilerplate so the agent actually reads and follows the file." — claude-code-pro-pack README

This token-efficiency constraint is underappreciated. CLAUDE.md is prepended to every agent context. Every line costs tokens on every call. The 12-rule pack clocks at ~700 tokens total — roughly the cost of a single paragraph of prose. The Ten Commandments version is even leaner at ~400 tokens.

According to Anthropic's Claude Code documentation, CLAUDE.md is one of the primary customization mechanisms alongside skills, hooks, and MCP servers. It's the first thing Claude reads when a session starts. The file sits in your project root or ~/.claude/ and is automatically loaded — no plugin, no /import, no configuration.

What were Karpathy's original 4 rules, and how did they cut error rates from 40% to 11%?

Karpathy's original CLAUDE.md established four rules as the minimum viable constraint set:

Rule 1: Clarify before implementing

The agent must restate the problem, goal, and expected outcome before writing code. This blocks the silent assumption failure mode. If the agent restates something wrong, you catch it before a single file changes.

Rule 2: Simplicity first

The agent must write the minimum code that solves the problem. No speculative features, no generic abstractions, no "future-proofing." This blocks overbuilt code.

Rule 3: Surgical changes only

The agent must touch only what the task requires. Match existing style. Do not refactor, rename, reformat, or clean unrelated code. This blocks unintended edits.

Rule 4: Verify before claiming success

The agent must run tests, lint, type checks, and confirm output before reporting completion. This blocks the "I fixed it" (didn't run anything) failure.

The 4 rules cut error rates from ~40% to ~11% because they target the four highest-frequency failure categories. Each rule is a negative constraint — it tells the agent what NOT to do — which research shows is more effective than positive guidance ("be helpful") for AI behavior control.

The 11% remaining errors come from failure modes the original rules don't cover: debugging spirals (the agent loops on a bug, burning tokens), pattern pollution (the agent sees two codebase patterns and averages them), silent partial failures (the agent catches one error but misses its downstream effects), and duplicate-function drift (creating near-identical functions in different files).

What 8 additional rules does the 12-rule pro pack add, and which failure mode does each address?

The claude-code-pro-pack extends Karpathy's 4 rules with 8 more, each targeting a specific agent-orchestration failure:

The most impactful of these in practice is rule 5 — hard token budget. The agent's natural response to a failing test is "try again." Without a budget, this becomes a spiral: try, fail, try differently, fail, until context exhaustion. The rule forces the agent to stop after a defined number of attempts and surface the impasse to the user.

Rule 7 — read before you write — prevents the most common "confident wrong answer" scenario: the agent modifies a function signature without checking its call sites, breaking the build in files it never touched.

The full rationale for each rule is documented in the pro pack's docs/why-12-rules.md, with every rule citing a real failure it closes rather than a preference.

How do the "Ten Commandments for Coding Agents" differ from the 12-rule approach — and which should you use?

Both approaches are drop-in, open-source, MIT-licensed constraint files. They differ in philosophy, scope, and tooling:

Which should you use?

Use the 12-Rule Pro Pack if:

• You want the most comprehensive coverage (every known failure mode addressed)
• You want skill templates (TDD loop, systematic debugging, PR workflow) included
• Your team is 3+ developers and needs a shared behavior baseline
• You want explicit Karpathy provenance (built on the original 4 rules)

Use the Ten Commandments if:

• You use multiple AI coding tools across your workflow (the symlink trick is elegant)
• Token efficiency matters — 400 tokens is about half the cost of the 12-rule pack
• You prefer the "commandments" framing — imperative directives with named failure modes inline
• You're a solo developer who wants minimal overhead

Both work. The Ten Commandments author themselves note: "If your fork grows past ~20 rules, you have a wiki, not a system prompt." The 12-rule pack author says: "Use all three — pack for behavior, anthropic/skills for domain tasks, addyosmani/agent-skills for lifecycle flow."

What does a surgical change look like in practice (and what happens when agents ignore rule #5)?

Rule 5 (12-rule pack) / Rule 5 (Ten Commandments) both address the same failure: keep changes surgical. Here's a concrete example.

Task: Fix a null-pointer exception in PaymentService.processRefund() when transaction.merchant is null after a failed payment gateway response.

Agent without surgical-change rules (what happens):

- public RefundResult processRefund(Transaction transaction) {
+ public RefundResult processRefund(Transaction transaction) {
+     // Added null safety
+     if (transaction == null) throw new IllegalArgumentException("transaction required");
      RefundRequest request = buildRequest(transaction);
-     GatewayResponse response = gateway.refund(request);
+     GatewayResponse response = gateway.refund(request);
+     // Extracted to separate method for testability
+     return handleGatewayResponse(response, transaction);
+ }
+
+ private RefundResult handleGatewayResponse(GatewayResponse response, Transaction tx) {
+     if (response.isSuccess()) {
+         return RefundResult.success(tx.getId());
+     }
+     // Added merchant null handling
+     if (tx.getMerchant() == null) {
+         log.warn("Merchant information missing for transaction {}", tx.getId());
+     }
+     return RefundResult.failure(response.getError());
  }

Three things happened that weren't asked for: (1) the method was split into two, (2) a new null check was added at the top, (3) the gateway.refund() variable was renamed. This touches 4 lines that didn't need changing and introduces a new method the team didn't agree on.

Agent with surgical-change rules (what was asked for):

  public RefundResult processRefund(Transaction transaction) {
      RefundRequest request = buildRequest(transaction);
      GatewayResponse response = gateway.refund(request);
-     return RefundResult.success(transaction.getId());
+     if (response.isSuccess()) {
+         return RefundResult.success(transaction.getId());
+     }
+     if (transaction.getMerchant() == null) {
+         log.warn("Merchant information missing for transaction {}", transaction.getId());
+     }
+     return RefundResult.failure(response.getError());
  }

One change, directly addressing the null pointer. No extracted methods, no input validation refactor, no variable renames.

The surgical approach isn't about writing worse code — it's about scope discipline. The refactored version might be genuinely better code. But when an AI agent introduces structural changes you didn't ask for, you lose the ability to reason about what else might have changed. The surgical rule preserves your ability to review the diff with confidence that everything you see is intentional.

How do you customize CLAUDE.md rules for your specific stack without breaking the system?

Customization follows two levels: repository rules and fork-and-extend.

Level 1: Repository rules (edit in place)

Both the 12-rule pack and Ten Commandments include a "Repository Rules" section at the bottom for project-specific conventions. Edit these without touching the core rules:

## Repository Rules
- We use pnpm, not npm or yarn. Use `pnpm install`, `pnpm test`, etc.
- Never modify `schema.prisma` directly — use `pnpm db migrate`
- Test files live next to their source files, not in a `__tests__` directory
- Prefer server components over client components. Only add 'use client' when necessary
- Auth is handled by NextAuth.js with the credentials provider. Do not add new auth libraries

These should be imperative directives, not descriptions. "Use X, not Y" works. "We use X for Y" gets ignored by the agent after 20 turns of context.

Level 2: Fork and extend (add custom rules)

If you encounter a failure mode the existing rules don't cover, fork and add a rule. The criterion for adding a new rule:

1. One sentence
2. Maps to a real incident (not a hypothetical preference)
3. Does not duplicate an existing rule

Example of a good custom rule:

13. Never import from barrel files in package internals. Use direct imports to avoid circular dependency cycles.

This maps to a real incident (your build broke from a circular dependency), is one sentence, and doesn't duplicate any existing rule.

Example of a bad custom rule:

13. Write good code that follows best practices and is maintainable over time.

This is a preference, not a directive. It doesn't map to a specific failure mode. The agent will ignore it.

Anti-patterns to avoid

• Don't add tool-specific rules: "Use npm test not jest" belongs in Repository Rules, not as a new commandment
• Don't add style rules: Prettier and ESLint handle formatting; CLAUDE.md shouldn't
• Don't go past ~15 rules: If you have 20 rules, audit them. Cut the ones that haven't prevented a real incident
• Don't describe your architecture: "We use hexagonal architecture with domain-driven design" is a wiki page, not a behavioral constraint

The cc-audit tool (from the pro pack ecosystem) scores any CLAUDE.md against the 12-rule baseline — use it in CI to enforce rule quality across your team.

Frequently Asked Questions

Q: Does CLAUDE.md work with non-Claude tools like Cursor or Codex?

Yes. Both Cursor and Codex read AGENTS.md or CLAUDE.md from your project root. The Ten Commandments maintain identical content in both file formats specifically for cross-tool compatibility. The 12-rule pack provides both CLAUDE.md and AGENTS.md variants.

Q: Can CLAUDE.md rules conflict with my existing .cursorrules or copilot-instructions?

They can. If your .cursorrules says "add comprehensive error handling" and your CLAUDE.md says "choose simplicity," the agent may produce inconsistent output. Pick one behavioral baseline and use it everywhere. The arai tool can enforce instruction files via hooks to prevent conflicts.

Q: Will these rules make the agent too conservative and miss edge cases?

No. The rules block unwanted behavior, not necessary behavior. An agent with surgical-change rules will still handle edge cases — it just won't restructure your codebase while doing it. The hard token budget rule prevents spiraling, not standard error handling.

Q: How do I verify my CLAUDE.md is actually working?

Watch for reduced chatter. An effective CLAUDE.md produces fewer clarifying questions, shorter diffs, and higher first-attempt success rates. The cc-audit tool provides quantitative scoring. Empirically, if your agent produces 3-line diffs instead of 30-line diffs for bug fixes, the rules are working.

Q: Can I use different rule sets per project?

Yes. CLAUDE.md files are project-scoped. Have a strict 12-rule set for your production monorepo and a lightweight 4-rule set for your experimental side projects. You can also have a global ~/.claude/CLAUDE.md with baseline rules that all projects inherit.

Q: Do these rules work with non-English prompts?

The rules are language-agnostic — they constrain behavior, not output language. The Ten Commandments repository includes a Korean translation (README.ko.md) demonstrating cross-language applicability.

Glossary

• CLAUDE.md: A markdown file in your project root or ~/.claude/ that Claude Code reads at the start of every session, containing behavioral rules and project conventions
• AGENTS.md: The emerging cross-tool equivalent of CLAUDE.md, read by Codex, Gemini CLI, OpenCode, and Cursor
• Surgical change: A code modification that touches only what the task requires, matching existing style without refactoring adjacent code
• Token budget: A hard limit on consecutive debugging attempts, preventing the agent from spiraling into infinite retry loops
• Two-pattern pollution: When an agent encounters two different conventions in a codebase and produces a third, averaging them instead of picking one
• Rule compliance cliff: The threshold (~200 lines or ~15 rules) beyond which AI agents stop consistently following CLAUDE.md directives

Author

Ramsis Hammadi — AI/ML engineer specializing in GenAI, LLM engineering, and automation. Full bio →