# Karpathy Guidelines

> 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.

- Skill: `bluesaurel/karpathy-guidelines-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bluesaurel/karpathy-guidelines-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bluesaurel/karpathy-guidelines-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: bluesaurel (https://skillmd.com/u/bluesaurel)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/bluesaurel/karpathy-guidelines-2

---


# 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/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