Karpathy Claude File

Karpathy-Inspired Coding Agent Guidelines (Clear > Clever Edition)

A `CLAUDE.md` / `AGENTS.md` file to improve AI coding agent behavior, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls and modified with one critical addition: **Clear is better than Clever.**

Based on [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) — with a key principle added.

What Changed

The original guidelines are excellent but miss one of the most important software engineering principles:

**Clear is better than Clever.**

50 lines of code are not better than 100 lines of code if the 50 lines are super confusing and hard to understand.

This repo adds **"Clear Over Clever"** (Section 3) and **"Understand Before Modifying"** (Section 2) as first-class principles, and reframes "Simplicity First" to optimize for clarity *and* efficiency — not just concision.

If it's easier for a human to understand, it will likely be easier for an LLM to understand.

The Problems

From Andrej's post:

"The models make wrong assumptions on your behalf and just run along with them without checking."

"They really like to overcomplicate code and APIs, bloat abstractions... implement a bloated construction over 1000 lines when 100 would do."

"They still sometimes change/remove comments and code they don't sufficiently understand as side effects."

The Seven Principles

#	Principle	Addresses
1	Don't Assume — Surface Confusion	Wrong assumptions, hidden confusion, missing tradeoffs
2	Understand Before Modifying	Changing code without understanding context or blast radius
3	Clear Over Clever	Cryptic one-liners, bad variable names, unreadable chains
4	Simplicity First	Overcomplication, bloated abstractions, speculative features
5	Surgical Changes	Orthogonal edits, drive-by refactoring