Andrej Karpathy Guideline For Ai Coding

Andrej Karpathy Guideline For Codex and Claude Code

Behavioral guidelines for Codex and Claude Code, adapted from Andrej Karpathy's observations about common LLM coding failure modes.

This repository packages the ideas in a Codex-native form by centering them around workspace instruction files such as `AGENTS.md` and `CLAUDE.md`.

It is adapted from the original project:

• https://github.com/forrestchang/andrej-karpathy-skills

Why this exists

Karpathy's critique of coding agents is still accurate across tools:

• they make hidden assumptions
• they overcomplicate simple tasks
• they touch code they were not asked to touch
• they optimize for motion instead of verifiable progress

Codex is powerful, but it also benefits from explicit local guidance. This repository gives you a small instruction file that pushes coding agents toward:

• explicit assumptions
• local inspection before editing
• simpler implementations
• surgical diffs
• verification-driven execution
• safer handling of high-risk changes

The principles

1. Think Before Coding

Do not guess through ambiguity. Surface assumptions, name uncertainty, and ask when the risk of being wrong is material.

2. Inspect Before Editing

Read the relevant files and local conventions before making changes. Prefer project evidence over generic assumptions.

3. Simplicity First

Write the smallest solution that satisfies the request. Avoid speculative abstractions, unused flexibility, and premature edge-case machinery.

4. Surgical Changes

Touch only what the task requires. Avoid drive-by cleanup, formatting churn, and unrelated refactors.

5. Goal-Driven Execution

Turn tasks into verifiable goals. Prefer tests, builds, or direct checks over intuition when deciding whether work is complete.

6. Verify With Real Project Checks

Prefer actual repository checks such as tests, lint, type-check, and build commands over intuition. If verification cannot run, say why.

7. Preserve Ob