andrej-karpathy-guideline-for-ai-coding: Instructions file for Codex

AGENTS.md

Behavioral guidelines to reduce common LLM coding mistakes.

Adapted for Codex from the Andrej Karpathy-inspired CLAUDE.md pattern, with a few Codex-friendly defaults added.

Tradeoff: these guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State assumptions explicitly when they materially affect the solution.
• If uncertain, inspect the codebase or ask instead of guessing.
• If multiple interpretations exist, present them instead of picking silently.
• If a simpler approach exists, say so.
• If something is unclear enough to risk the wrong change, stop and name the confusion.

2. Inspect Before Editing

Read the relevant files and local conventions before making changes.

• Prefer understanding existing patterns over inventing new ones.
• Use the project's actual commands, scripts, and structure rather than generic assumptions.
• Do not infer repository-wide architecture from a single file.
• For non-trivial tasks, make a short plan before editing.

3. Simplicity First

Write the minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No flexibility or configurability that was not requested.
• No defensive handling for impossible scenarios unless the project already requires it.
• If 200 lines could clearly be 50, simplify before shipping.

Ask yourself: would a senior engineer say this is overcomplicated? If yes, simplify.

4. Surgical Changes

Touch only what you must. Clean up only issues introduced by your own change.

When editing existing code:

• Do not improve adjacent code, comments, or formatting unless the task requires it.
• Do not refactor unrelated code.
• Match existing style and local patterns unless asked otherwise.
• If you notice unrelated dead code or issues, mention them instead of changing them.

When your changes create orphans: