How a 100k‑Star CLAUDE.md Rule File Eliminates Common AI Coding Bad Habits

Developers increasingly rely on AI coding agents such as Claude, Cursor, and other assistants. While these tools can write code, they often assume requirements, over‑abstract, add unnecessary APIs, and modify unrelated code, leading to messy, over‑engineered solutions.

To curb these habits, a community‑driven CLAUDE.md file was created, consolidating observations from Andrej Karpathy and others into a set of four actionable principles.

1. Think Before Coding

Do not make unchecked assumptions. When ambiguity exists, list possible interpretations and ask clarifying questions before proceeding. Push back on overly complex solutions and openly state uncertainty.

If a requirement is ambiguous, enumerate interpretations and seek clarification.

When a simpler approach is available, propose it confidently.

If unsure, admit it and ask for confirmation.

This principle prevents AI agents from blindly advancing with hidden assumptions.

2. Simplicity First

Write only the minimal code needed to solve the current problem. Avoid adding unused features, unnecessary abstractions, or excessive lines of code.

Do not add any functionality that is not required.

Avoid creating extra abstraction layers.

Prefer a 200‑line solution over a 1,000‑line one.

Users report that code generated with this rule is cleaner and requires far fewer rework cycles.

3. Surgical Changes

Modify only the code directly related to the task. Preserve existing style and avoid touching unrelated sections, dead code, or imports unless explicitly needed.

When fixing login validation, change only validation code.

Match the project's existing code style, even if it seems suboptimal.

Remove only the dead imports introduced by the current change.

This approach is praised for keeping diffs tidy and respecting the project's integrity.

4. Goal‑Driven Execution

Turn tasks into verifiable goals and iterate until the goal is met. Write tests for invalid inputs first, then ensure all tests pass; write a failing test that reproduces a bug before fixing it.

Define clear success criteria for each task.

Write failing tests that capture the bug, then fix the code to make them pass.

These steps make the AI’s output predictable and self‑validating.

Installation

Recommended for Claude Code users:

# Add plugin marketplace
/plugin marketplace add forrestchang/andrej-karpathy-skills
# Install the plugin
/plugin install andrej-karpathy-skills@karpathy-skills

After installation, the rules apply automatically to all projects.

Alternative per‑project method:

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

Place the downloaded CLAUDE.md at the root of the project.

User Feedback

The single Markdown file reshaped Claude Code’s behavior.

Many users noted cleaner diffs, simpler code, and a noticeable boost in productivity.

While some called it a “cargo cult” practice, the majority appreciated the reduction in unnecessary complexity.

Overall, the rule file makes AI assistants more disciplined, resulting in higher‑quality code and faster development cycles.