karpathy-guidelines

name	karpathy-guidelines
description	Karpathy-inspired behavioural guidance for non-trivial coding, debugging, review, or refactor work. Use to surface assumptions, keep changes minimal, and define verifiable success criteria.
version	1.0.0

/karpathy-guidelines

Behavioural checklist for non-trivial coding, debugging, refactoring, and code review work. /init includes common/karpathy-guidelines in its constraint manifest; read that canonical constraint when it applies.

When to apply

• Any implementation work beyond a single obvious line fix
• Debugging sessions
• Refactors that touch more than one file
• Code review

The four rules

1. Think before coding

State material assumptions before writing code. Surface tradeoffs. Stop and ask when ambiguity changes the solution shape. Prefer a short plan + verification step over diving straight into implementation.

2. Simplicity first

Write the minimum code that fully solves the stated problem.

• Do not add features, configurability, or abstractions not requested.
• Do not build reusable infrastructure for a one-off need.
• Do not add defensive complexity for scenarios that cannot happen.
• Three similar lines > a premature abstraction.

3. Surgical changes

Touch only the code needed for the requested outcome.

• Do not refactor adjacent code just because you noticed it.
• Do not rewrite comments, formatting, or APIs unrelated to the task.
• Match local project patterns unless asked to change direction.
• Clean up only unused imports/variables created by your own change.
• Call out unrelated debt separately instead of silently fixing it.

Every changed line must be traceable to the user request or to verification required by that request.

4. Goal-driven execution

Turn vague instructions into concrete success criteria and verify them.

• Prefer reproduction-first debugging: identify a failing check, then make it pass.
• Prefer before-and-after validation for refactors.
• State a short plan for multi-step work with a verification step for each stage.
• Do not claim completion without evidence from tests, builds, linters, or another concrete check.

Tradeoff

This skill favours correctness and caution over raw speed on non-trivial work. Apply judgment on obvious one-liners — do not over-engineer the process.

Source

Adapted from forrestchang/andrej-karpathy-skills (MIT) for this repository template.