# Karpathy Guidelines

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

- Skill: `richling98/karpathy-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add richling98/karpathy-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richling98/karpathy-guidelines/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: richling98 (https://skillmd.com/u/richling98)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/richling98/karpathy-guidelines

---


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

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