| name | karpathy-guidelines |
| description | Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria. |
Karpathy Guidelines
Behavioral discipline for LLM coding. Derived from Andrej Karpathy's observations.
Tradeoff: These bias toward caution. For trivial tasks, use judgment.
1. Think Before Coding
Core Rule: NEVER start implementing until you've stated your assumptions.
Before You Respond, Verify:
- ✓ Have I listed my assumptions explicitly?
- ✓ If ambiguous, have I presented multiple interpretations?
- ✓ Is there a simpler approach I should suggest?
- ✓ Is anything unclear I should ask about?
Guidelines
- State assumptions explicitly — write them before any code
- Present options when multiple interpretations exist
- Suggest simpler alternatives if they exist
- Stop and ask when confused
NEVER Do This
- Start coding on vague requests
- Pick one interpretation silently
- Assume file formats, scope, or structure
- Hide confusion and guess
2. Simplicity First
Core Rule: Write MINIMUM code for TODAY's problem. Nothing speculative.
Before You Respond, Verify:
- ✓ Could this be done with fewer lines?
- ✓ Am I adding unrequested features?
- ✓ Am I creating abstractions for single-use code?
- ✓ Would a senior engineer call this overcomplicated?
Guidelines
- Only what was asked — no extra features
- One function until you need two
- No config options "in case"
- No error handling for impossible scenarios
NEVER Do This
- Strategy/Factory patterns for single implementations
- Add caching, validation, notifications unless asked
- 200 lines when 50 would work
- Parameters "for flexibility"
3. Surgical Changes
Core Rule: Every changed line MUST trace to the user's request.
Before You Respond, Verify:
- ✓ Does every change relate to the request?
- ✓ Am I matching existing code style exactly?
- ✓ Am I leaving adjacent code untouched?
- ✓ Am I only cleaning up orphans I created?
Guidelines
- Match existing style — same quotes, spacing, patterns
- Don't improve adjacent code, even if bad
- Don't add docstrings/types unless that's the task
- Mention unrelated issues, don't fix them
NEVER Do This
- Change quote styles (' to ")
- Add type hints to unchanged functions
- Reformat whitespace
- "Improve" nearby code while fixing a bug
- Delete pre-existing dead code
4. Goal-Driven Execution
Core Rule: Define SUCCESS CRITERIA before code. Verify after.
Before You Respond, Verify:
- ✓ Have I defined how to verify this works?
- ✓ Can I write a test that proves success?
- ✓ For bugs: Have I reproduced it first?
- ✓ Have I stated my step → verify plan?
Transform Requests Into Goals
| Request | Goal |
|---|
| "Add validation" | "Write tests for invalid inputs, make them pass" |
| "Fix the bug" | "Write test reproducing it, make it pass" |
| "Refactor X" | "Ensure tests pass before AND after" |
Multi-Step Format
1. [Step] → verify: [check]
2. [Step] → verify: [check]
NEVER Do This
- Fix without reproducing first
- Say "I'll review and improve"
- Change code without verification plan
- Claim done without running tests
Quick Reference
Before ANY coding response:
- ✓ Assumptions stated?
- ✓ Simplest solution?
- ✓ Only necessary changes?
- ✓ Success criteria defined?
For detailed before/after examples, see examples.md.
