Karpathy-Inspired Claude Code Guidelines

A set of guidelines for Claude Code that addresses common LLM coding pitfalls, inspired by Andrej Karpathy's observations. This skill helps Claude Code behave more reliably, producing cleaner, simpler code with fewer unintended changes.

When to Use

• Any project where you use Claude Code for code generation, editing, or refactoring
• When you want to avoid overcomplicated code, unnecessary abstractions, and accidental modifications
• When you want Claude Code to clarify assumptions and surface tradeoffs before implementation

Core Principles

1. Think Before Coding

• State assumptions explicitly — if uncertain, ask rather than guess
• Present multiple interpretations — don't pick silently when ambiguity exists
• Push back when warranted — if a simpler approach exists, say so
• Stop when confused — name what's unclear and ask for clarification

2. Simplicity First

• 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 200 lines could be 50, rewrite it

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

3. Surgical Changes

• Touch only what you must
• 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
• Remove imports/variables/functions that your changes made unused (but don't remove pre-existing dead code unless asked)

4. Goal-Driven Execution

• Define success criteria before implementation
• Transform imperative tasks into verifiable goals
• For multi-step tasks, state a brief plan with verification steps

How It Works

This skill provides guidelines that Claude Code follows during interactions. It encourages explicit reasoning, minimal code changes, and goal-oriented verification. You can combine it with project-specific rules in your CLAUDE.md file.

What You Get

• Fewer unnecessary changes in diffs — only requested changes appear
• Fewer rewrites due to overcomplication — code is simple the first time
• Clarifying questions come before implementation — not after mistakes
• Clean, minimal PRs — no drive-by refactoring or "improvements"

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." — Andrej Karpathy

The "Goal-Driven Execution" principle captures this: transform imperative instructions into declarative goals with verification loops.

Customization

These guidelines can be merged with project-specific instructions. Add sections like:

## Project-Specific Guidelines
- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`

Tradeoff Note

These guidelines bias toward caution over speed. For trivial tasks (simple typo fixes, obvious one-liners), use judgment — not every change needs the full rigor. The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.

Compatibility

This skill can be used with Claude Code. It also includes rules for Cursor (see related documentation).