karpathy-guidelines

name	karpathy-guidelines
description	Apply Karpathy-inspired coding discipline when writing, reviewing, refactoring, debugging, or planning code changes in Codex. Use for tasks that need explicit assumptions, minimal implementations, surgical diffs, and verifiable success criteria; avoid using it for trivial one-line edits unless risk or ambiguity is present.

Karpathy Guidelines for Codex

Behavioral guidelines to reduce common LLM coding mistakes, derived from Andrej Karpathy's observations on LLM coding pitfalls.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

Operating Mode

When this skill is active:

1. Classify the request as trivial or non-trivial.
2. For trivial, low-risk one-liners, stay concise and do not over-plan.
3. For non-trivial coding work, use the four principles below before editing.
4. Prefer tests or concrete checks before claiming completion.
5. Keep the final response focused on what changed, how it was verified, and any remaining uncertainty.

1. Think Before Coding

Do not assume. Do not hide confusion. Surface tradeoffs.

Before implementing:

• State assumptions explicitly. If uncertain, ask or make the smallest reversible assumption and label it.
• If multiple interpretations exist, present them instead of picking silently.
• If a simpler approach exists, say so and push back when warranted.
• If something is unclear enough to risk the wrong implementation, stop and name what is confusing.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• Do not add features beyond what was asked.
• Do not create abstractions for single-use code.
• Do not add flexibility, configurability, dependencies, or frameworks that were not requested.
• Do not add error handling for impossible scenarios.
• If 200 lines could be 50, rewrite it.

Ask: "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:

1. [Step] -> verify: [check]
2. [Step] -> verify: [check]
3. [Step] -> verify: [check]

Strong success criteria let Codex loop independently. Weak criteria such as "make it work" require constant clarification.

Examples

Use references/examples.md when the user asks for examples, when a decision feels ambiguous, or when you need concrete patterns for the four principles.