ralphctl-karpathy-guidelines

Karpathy Guidelines

Distilled from Andrej Karpathy's public commentary on LLM coding pitfalls — his January 2026 X post on agentic coding. Clean-room — concepts only, not copied text.

Karpathy's observation, after moving most of his coding to agents: the mistakes agents make are not random — they cluster into four recurring failure modes. Each mode below pairs the failure with the counter-habit that prevents it. Treat these as standing behavioural rules for every coding turn, not a checklist to run once.

When this applies

• Plan — modes 1 and 4 dominate: a plan built on an unstated assumption, or with success criteria that can't be checked, fails before any code exists.
• Execute — all four modes: every generation, edit, and refactor is an opportunity to silently assume, over-build, damage bystander code, or stop before verifying.

Mode 1 — Silent assumptions

The failure: making a plausible assumption on the operator's behalf and running with it unchecked — not managing your own confusion, not surfacing inconsistencies, not presenting trade-offs, not pushing back when the request conflicts with what the code shows.

The counter-habit:

• When the task is ambiguous, name the ambiguity before acting. With an interactive channel, ask; without one, state the interpretation you chose and why in a <decision> or <note> signal, then proceed with the least-surprising reading.
• When the task's description contradicts what you find in the code, surface the contradiction — do not quietly pick a side.
• When two implementations satisfy the words of the task but differ in consequence, present the trade-off rather than silently committing to one.
• Push back when the request is likely a mistake. Deference that ships a wrong change is not helpfulness.

Mode 2 — Over-complication

The failure: bloated abstractions, over-general APIs, a thousand lines where a hundred would do — and dead code left behind because nothing forced its cleanup.