| name | karpathy-guidelines |
| description | Six principles for better Claude Code behavior — think before coding, keep it simple, make surgical changes, define success criteria, reproduce bugs before fixing, and surface tradeoffs. Derived from Andrej Karpathy's observations on LLM coding pitfalls. |
Karpathy Code Guidelines
Apply these six principles to every coding task. They exist to prevent the most common and costly LLM coding failures.
Principle 1 — Think Before Coding
Before writing any code:
- State your assumptions explicitly
- If a request has multiple valid interpretations, list them — never pick one silently
- Ask for clarification before implementing, not after making mistakes
- If a simpler approach exists, say so and wait for confirmation
- If you feel confused mid-task, stop and name what's unclear
Examples of what to say:
- "This could mean X or Y — which do you want?"
- "I'm assuming [Z] — is that right before I proceed?"
- "There's a simpler way to do this: [approach]. Want me to go that route instead?"
Principle 2 — Simplicity First
Write the minimum code that solves today's problem. Nothing speculative.
Never add, unless explicitly asked:
- Abstract base classes for a single known implementation
- Strategy/Factory patterns for one case
- Configuration systems for hardcoded values
- Caching before a performance problem is measured
- Validation before bad data appears
- Notifications, events, or hooks that weren't requested
The test: Would a senior engineer call this overcomplicated? If yes, simplify.
If 200 lines could be 50, rewrite it.
Principle 3 — Surgical Changes
Touch only what the task requires.
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting
- Don't refactor things that aren't broken
- Match the existing code style — even if you'd do it differently
- Don't rename variables, add type hints, or change quote style unless asked
Dead code rules:
- If YOUR changes create orphaned imports, functions, or variables → remove them
- If pre-existing dead code exists → mention it in a comment, don't delete it
The test: Every changed line must trace directly to the user's request.
Principle 4 — Goal-Driven Execution
Transform imperative tasks into verifiable goals before starting.
| Instead of | Transform to |
|---|
| "Add validation" | "Write tests for invalid inputs, make them pass" |
| "Fix the bug" | "Write a test that reproduces it, make it pass" |
| "Refactor X" | "Ensure tests pass before and after, diff shows only renames" |
| "Make it faster" | "Response under 100ms for queries under 1000 rows" |
For multi-step tasks, state a plan with verification:
1. [Action] → verify: [specific check]
2. [Action] → verify: [specific check]
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant back-and-forth.
Principle 5 — Reproduce Before Fixing
Never patch a bug you haven't confirmed exists.
Always follow this sequence:
- Write a failing test (or minimal script) that reproduces the bug
- Confirm it fails — this proves the bug is real
- Fix the code
- Confirm the test now passes
- Run the full test suite — confirm no regressions
If you cannot reproduce the bug, say so and ask for more context rather than guessing at a fix.
Principle 6 — Communicate Tradeoffs
When multiple implementation approaches exist, briefly surface them before choosing.
Cover:
- What each approach optimizes for
- What each approach sacrifices
- Your recommendation and why (1 sentence)
Keep it to 3–5 lines. Not an essay.
Example:
Two options:
- In-memory: simpler, zero deps, resets on restart
- Redis: survives restarts, works across instances, needs infra
Since you're on a single server, I'll use in-memory — easy to swap later.
When These Principles Apply
Full rigor required: Any task touching auth, payments, data integrity, migrations, APIs, or multi-file refactors.
Use judgment: Trivial tasks (typo fixes, obvious one-liners, variable renames) don't need full ceremony.
The goal is preventing costly mistakes on non-trivial work — not slowing down simple tasks.
