How to Make Claude Code 10x Smarter with One File (Karpathy's file)

Don't want to figure this out alone? I walk members through every step inside the community. Join the Skool → skool.com/raycfu

WHAT A CLAUDE.MD FILE DOES

A CLAUDE.md file is a behavior configuration that Claude Code reads automatically at the start of every session. Whatever is in it becomes part of how Claude thinks about your project. You drop it in your project root and Claude follows those instructions on every task from that point forward.

This specific file adds four principles derived directly from Karpathy's complaints. Each one fixes a specific bad habit.

THE FULL FILE (COPY THIS)

CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

State your assumptions explicitly. If uncertain, ask.
If multiple interpretations exist, present them. Don't pick silently.
If a simpler approach exists, say so. Push back when warranted.
If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

No features beyond what was asked.
No abstractions for single-use code.
No "flexibility" or "configurability" that wasn't requested.
No error handling for impossible scenarios.
If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

Don't "improve" adjacent code, comments, or formatting.
Don't refactor things that aren't broken.
Match existing style, even if you'd do it differently.
If you notice unrelated dead code, mention it. Don't delete it.

When your changes create orphans:

Remove imports/variables/functions that YOUR changes made unused.
Don't remove pre-existing dead code unless asked.

The test: every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

"Add validation" → "Write tests for invalid inputs, then make them pass"
"Fix the bug" → "Write a test that reproduces it, then make it pass"
"Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

[Step] → verify: [check]
[Step] → verify: [check]
[Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

END OF THE FILE

WHAT EACH PRINCIPLE ACTUALLY CHANGES

PRINCIPLE 1: THINK BEFORE CODING

Before this file:

You say "Add a caching layer to this API endpoint."

Claude builds a full Redis integration with TTL config, cache invalidation hooks, fallback logic, and a complete abstraction layer. You stare at 200 lines of code you did not ask for and say "I just meant in-memory caching for now."

After this file:

You say "Add a caching layer to this API endpoint."

Claude responds: "Before I start, two interpretations. One, in-memory cache for this session only. Two, persistent cache like Redis across requests. Which did you mean? Also, should cache invalidation be time-based or manual?"

You say "In-memory, time-based, 60 seconds."

Claude builds exactly that. Nothing else.

The confusion surfaces before the work happens, not after. You stop wasting tokens on rebuilds because Claude asked the right question upfront.

PRINCIPLE 2: SIMPLICITY FIRST

Before this file:

You ask for "a function that checks if a user is an admin."

Claude builds a 50-line UserPermissionManager class with a config system, a cache layer, a permission registry, and a check_permission method with four parameters and fallback logic.

After this file:

You ask for "a function that checks if a user is an admin."

Claude writes:

def is_admin(user_id: str) -> bool: return user_id in ADMIN_USER_IDS

One function. One line. Does exactly what you asked. Would a senior engineer say the first version is overcomplicated? Yes. So Claude rewrites it before you even have to complain.

PRINCIPLE 3: SURGICAL CHANGES

Before this file:

You ask Claude to fix one null check in a 200-line file. You get back a diff that added type hints to the function signature, renamed a variable from x to order, rewrote two comments you never mentioned, and refactored the function signature. You asked for one fix. Claude touched six things.

After this file:

You ask Claude to fix the null check. You get back:

if order == None:
if order is None:

One change. The one you asked for. Nothing else. Every changed line traces directly back to your request. Your diffs are clean. Your code reviews take minutes instead of hours.

PRINCIPLE 4: GOAL-DRIVEN EXECUTION

This is the one Karpathy called the key insight. "LLMs are exceptionally good at looping until they meet specific goals. Don't tell it what to do. Give it success criteria and watch it go."

Before this file:

You say "Fix the login bug." Claude makes a change. You say "That didn't fix it." Claude makes another change. You say "Still broken." Claude makes another change. You go back and forth five times babysitting every step.

After this file:

You say "Fix the login bug."

Claude responds: "Here is my plan. Step 1: Write a test that reproduces the bug. Verify: test fails. Step 2: Identify root cause. Verify: can explain why test fails. Step 3: Implement fix. Verify: test passes. Step 4: Check no other tests broke. Verify: full suite green. Starting now."

Claude loops independently until all four checks pass. You review the finished work. You stop babysitting and start reviewing.

HOW TO INSTALL IT (2 MINUTES)

Option A: Plugin (works across all your projects)

Open Claude Code and run these two commands one after the other:

/plugin marketplace add forrestchang/andrej-karpathy-skills /plugin install andrej-karpathy-skills@karpathy-skills

Active immediately. Works in every project from this session forward. This is the recommended option because you install once and it applies everywhere.

Option B: Per-project (drop it into one repo)

Go to github.com/forrestchang/andrej-karpathy-skills. Copy the CLAUDE.md file from the repo. Drop it into the root of your project folder. Claude Code reads it automatically at the start of every session in that project.

Use Option B when you want different rules for different projects or when you want to customize the file for a specific codebase.

HOW TO ADD YOUR OWN RULES ON TOP

The file is designed to be merged with project-specific instructions. After the four principles, add a section like this:

Project-Specific Guidelines

Use TypeScript strict mode
All API endpoints must have integration tests
Follow error handling patterns in src/utils/errors.ts
Never commit directly to main
Use Prisma for all database queries
All components must have unit tests before PR

Your project rules sit on top of the four principles. Both apply. The four principles handle how Claude behaves. Your project rules handle what Claude builds with.

Some examples of project-specific rules people are adding:

For a React project: "Use functional components only. All state management through hooks. No class components. Follow the component structure in src/components/Button as the reference pattern."

For an API project: "Every endpoint must return consistent error format: { error: string, code: number }. All routes must have rate limiting. Use the middleware pattern in src/middleware/auth.ts as the template."

For a monorepo: "Never modify packages you were not asked to touch. If a change in package A requires a change in package B, flag it and ask before making both changes."

HOW YOU KNOW IT IS WORKING

Three things change that you will notice immediately.

Your diffs get cleaner. Only what you asked for shows up. No reformatted functions. No renamed variables. No improved comments you never mentioned. Code reviews go from "why did you change all of this" to "looks good, merge."

Clarifying questions come before implementation. Claude stops guessing and starts asking. You spend less time throwing away wrong work and more time building.

Code is simpler the first time. No rewrites because Claude overengineered the solution. No abstractions that made sense to Claude but nobody asked for. No 200-line implementations of something that should have been 50 lines.

Install it today. You will feel the difference on the very first task you run.

You just read the full playbook. Most people will close this tab and never implement it. The ones who do usually hit a wall around the technical setup and quit.

Inside the Skool, I walk you through the exact build step-by-step, troubleshoot your setup live in the community, and share the scripts and templates I use to actually land paying clients.

If you want the shortcut instead of the long way around:

Join the Skool →