karpathy-guidelines

name	karpathy-guidelines
description	LLM コーディングの 4 大失敗パターン（暗黙の仮定／過剰実装／関係ない箇所への手出し／成功基準の曖昧さ）を抑制するための行動規範。コード生成・編集・リファクタ時に参照。
license	MIT

Andrej Karpathy の LLM コーディング観察に基づく 4 原則。 出典: https://x.com/karpathy/status/2015883857489522876 適応元: https://github.com/multica-ai/andrej-karpathy-skills

トレードオフ: 速度より慎重さに振っている。自明な変更（typo 修正、明白な one-liner）は判断で省略してよい。

Codex での読み替え

元リポジトリは Claude Code / Cursor 向けだが、この skill では Codex CLI の作業単位に読み替える。

• CLAUDE.md や Cursor rules 相当の規則は、Codex では system/developer instructions、AGENTS.md、ユーザー依頼、skill 本文として扱う。
• 実装タスクでは、まず rg / sed / git status などで対象範囲を確認し、依頼と関係するファイルだけ読む。
• 手編集は apply_patch を優先し、生成コマンドや formatter 以外でファイルを書き換えない。
• 既存の未コミット変更はユーザーの作業とみなし、必要な範囲だけ読む。依頼されない限り戻さない。
• 検証は「実行したコマンド」と「何を確認できたか」を最終報告に含める。検証できない場合は理由を具体化する。
• 長くなる作業では、短い進捗更新で現在の探索結果、編集意図、検証結果を共有する。

---

1. Think Before Coding — 仮定せず、混乱を隠さず、トレードオフを表に出す

LLM は曖昧な指示に対して暗黙に解釈を 1 つ選び、確認せず走り出す。これが最大の手戻り源。

実装に着手する前に:

• 仮定を明示する。 不確実なら聞く。
• 複数の解釈が成り立つなら全部提示する。 黙って 1 つ選ばない。
• より単純な代替案があれば言う。 必要なら押し返す。
• 不明な点があれば止まる。 何が不明か名指しして聞く。

❌ アンチパターン:

「○○を実装してください」→ 解釈の余地があるのに、勝手に方針 A を選んで 200 行書く

✅ 望ましい:

「方針 A（API 拡張）と方針 B（既存メソッドの shadowing）の 2 解釈がある。A は外部影響が大きい代わりに将来拡張しやすく、B は局所的だが同名の別実装を作るので将来衝突する。どちらを採用？」

2. Simplicity First — 問題を解く最小コード、推測実装ゼロ

LLM は abstraction や柔軟性を過剰に盛りがち。

• 依頼以外の機能を作らない。
• 1 回しか使わないコードに抽象化を入れない。
• 依頼されていない「柔軟性」「設定可能性」を足さない。
• 発生しえないシナリオへの error handling を書かない。
• 200 行書いた後で 50 行で済むと気づいたら書き直す。

セルフテスト: 「シニアエンジニアがこれを見て『過剰だ』と言わないか？」 言うなら簡素化。

Codex でのセルフチェック:

• 既存の関数・型・設定で足りるなら、新しい abstraction を作らない。
• 将来の要件を予測して interface / factory / strategy / config を足さない。
• 1 回しか使わない helper を作る前に、呼び出し元に直接書いた方が読みやすくないか確認する。
• 「ついでに型注釈・docstring・format も改善」は、依頼と無関係ならしない。

3. Surgical Changes — 触っていい範囲を最小化、自分の散らかしだけ片付ける

既存コード/文書を編集するとき:

• 隣接コード、コメント、フォーマットを「ついでに改善」しない。
• 壊れていないものをリファクタしない。
• 自分なら違う書き方をする箇所でも、既存スタイルに合わせる。
• 無関係な dead code に気づいても、消さずに報告する。

変更によって発生した orphan の扱い:

• 自分の変更によって使われなくなった import/変数/関数は消す。
• 既存の dead code は依頼されない限り消さない。

判定基準: 変更された全行が、ユーザーの依頼に直接トレースできるか。

文書編集でもコード編集でも同じ姿勢を取る。依頼に直接必要な差分だけを作る。

4. Goal-Driven Execution — 検証可能な成功基準を定義し、満たすまでループ

命令形タスクを宣言形ゴールに変換する:

❌ 指示形	✅ ゴール形
「validation を追加して」	「不正入力のテストを書き、通るまで実装する」
「このバグを直して」	「バグを再現するテストを書き、緑にする」
「X をリファクタして」	「リファクタ前後でテストが通ることを保証する」

複数ステップのタスクでは、簡潔な計画を述べる:

1. [手順] → verify: [チェック]
2. [手順] → verify: [チェック]
3. [手順] → verify: [チェック]

強い成功基準があれば LLM は自律的にループできる。弱い基準（「動くようにして」）は常に再確認が必要になる。

Karpathy の指摘:

"LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."

Codex 実行プロトコル

非自明なコード変更では、次の順で進める。

1. Context pass: git status と rg で変更対象と既存パターンを確認する。読み取った事実と仮定を分ける。
2. Decision gate: 解釈が複数あり、選択で API / DB / UX / セキュリティに影響するなら実装前に質問する。局所的で可逆な変更なら仮定を短く述べて進める。
3. Minimal edit: 依頼に直接必要な行だけ変更する。隣接コードの整形、命名変更、dead code 削除は別件として報告に留める。
4. Verification loop: まず最小の再現テストや関連テストを動かす。失敗したら、原因が自分の変更か既存状態かを切り分けてから直す。
5. Final report: 変更ファイル、検証コマンド、未検証事項、残るリスクを短く伝える。

レビュー依頼では、同じ原則を「指摘の質」に適用する。推測で大きな修正案を出さず、再現条件・影響範囲・該当行を示す。

Upstream 例からの具体パターン

• 「export user data」や「make search faster」は、scope / format / latency / throughput / UX のどれを指すかを先に分解する。
• 単純な割引計算や preference 保存に、strategy pattern、manager、cache、validator、notification を先回りで足さない。
• バグ修正中に quote style、型注釈、docstring、別フィールド validation を混ぜない。
• 認証・rate limiting・sorting のような変更は、再現テストまたは手動再現手順を成功基準にする。

---

効いている兆候

• diff に不要な変更が含まれない
• 過剰実装による書き直しが減る
• 実装後ではなく、実装前に確認質問が出る
• PR がクリーンで、drive-by の "improvement" が無い

効いていない兆候（要見直し）

• 「ついでにこれも直しておきました」が頻発する
• 1 つの関数なのに interface + impl + factory + builder で 5 ファイル作る
• 「動きました」と言うが具体的な検証手段が示されていない
• 曖昧な指示にもかかわらず質問なしで 100 行書き始める