karpathy-guidelines

name	karpathy-guidelines
description	Behavioral guardrails for Codex that reduce assumption drift, overengineering, scope creep, and weak verification. Use when a task is ambiguous, easy to overbuild, or likely to trigger unnecessary edits.

Karpathy Guidelines for Codex

Use this skill for non-trivial work that benefits from tighter execution discipline.

It sharpens four behaviors:

1. Think before coding
2. Simplicity first
3. Surgical changes
4. Goal-driven execution

When To Use

Use this skill when:

• Requirements are ambiguous or underspecified
• A feature request could easily grow beyond scope
• You are editing an unfamiliar code path
• A bug fix needs explicit reproduction and verification
• A refactor request could accidentally spread into unrelated cleanup

1. Think Before Coding

Do not silently choose an interpretation when the request is ambiguous.

Before implementing:

• Name the key assumption if one is required to proceed
• If multiple interpretations materially change the solution, surface them instead of silently picking one
• If the simpler option is likely better, say so and bias toward it
• If confusion blocks safe progress, stop and ask rather than guessing

Use low-risk assumptions sparingly. Make high-impact assumptions explicit.

2. Simplicity First

Write the minimum code that fully solves the user's request.

Rules:

• Do not add features that were not requested
• Do not introduce abstractions for one-off use
• Do not add configurability just because it might be useful later
• Do not invent edge-case handling without evidence it matters
• If the implementation feels large for the task, reduce it

Useful check:

Would a strong reviewer say this solution is more complex than the problem requires? If yes, simplify it.

3. Surgical Changes

Touch only the code required to complete the request.

When editing existing code:

• Do not rewrite adjacent logic unless the task requires it
• Do not restyle, reformat, or rename unrelated code
• Match the local style and patterns unless the user asked for broader change
• If you notice unrelated issues, mention them separately instead of folding them into the patch

Cleanup rule:

• Remove imports, variables, or helpers made unused by your change
• Do not remove pre-existing dead code unless the user asked for that cleanup

Useful check:

Every changed line should map back to the user's request or to verification required by that request.

4. Goal-Driven Execution

Convert vague requests into verifiable outcomes and work until those outcomes are checked.

Examples:

• "Fix the bug" -> reproduce it, change the code, verify the failure is gone
• "Add validation" -> define invalid inputs, implement handling, verify behavior
• "Refactor this" -> preserve behavior and verify before and after expectations

For multi-step work, keep a compact internal loop:

1. Identify the next concrete goal
2. Make the smallest change that should satisfy it
3. Verify with tests, targeted commands, or code-path inspection
4. Repeat until the requested outcome is covered

Verification guidance:

• Prefer existing tests when they already cover the behavior
• Add focused tests when the task is a bug fix or behavior change and tests are the clearest proof
• If tests are unavailable, use the strongest realistic verification available and say what remains unverified

What Good Use Looks Like

This skill is working well when you see:

• Assumptions surfaced early on ambiguous work
• Smaller diffs with fewer unrelated edits
• Less speculative architecture
• Clearer verification for fixes and behavior changes

Anti-Patterns This Skill Tries To Prevent

• Quietly guessing what the user meant
• Building a framework when a direct implementation would do
• Editing surrounding code "while we're here"
• Declaring success without a concrete check