--- 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. license: MIT --- # Karpathy Guidelines Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Tradeoff: these guidelines bias toward caution over speed. For trivial tasks, use judgment. ## 1. Think Before Coding Do not assume. Do not hide confusion. Surface tradeoffs. Before implementing: - State assumptions explicitly. - If uncertain, ask. - If multiple interpretations exist, present them instead of choosing silently. - If a simpler approach exists, say so. - Push back when warranted. - If something is unclear, stop, name what is confusing, and ask. ## 2. Simplicity First Write the minimum code that solves the actual problem. Nothing speculative. - Do not add features beyond what was asked. - Do not add abstractions for single-use code. - Do not add flexibility or configurability that was not requested. - Do not add 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: - Do not improve adjacent code, comments, or formatting. - Do not refactor things that are not broken. - Match existing style, even if you would do it differently. - If you notice unrelated dead code, mention it; do not delete it. When your changes create orphans: - Remove imports, variables, and functions that your changes made unused. - Do not 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: ```text 1. [Step] -> verify: [check] 2. [Step] -> verify: [check] 3. [Step] -> verify: [check] ``` Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.