How a Single CLAUDE.md File Tames Claude Code’s Uncontrolled Refactoring

1. Why AI coding assistants are both loved and hated?

Users of Claude Code and similar tools often encounter three recurring problems:

They ask for a simple change, but the model rebuilds an entire subsystem.

What could be solved in 50 lines expands to 500 lines because the model adds premature abstractions and unused fallback logic.

When fixing a bug, the model also modifies comments, formatting, naming, and unrelated code, making the diff unreadable.

Even Andrej Karpathy has complained that models make unchecked assumptions and over‑complicate simple logic.

2. The project’s core is not “skills” but “rules”

The repository andrej-karpathy-skills went viral not for flashy tricks but for a single, easy‑to‑understand idea: place a plain‑text CLAUDE.md file at the project root that encodes Claude Code’s behavior.

This file acts as a "project house rule" that tells Claude Code:

What actions are allowed.

What actions must not be taken autonomously.

When ambiguity arises, ask first instead of guessing.

Only modify the necessary parts of the code, avoiding unsolicited refactoring.

The underlying issue is not the model’s ability to write code, but its tendency to make decisions on behalf of the developer.

3. Four rules that curb Claude Code’s bad habits

1. Think Before Coding

Claude Code must first articulate its assumptions, list possible implementations, clarify ambiguities, and indicate whether a simpler solution exists.

✅ Explicitly state understanding before proceeding.

✅ Enumerate alternative implementations instead of following a single path.

✅ Clarify any ambiguities before starting work.

✅ Proactively mention if a simpler approach is available.

This rule reduces rework because many errors stem from the AI misinterpreting the problem from the outset.

2. Simplicity First

The model should avoid adding unnecessary features, premature abstractions, false flexibility, or scaffolding for scenarios that are not needed.

✅ Do not add unrequested functionality.

✅ Do not create heavyweight abstractions for one‑off logic.

✅ Do not chase illusory flexibility.

✅ Do not pre‑emptively build for unused scenarios.

If a senior engineer would call the result "over‑engineered," it is indeed too complex.

3. Surgical Changes

When fixing a bug, modify only the code directly related to the goal, leaving comments, formatting, naming, and unrelated logic untouched, and preserve the original project style.

✅ Change only code tied to the current objective.

✅ Do not touch comments, formatting, or naming.

✅ Do not alter logic that is already correct.

✅ Keep the original project’s style without unnecessary restructuring.

After applying this rule, diffs become readable and each change can be traced back to its original requirement.

4. Goal‑Driven Execution

The model must define a completion criterion, continuously work toward the goal, verify the result, and avoid declaring success prematurely.

✅ Define what constitutes a finished task.

✅ Keep advancing until the goal is met.

✅ Verify the outcome instead of relying on intuition.

✅ Do not deem the work "good enough" until the result is achieved.

A reliable AI assistant is judged not by speed but by its ability to close the loop on the goal.

4. How to use it? Two quick ways

Method 1: Per‑project quick activation

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Copy the file to the root of a single project to see immediate behavior convergence.

Method 2: Global installation via MCP plugin

claude mcp install https://github.com/forrestchang/andrej-karpathy-skills

Install the official MCP plugin so the rules apply to every new project. Teams can append their own policies to the end of CLAUDE.md, such as requiring tests before commits, forbidding unrelated refactoring, or mandating test cases for API changes.

5. How to tell if it works?

After adoption, three noticeable changes appear:

Diffs become clean, showing only the intended modifications.

Rework cycles drop because the model no longer guesses requirements or chooses overly complex solutions.

Communication cost falls as the model confirms boundaries before acting, eliminating rounds of misunderstanding.

The project’s success stems not from a new AI workflow but from reminding developers that the scarce resource in AI‑assisted coding is a clear sense of boundaries.

Related Links

GitHub: https://github.com/forrestchang/andrej-karpathy-skills
CLAUDE.md raw file: https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md