Karpathy’s 10 LLM Coding Rules That Instantly Boost Claude and Codex

Repository

The Karpathy-LLM-Coding-Rules repository contains two instruction files that can be loaded by AI coding agents: CLAUDE.md for Claude Code / Cursor and AGENTS.md for the OpenAI Codex CLI. Placing either file in a project’s root directory makes the rules automatically active for every session.

Motivation

Pain point 1 – Uncontrolled “hand‑over refactor”. When asked to modify a single function, the agent may rewrite the entire file, making code review impossible. The problem stems from the lack of explicit constraints that limit changes to what is strictly required.

Pain point 2 – Apparently reasonable code can be dangerous. Generated code often passes a superficial review but fails in critical scenarios, frequently swallowing exceptions with a try‑catch. The rules require the agent to pause and ask for clarification when uncertain.

Pain point 3 – Many rules lack enforceability. Generic advice such as “write clean code” or “follow SOLID” does not bind an LLM. Effective rules need a concrete verification standard, e.g., “Can each line be justified by the task itself?”

Rule Set

Read before write – Thoroughly read the target file and copy existing patterns. Validation: If no pattern is found, ask instead of guessing.

Think before write – State assumptions and trade‑offs explicitly. Validation: Pause and ask when confused; avoid filling code with plausible guesses.

Keep it simple – Write only the minimal code that solves the current problem. Validation: Abstract only when justified; “just in case” counts as over‑design.

Surgical changes – Keep diffs as small as possible; avoid touching unrelated code. Validation: Each line must be provably necessary for the task.

Validate – Write a failing test first, then fix it. Validation: Test behavior, not field assignments.

Goal‑driven – Define success criteria before coding. Validation: For multi‑step tasks, state the plan first.

Debug – Investigate, don’t guess; change one thing at a time. Validation: Avoid null‑checks that mask the root cause.

Dependencies – Treat every dependency as permanently uncontrolled code. Validation: Prefer standard‑library functionality over external packages.

Communication – Explain what was done and why. Validation: Express uncertainty precisely.

Anti‑pattern detection – Identify and stop four common failure patterns (Kitchen Sink, Wrong Abstraction, Optimistic Path, Runaway Refactor). Validation: Detect self‑inclusion in a pattern and pause.

File Structure

CLAUDE.md

– Target Agent: Claude Code / Cursor. Loaded automatically from the project root. CLAUDE.zh.md – Chinese version for Claude Code. Rename to CLAUDE.md to use. AGENTS.md – Target Agent: OpenAI Codex CLI. Discovered by descending from the repository root. AGENTS.zh.md – Chinese version for Codex. Rename to AGENTS.md to use.

Agent Loading Mechanism

Claude Code / Cursor

Automatically detects CLAUDE.md in the project root.

Fallback locations: .claude/CLAUDE.md or a parent directory.

Injected as a persistent system instruction for every session.

OpenAI Codex

Searches downward from the repository root for AGENTS.md (or AGENTS.override.md).

Global configuration possible via ~/.codex/AGENTS.md.

Supports hierarchical overrides.

Quick Start

Installation

# Copy the rule file to the project root for Claude Code / Cursor
cp Karpathy-LLM-Coding-Rules/CLAUDE.md ./CLAUDE.md
# Chinese version (optional)
cp Karpathy-LLM-Coding-Rules/CLAUDE.zh.md ./CLAUDE.md

# Copy the rule file to the project root for OpenAI Codex
cp Karpathy-LLM-Coding-Rules/AGENTS.md ./AGENTS.md
# Global installation (all projects)
cp Karpathy-LLM-Coding-Rules/AGENTS.md ~/.codex/AGENTS.md

Usage Example

请修复 src/auth.ts 中 login 函数在 token 过期时不刷新而是直接报错的 bug。

Summary

The Karpathy-LLM-Coding-Rules file provides an immediately usable AI coding discipline: ten executable rules that constrain an agent’s behavior throughout the coding lifecycle, with explicit validation standards and named anti‑patterns.

Reference

https://github.com/tomoncle/Karpathy-LLM-Coding-Rules

Disclaimer

The content is for learning and exchange only. Use the described tools and methods in accordance with platform terms and applicable laws. For third‑party services, refer to the latest official policies.