karpathy

Karpathy ガイドライン

コード実装のための、予防的な思考規律です。コード生成時にLLMが犯しやすい典型的なミスを防ぐため、コードを書く前と書いている最中に適用します。

これはパフォーマンス（rob-pike）やデバッグ（systematic-debugging）についてではありません。コードを書くという行為そのものについてです。書く前に読む、求められたことだけを変更する、思い込みではなく検証する、そして着手前に「完了」の定義を明確にすることです。

厳守事項

これらのルールに例外はありません。

1. 書く前に読む。 読んでいないファイルを変更してはいけません。呼び出し元を理解せずに関数を変更してはいけません。役割を理解せずにモジュールを変更してはいけません。
2. 依頼の範囲にとどめる。 求められたことを変更してください。それ以外は何も変更しません。「ついでに」改善することも、機を見たリファクタリングも、依頼されていない機能の追加も禁止です。
3. 思い込まずに検証する。 関数がXをすると思ったら、その関数を読みます。型にフィールドYがあると思ったら、確認します。テストがシナリオZをカバーしていると思ったら、そのテストを探します。思い込みは、LLMによるコーディングエラーの主な原因です。
4. 着手前に成功の条件を定める。 コードを書く前に、「完了」がどのような状態かを、具体的かつ検証可能な形で明確にします。それを定義できないなら、まだタスクを理解できていません。

使用する場面

• 機能や変更を実装する前
• 既存のコードを変更するとき
• コードレビュー中（思考上のチェックリストとして）
• 周辺の文脈を読まずにコードを生成していることに気づいたとき

使用しない場面

• 読むべき既存コードがない新規プロジェクト（ただし、ゲート1と3は依存関係にも適用されます）
• ドキュメントのみの変更
• パフォーマンス最適化（代わりにrob-pikeを使用してください）

5つのルール

ルール1：必要最小限の変更にする

すべての変更は、目標を達成するために必要最小限の編集にしてください。

書く前に自問してください：

• これを解決する最小の変更は何ですか？
• 変更する必要のないファイルに手を加えていませんか？
• 依頼されていないコードを追加していませんか？

明示的に依頼されていない限り、次の追加は禁止です：

• 変更していないコードへの型注釈
• 変更していない関数へのドキュメント文字列
• 変更していないロジックへのコメント
• タスクの対象ではない状況へのエラー処理
• 周辺コードのリファクタリング
• 作業中に気づいた「改善」

1つのタスクに、1つの変更を行います。ほかに修正が必要なものを見つけたら、記録するだけにして、今は修正しないでください。

ルール2：既存のコードを読む

LLMはパターンに基づいてコードを生成します。コードベースには独自のパターンがあり、それらはしばしば互いに矛盾します。

ファイルを変更する前に：

1. ファイルを読む
2. 使用されている規約（命名、エラー処理、パターン、構造）を特定する
3. 変更では、それらの規約に正確に合わせる

関数を変更する前に：

1. すべての呼び出し元を見つける
2. 契約（入力、出力、副作用）を理解する
3. 変更によって契約が損なわれないことを確認する

新しいファイルを追加する前に：

1. 類似の機能がほかに存在するか確認する
2. プロジェクトのファイル構成のパターンに従う
3. 近接するファイルと同じ命名規約を使う

新しいパターンを考案してはいけません。既存のパターンに従ってください。

ルール3：思い込みを検証する

すべての思い込みは、バグにつながる可能性があります。最も危険なのは、明白だと感じる思い込みです。

失敗の原因となるよくある思い込み：

思い込み	検証方法
「この関数はXを返す」	関数を読む
「このフィールドは常に存在する」	型定義と上流の生成元を確認する
「このテストがそのケースをカバーしている」	テストを読む
「このインポートパスは正しい」	そのパスにファイルが存在するか確認する
「このAPIはこれらのパラメーターを受け付ける」	APIの定義またはドキュメントを読む
「このライブラリはこう動作する」	バージョンとドキュメントを確認する
「この設定値は設定されている」	実際の設定を確認する

迷ったらgrepしてください。確信があっても、やはりgrepしてください。

ルール 4：成功基準を定義する

コードを書く前に、「完了」とは何を意味するのかを明確にします。

形式：

Done when:
- [ ] <specific, verifiable condition>
- [ ] <specific, verifiable condition>
- [ ] <specific, verifiable condition>

悪い基準：

• 「機能が動く」（検証できません）
• 「コードがきれい」（主観的です）
• 「テストが通る」（どのテストですか？何を検証するのですか？）

良い基準：

• 「有効なペイロードを指定した場合、POST /api/users が 201 を返し、email がない場合は 400 を返す」
• 「user.test.ts の既存テストが引き続きすべて通る」
• 「issue #42 の null-brand エッジケースを対象とする新しいテストを追加する」

具体的な基準を書けない場合は、タスクを理解できていません。戻って確認しましょう。

ルール 5：存在しない問題を解決しない

LLM は将来のニーズを先回りして考えがちです。その結果、必要以上に複雑なコードが生まれます。

こうした衝動を抑えましょう：

• 「これに null が渡されたらどうなるだろう？」— 現在のコードでその可能性はありますか？なければ、対策は不要です。
• 「設定可能にしておくべきだ」— 今、設定が必要ですか？不要なら、値を直接指定しましょう。
• 「複数のバックエンドをサポートする必要が出るかもしれない」— 現在、複数のバックエンドがありますか？なければ、抽象化は不要です。
• 「汎用ユーティリティにできそうだ」— 複数の場所で使われていますか？そうでなければ、用途を限定しておきましょう。
• 「機能フラグを追加しよう」— 機能フラグは依頼されていますか？そうでなければ、コードを変更するだけにしましょう。

今日必要なものを作りましょう。明日の問題には、明日の状況があります。

アンチパターン

衝動	違反しているルール	対応
「ついでに、さっとリファクタリングしよう」	ルール 1	1つのタスクに1つの変更。後で対応するために記録しましょう。
「仕組みはわかっているから、すぐ修正を書こう」	ルール 2	まず読んでください。頭の中の理解が間違っているかもしれません。
「これはたぶん文字列を受け取る」	ルール 3	型を確認してください。「たぶん」と言うなら、わかっていないということです。
「動けば完了だとわかる」	ルール 4	作業を始める前に、具体的な基準を定義してください。
「将来使えるように拡張しやすくしておこう」	ルール 5	今必要なものを作りましょう。拡張性は将来のタスクです。
「周辺のコードが汚いから、きれいにしよう」	ルール 1	あなたのタスクではありません。別の issue を起票してください。
「役立ちそうなログを追加しよう」	ルール 1	ログは依頼されていますか？そうでなければ、追加しないでください。

危険信号

次のように考えていることに気づいたら、作業を止めてルールを読み直してください。

• 「これは明らかだから、コードを読む必要はない」
• 「ついでに、いくつか追加しよう」
• 「エッジケース X にも対応したほうがよさそう」（X が起こりうるか確認せずに）
• 「ここで型安全性も改善しよう」
• 「この関数が何をするかわかっている」
• 「エラーが発生している証拠もないのに、エラーハンドリングを改善する必要がある」
• 「命名に一貫性がないから、ファイル全体を修正しよう」

最小チェックリスト

実装中に、次のリストに照らして確認してください。

• 変更する前に、対象ファイルを読んだ
• 変更の範囲を依頼された内容に限定した
• 型、API、動作に関する前提を確認した
• 作業を始める前に、具体的な成功基準を定義した
• 仮定上の将来の問題を解決しようとしていない
• 新しいやり方を独自に作らず、既存のプロジェクト規約に従っている
• 追加したコードの各行が、タスクの遂行に必要である

完了基準

次の条件を満たしていれば、規律ある実装です。

• すべての変更が依頼された範囲内にある
• 確認せずに前提を置いていない
• 成功基準を定義し、達成した
• 推測に基づくコードを追加していない
• 既存の規約に従っている

いずれかを満たしていない場合は、実装を見直す必要があります。

次の手順

実装が完了した後：

• AI 生成コード特有の問題が残っている場合 → clean-ai-slop を使って修正パスを実行する
• バグが見つかった場合 → systematic-debugging を使って調査する
• パフォーマンスが懸念される場合 → 最適化の前に rob-pike を使う