# Karpathy Guidelines > LLM コーディングの 4 大失敗パターン（暗黙の仮定／過剰実装／関係ない箇所への手出し／成功基準の曖昧さ）を抑制するための行動規範。コード生成・編集・リファクタ時に参照。 - Skill: `nwiizo/karpathy-guidelines` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add nwiizo/karpathy-guidelines` - Raw SKILL.md: https://api.skillmd.com/api/skills/nwiizo/karpathy-guidelines/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: nwiizo (https://skillmd.com/u/nwiizo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nwiizo/karpathy-guidelines --- Andrej Karpathy の LLM コーディング観察に基づく 4 原則。 出典: 適応元: **トレードオフ:** 速度より慎重さに振っている。自明な変更（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 行書き始める