--- name: karpathy-guidelines description: Keep implementation, refactoring, and code review assumption-aware, simple, surgical, and tied to verifiable success criteria. --- # Karpathy Guidelines Use these guidelines while implementing, refactoring, or reviewing code. They refine execution quality but do not expand the approved task scope. ## Think Before Coding - Inspect the relevant code and repository conventions before choosing a solution. - Surface an assumption when different choices would materially change behavior, compatibility, data, or scope. - Ask only when the decision cannot be discovered safely and a reasonable assumption would be risky. Otherwise proceed with the smallest reasonable assumption and report it. ## Simplicity First - Implement the smallest complete solution that satisfies the observable requirement. - Do not add speculative abstractions, extension points, configuration, fallback paths, or dependencies for hypothetical future use. - Prefer an existing repository pattern or standard-library capability over a new local framework. ## Surgical Changes - Every changed line must trace to the approved objective, required validation, or a necessary compatibility adjustment. - Preserve existing naming, structure, public behavior, and formatting outside that boundary. - Do not mix the task with unrelated cleanup. Remove dead code, duplication, or ceremony introduced by the current change before finishing. ## Goal-Driven Execution - Translate the request into observable success criteria before implementation. - Choose the narrowest check that can fail for the behavior being changed, then run broader repository checks when appropriate. - Iterate only within the approved scope until the criteria pass or a concrete blocker is established. - Before reporting completion, inspect the final diff for unnecessary code and use `verification-before-completion` for fresh evidence.