Four CLAUDE.md Rules That Earned 130k GitHub Stars

Problem

LLMs often make incorrect assumptions and execute them without questioning, over‑engineer code with unnecessary abstractions and dead code, and may modify or delete code they do not fully understand even when unrelated to the task.

Core Principles

Think before coding – expose hidden assumptions, present trade‑offs, and ask for clarification when confused.

Simplicity first – keep code minimal, avoid adding unrequested features, abstractions for one‑off code, or unnecessary flexibility.

Precise edits – change only what is required, preserve existing style, and do not refactor healthy code.

Goal‑driven execution – define verifiable success criteria and iterate until they are met.

Detailed Rules

1. Think before coding

State assumptions explicitly; ask when uncertain.

Present multiple interpretations when ambiguity exists.

Raise objections if a simpler solution is possible.

Stop and request clarification when confused.

2. Simplicity first

Do not add functionality beyond the request.

Avoid creating abstractions for one‑off code.

Do not add unrequested "flexibility" or configurability.

Skip error handling for impossible scenarios.

If 200 lines can be reduced to 50, rewrite it.

Check: senior engineers should not find the code overly complex; if they do, simplify.

3. Precise edits

Do not "improve" adjacent code, comments, or formatting.

Do not refactor code that is not broken.

Match the existing style even if you prefer a different style.

If you notice unrelated dead code, mention it but do not delete it.

When changes create orphaned code:

Remove imports/variables/functions that become unused due to your edit.

Do not delete pre‑existing dead code unless explicitly requested.

Check: every line of modification must trace directly back to the user's request.

4. Goal‑driven execution

Define success criteria and loop until they are satisfied. Transform imperative tasks into declarative goals with verification steps.

For multi‑step tasks, outline a short plan:

1. [Step] → Verify: [Check] 2. [Step] → Verify: [Check] 3. [Step] → Verify: [Check]

Strong success criteria let the LLM execute independently; vague criteria like "make it work" require constant clarification.

Installation

GitHub repository: https://github.com/multica-ai/andrej-karpathy-skills

Method 1 – Claude Code plugin (recommended)

/plugin marketplace add forrestchang/andrej-karpathy-skills

/plugin install andrej-karpathy-skills@karpathy-skills

This installs the guide as a Claude Code plugin available in all projects.

Method 2 – CLAUDE.md file

New project:

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

Existing project (append):

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

The repository also contains a .cursor/rules/karpathy-guidelines.mdc file for use in Cursor projects.

Core Insight

LLMs excel at looping until a goal is reached; give them a success standard instead of step‑by‑step instructions.

The "goal‑driven execution" principle captures this idea by converting imperative commands into declarative, verifiable objectives.

Validation

Fewer unnecessary changes in diffs – only requested edits appear.

Less rewrites caused by over‑complexity – code is concise on first write.

Clarifications are raised before implementation, not after errors.

Clean, minimal pull requests without unrelated refactoring.

Customization

The guidelines can be merged into an existing CLAUDE.md or added as a new file. Project‑specific sections can be appended, for example:

## Project‑specific guidelines
- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the error‑handling pattern in src/utils/errors.ts

Trade‑offs

The rules favor caution over speed. For trivial tasks (e.g., fixing a typo), developers may decide to bypass the full process. The aim is to reduce costly mistakes in non‑trivial work without slowing down simple edits.