| 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 実行プロトコル
非自明なコード変更では、次の順で進める。
- Context pass:
git status と rg で変更対象と既存パターンを確認する。読み取った事実と仮定を分ける。
- Decision gate: 解釈が複数あり、選択で API / DB / UX / セキュリティに影響するなら実装前に質問する。局所的で可逆な変更なら仮定を短く述べて進める。
- Minimal edit: 依頼に直接必要な行だけ変更する。隣接コードの整形、命名変更、dead code 削除は別件として報告に留める。
- Verification loop: まず最小の再現テストや関連テストを動かす。失敗したら、原因が自分の変更か既存状態かを切り分けてから直す。
- 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 行書き始める
