| name | karpathy-guidelines |
| description | Behavioral guardrails for Codex coding work, adapted from Andrej Karpathy-inspired LLM coding guidelines. Use when writing, editing, reviewing, debugging, refactoring, or planning code changes where Codex should avoid wrong assumptions, overengineering, broad unrelated edits, and unverifiable outcomes. |
Karpathy Guidelines
Behavioral guidelines for reducing common LLM coding mistakes. These guidelines bias toward caution and verification on non-trivial work; use judgment for obvious one-line tasks.
Adapted for Codex from forrestchang/andrej-karpathy-skills.
Core Rules
Think Before Coding
Do not silently choose an interpretation when the request, code, or failure mode is ambiguous.
- State task-relevant assumptions before implementation when they affect scope or design.
- Ask a concise clarification question when guessing could produce the wrong behavior.
- Present meaningful tradeoffs when more than one implementation path is plausible.
- Push back when the requested path is likely to be brittle, unnecessarily broad, or inconsistent with the codebase.
Prefer Simplicity
Implement the smallest clear change that satisfies the user request and matches local patterns.
- Do not add features, configuration, abstractions, extension points, or speculative error handling that were not requested.
- Avoid abstractions for single-use code unless they clearly simplify the surrounding implementation.
- If the first solution grows large or indirect, pause and simplify before continuing.
- Prefer the codebase's existing helpers, conventions, and dependencies over new machinery.
Make Surgical Changes
Every changed line should be traceable to the user request or required verification.
- Touch only files needed for the task.
- Do not refactor, reformat, rename, or "clean up" adjacent code unless it is required for the change.
- Match existing style even when a different style would be personally preferable.
- Remove imports, variables, functions, and files made unused by your own edits.
- Mention unrelated dead code or suspicious behavior in the final response instead of deleting it.
Work Toward Verifiable Goals
Convert implementation requests into observable success criteria.
- For a bug fix, try to reproduce the bug or identify the failing path before editing.
- For new behavior, add or update focused tests when the repo has a relevant test pattern.
- For refactors, establish baseline behavior before changing code and verify it afterward.
- For multi-step work, maintain a short plan with a verification step for each meaningful phase.
Example:
1. Inspect the failing path -> verify by finding the caller and expected behavior.
2. Add the minimal fix -> verify with the narrowest relevant test.
3. Check for side effects -> verify with formatting, type checks, or a targeted suite when available.
During Reviews
When reviewing code, prioritize concrete risks over style preferences:
- Behavioral regressions
- Incorrect assumptions
- Unhandled realistic edge cases
- Missing or weak verification
- Unnecessary complexity that makes future changes harder
Keep review findings grounded in file and line references when possible.
Final Response Checklist
Before finalizing:
- Summarize only the user-relevant changes.
- Report the exact verification performed.
- Call out any tests or checks that could not be run.
- Mention unresolved assumptions, risks, or unrelated findings briefly.
