# Karpathy Guidelines

> <Purpose>

- Skill: `ricardo-vae/karpathy-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ricardo-vae/karpathy-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ricardo-vae/karpathy-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ricardo-vae (https://skillmd.com/u/ricardo-vae)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ricardo-vae/karpathy-guidelines

---


<Purpose>
This skill adapts the ideas from the `andrej-karpathy-skills` repository into a Codex-friendly workflow.
Use it when you want disciplined execution with less overengineering, smaller diffs, and tighter alignment to the actual goal.
</Purpose>

<Use_When>
- The user asks for "Karpathy-style", "simple and surgical", or "don't overengineer"
- The task is easy to overcomplicate with abstractions or broad refactors
- You are about to modify a codebase with unclear side effects and want tighter discipline
- You need to keep changes minimal while still finishing the job end-to-end
</Use_When>

<Do_Not_Use_When>
- The user explicitly wants broad redesign, large-scale refactor, or exploratory architecture work
- The task is purely creative writing with no engineering decision-making
- A larger systems redesign is already approved and minimalism would be counterproductive
</Do_Not_Use_When>

<Core_Principles>

## 1. Think Before Coding
- Restate the real goal in one or two sentences before editing
- Identify the smallest surface that can solve the problem
- Check what already exists before inventing a new pattern
- Do not code from a vague hunch when the codebase can answer the question directly

## 2. Simplicity First
- Prefer the simplest solution that fully solves the problem
- Reuse existing modules, conventions, and utilities before adding new ones
- Avoid speculative abstractions, premature optimization, and "frameworking"
- If two approaches work, prefer the one that is easier to explain and easier to delete later

## 3. Surgical Changes
- Touch as few files and symbols as possible
- Keep behavior changes narrow and intentional
- Avoid drive-by edits unless they are required for correctness
- Preserve surrounding code patterns unless there is a strong reason to unify or fix them

## 4. Goal-Driven Execution
- Judge progress by whether the user goal is solved, not by how much code was produced
- Verify the concrete outcome after changes
- Call out remaining risks or gaps clearly instead of hiding them behind large edits
- Stop once the goal is met; do not keep polishing unrelated areas

</Core_Principles>

<Execution_Checklist>
Before editing:
- State the target outcome
- Identify the smallest likely change set
- Inspect existing code paths and constraints

While editing:
- Keep diffs compact
- Prefer modification over invention
- Avoid renaming, moving, or restructuring unless necessary

Before finishing:
- Verify the user-facing outcome
- Summarize what changed in plain language
- Name any residual risks, edge cases, or untested paths
</Execution_Checklist>

<Behavioral_Defaults>
- Bias toward deletion over addition when safe
- Treat complexity as a cost that must be justified
- Avoid introducing new dependencies unless the user asked for them or the task truly requires them
- Do not confuse "thorough" with "large"
- When unsure, choose the more reversible path
</Behavioral_Defaults>

<Suggested_Phrases>
When activating this skill mentally, aim for these questions:
- "What is the smallest change that solves the real problem?"
- "Can I reuse what is already here?"
- "Am I changing this because it is necessary, or because it is tempting?"
- "Does this help the user outcome, or just make the code look different?"
</Suggested_Phrases>

<Source>
Adapted from:
- https://github.com/vtroisWhite/andrej-karpathy-skills
- repository guidance centered on Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution
</Source>