Andrej Karpathy’s LLM Coding Rules: Think, Simplify, & Iterate

Large Language Models like Claude have a huge upside when it comes to code generation, but they can also produce messy, over‑engineered or even incorrect results. Andrej Karpathy, a pioneer in the field, distilled his observations into four principles that help developers write reliable, clean code with Claude. This tutorial walks through each rule, explains why it matters, and shows you how to embed the guidelines into your own workflow.

1. Think Before Coding

Goal: Surface assumptions, clarify ambiguities, and push back when safer decisions exist.

When Claude reads a task, it often infers an interpretation and proceeds without asking. This can lead to hidden confusion or wrong trade‑offs.

• State assumptions explicitly: Begin your prompt with a short list of what you assume.
• Ask for clarification: If a requirement is vague, generate a question for the user first.
• Present alternatives: Offer multiple viable approaches rather than committing to one.
• Stop when unsure: Name what’s unclear and request more context before coding.

Practical tip: add a comment block at the start of every file you generate with a brief outline of assumptions and chosen strategy.

2. Simplicity First

Goal: Prioritize the simplest code that satisfies the spec.

Claude loves to explore every possible abstraction and often produces 1,000‑line solutions when a 50‑line one would suffice. Simplicity reduces cognitive load for future developers and lowers bug surface area.

• Remove unnecessary features: Don’t add optional arguments unless the spec explicitly requires them.
• Avoid generic infrastructure: If a small helper function solves the problem, write it; don’t build a whole class just in case you think you might reuse it.
• Keep error handling realistic: Handle only realistic error paths. Don’t guard against impossible states.
• Use the "over 200 lines = 50 lines" rule: Whenever code stretches past 200 lines, refactor or strip.

Use the Senior Engineer Test: Would a senior engineer say this is overcomplicated? If yes, simplify.

3. Surgical Changes

Goal: Modify only what the user explicitly requests.

When tweaking existing code, Claude sometimes spills over into unrelated sections, altering comments or refactoring code that worked correctly.

• Don’t touch unrelated code: Limit changes to the lines that directly address the request.
• Maintain style: Preserve the project’s style guide; mimic existing patterns.
• Don’t remove pre‑existing dead code: If you notice an orphaned function, simply mention it—do not delete it unless requested.
• Clean up after yourself: Remove imports or variables that your changes made unused.

After a change, run a diff‑review loop to confirm no unintended modifications.

4. Goal‑Driven Execution

Goal: Define clear success criteria and loop until verified.

This principle leverages Claude’s strength of iterating until a verifiable condition is met. Rather than giving an imperative command, you specify the desired end state.

• Describe the goal: e.g., "Add input validation and expose error messages via an API response".
• Define verification steps: "Write a unit test for empty input; run and confirm failure; add validation; re‑run and confirm success."
• Create a short plan with step‑by‑step checkpoints.
• Loop: After each change, ask Claude to run or evaluate the tests.

Pseudocode example:

1. Add a unit test for empty input → Verify failure.
2. Insert validation logic → Verify failure.
3. Adjust logic to pass the test → Verify success.

How to Install the Guidelines

The repository contains a single CLAUDE.md file that you can add to any project.

# Option A: As a skills CLI plugin
npx skills add forrestchang/andrej-karpathy-skills

# Option B: Direct file copy
# For a new project
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md 

# For an existing project (appending)
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Once the file is present, prompt Claude with the Goal‑Driven Execution format: "Add data validation; Write tests that catch it; Run until tests pass." Claude will refer to the guidelines automatically.

Practical Use‑Case

Scenario: A team is building a simple user‑registration API. They want to: 1. Accept name, email, and password. 2. Validate email format. 3. Reject duplicate emails. 4. Store the hash of the password.

Using Karpathy’s rules:

1. Think before coding – ask whether the API should return a 409 for duplicates or a generic 400.
2. Simplicity first – use a single helper for email validation instead of a full external service.
3. Surgical changes – only modify the controller file, not the middleware.
4. Goal‑driven – specify the success criteria: unit tests for valid and invalid inputs.

Claude will generate minimal, well‑structured code that adheres to the project’s style, and the developer can review a clean pull request with only the required changes.

Wrap‑Up

Adopting Karpathy’s four principles can drastically reduce the noise and errors you see when using LLMs for coding. By foregrounding assumptions, simplicity, precision in modifications, and explicit goals, developers can harness Claude’s power while keeping their codebase maintainable and reliable.

Try adding CLAUDE.md to your next project and watch how your code loops more intelligently, and your reviews become fewer and more focused.