karpathy-principles

モデルはあなたに代わって誤った前提を置き、 確認せずにその前提のまま進めてしまいます。混乱を 自分で整理せず、確認を求めず、矛盾を明らかにせず、 トレードオフを示さず、必要なときにも異議を唱えません。

（エージェント型コーディングの失敗パターンについての Andrej Karpathy の発言）

これは何か

LLM によるコーディングでよくある落とし穴を減らすための、4 つの原則からなる規約です。コンパクトなエントリーポイントです。各原則には night-market に詳しく掘り下げたスキルがあり、このスキルは目次であって、百科事典ではありません。

出典：Karpathy の所見を Forrest Chang が要約したもの （forrestchang/andrej-karpathy-skills、MIT）です。 詳しい出典表記は references/source-attribution.md を参照してください。

使用する場面

• 誤字修正より大きなコーディングタスクを始める前
• コードレビュー中に、目にした失敗パターンを指摘するとき
• 差分を書いた後、完了を宣言する前の自己監査として
• ジュニアエンジニアにエージェントの差分の読み方を教えるとき

使用しない場面

これらの原則は、速さより慎重さを重視します。 modules/tradeoff-acknowledgment.md に挙げられているケースでは、 判断を働かせてください。軽微な修正、探索的な試作、 ドキュメントのみの編集、時間を区切ったプロトタイプが該当します。

4 つの原則

1. コーディングの前に考える

前提を明示します。混乱を明らかにします。根拠に合わせて 表現の強さを調整します。

• リクエストに複数の解釈がある場合は、それらを列挙します。 黙って 1 つを選んではいけません。
• よりシンプルな方法がある場合は、それを示します。 シンプルな方法が正しいときは、異議を唱えます。
• 不明な点があれば、作業を止めて質問します。隠れた 前提は、予防するのに最も手間がかからず、後から発見するのに 最も手間がかかるバグです。
• 主張は、根拠が裏付ける範囲を超えないようにします。 自信満々の曖昧な説明より、根拠に即した表現が優れています。

詳しくは、迎合を防ぐための Skill(imbue:rigorous-reasoning)、選択肢の生成に関する Skill(superpowers:brainstorming)、曖昧さを掘り下げる /spec-kit:speckit-clarify コマンドを参照してください。

2. シンプルさを優先する

問題を解決するための最小限のコードにします。推測に基づく 実装はしません。

コードや API を過度に複雑にし、抽象化を肥大化させる 傾向があります。

（同じエージェント型コーディングに関する議論での Andrej Karpathy の発言）

• 求められていない機能は追加しません
• 1 回しか使わないコードに抽象化を導入しません
• 求められていない柔軟性や設定可能性は追加しません
• 起こり得ない状況に対するエラー処理は追加しません
• 200 行書いて、50 行で済むなら、書き直します

自己チェック：シニアエンジニアなら、これを過度に複雑だと言うでしょうか？ modules/senior-engineer-test.md を参照してください。

詳しくは、妥当性を判断する公式とブランチ予算については Skill(imbue:scope-guard)、追加するすべての要素に対する立証責任については Skill(leyline:additive-bias-defense)、KISS／YAGNI／SOLID の基盤については Skill(conserve:code-quality-principles) を参照してください。

トレードオフを記録する（意思決定ジャーナル）

このステップで実質的な代替案のある決定が確定した場合、判断の根拠が明確なうちに docs/tradeoffs.md に記録します（下書きを作成して確認を取ります）。

• leyline がインストールされている場合は、Skill(leyline:decision-journal) を呼び出し、 トレードオフの項目（決定事項、検討した選択肢、諦めたこと）を追記します。 phase は plan に設定します。下書きを提示し、確認後に追記します。
• フォールバック（leyline がない場合）：ファイル内の ENTRY TEMPLATE を使用して docs/tradeoffs.md に追記し、次の TR-NNN ID を割り当てます。

3. 外科的な変更

必要な箇所だけに手を加えます。自分が生んだ問題だけを片付けます。

• 近接するコード、コメント、書式は改善しないでください
• 壊れていないものはリファクタリングしないでください
• 異なるやり方をしたくても、既存のスタイルに合わせてください
• スタイルだけでなく、その懸念事項に対するモジュール既存のモデルにも合わせてください。移行中は移行先のモデルを使い、たとえ大半が旧モデルを使っていても、廃止されたモデルを決してコピーしないでください。Skill(conserve:elegant-code) の段階 2 を参照してください
• 無関係な未使用コードに気づいたら、その旨を伝えてください。削除してはいけません
• 変更によって不要になったインポートや変数は削除してください。既存の未使用コードは、依頼されない限りそのままにしてください

変更をさかのぼるテスト：変更したすべての行が、ユーザーの依頼に直接結びついている必要があります。

詳細な調査：差分の加算バイアス監査には Skill(imbue:justify)、立証責任の契約には Skill(leyline:additive-bias-defense)、読み取り予算の上限には bounded-discovery.md のルールを参照してください。

4. 目標主導の実行

検証可能な成功基準を定めます。検証できるまで繰り返します。

曖昧なタスクを確認可能な目標に変換します。

• 「検証を追加する」は「無効な入力を対象としたテストがパスする」に変換します
• 「バグを修正する」は「バグを再現するテストを作り、その後パスさせる」に変換します
• 「X をリファクタリングする」は「変更前後にテストがパスする」に変換します
• 「高速化する」は「Y を N ms 未満で処理するベンチマーク」に変換します

複数の手順があるタスクでは、手順ごとの検証方法を含む簡潔な計画を立ててください。明確な成功基準があれば、自分で反復して進められます。基準が曖昧だと、常に確認が必要になります。

完全な再定義のテンプレートは modules/verifiable-goals.md を参照してください。

詳細な調査：鉄則（失敗するテストを先に作り、実装する）については Skill(imbue:proof-of-work)、RED-GREEN-REFACTOR のサイクルについては Skill(superpowers:test-driven-development) を参照してください。

Karpathy セルフチェック

作業を提出する前に、次の 4 つの質問を確認します。

原則	質問
コーディング前に考える	前提を列挙しましたか。それとも黙って推測しましたか？
シンプルさを優先する	シニアエンジニアから見て、複雑にしすぎていませんか？
外科的な変更	変更したすべての行が依頼に結びついていますか？
目標主導の実行	感覚ではなく、チェックによって完了を証明できますか？

4 つすべてが「はい」なら提出できます。それ以外の場合は、反復してください。

モジュール

• modules/anti-patterns.md - 名前付きの逸脱防止策 8 項目と変更前後の差分
• modules/senior-engineer-test.md - 3 つの質問からなるセルフチェック
• modules/verifiable-goals.md - 具体例付きの、曖昧な目標を検証可能な目標に変換するテンプレート
• modules/tradeoff-acknowledgment.md - 4 つの原則が適用されない場合

参考資料

• references/source-attribution.md - Karpathy の一次出典、Forrest Chang による導出、ライセンス、関連する先行事例

関連スキル

• Skill(imbue:scope-guard) - 妥当性の計算式とブランチ予算
• Skill(imbue:proof-of-work) - 鉄則 TDD ゲート
• Skill(imbue:rigorous-reasoning) - 追従的な同意や隠れた前提を防ぐガード
• Skill(imbue:justify) - 差分の加算バイアス監査
• Skill(leyline:additive-bias-defense) - 追加項目ごとの立証責任
• Skill(conserve:code-quality-principles) - KISS、YAGNI、SOLID
• Skill(superpowers:test-driven-development) - RED-GREEN-REFACTOR
• Skill(superpowers:brainstorming) - 決定する前に選択肢を挙げる
• ゲートスキルの連携グラフ全体については、docs/quality-gates.md#skill-level-quality-gate-composition を参照してください（このスキルが統合ハブです）

必須の進捗項目

プリフライトゲートとして呼び出された場合は、次の項目を作成してください。

• karpathy:assumptions-listed - 原則 1 を満たした
• karpathy:simplicity-checked - 原則 2 を満たした
• karpathy:trace-back-verified - 原則 3 を満たした
• karpathy:success-criteria-defined - 原則 4 を満たした

終了基準

• 4つの原則それぞれについて、具体的な成果物（前提条件リスト、スコープの根拠、差分の追跡記録、検証計画）を用いて回答しています。
• シニアエンジニアのテストを少なくとも1回実施しています。
• 実装を開始する前に、検証可能な成功基準を文書化しています。
• 実際に代替案を検討した場合、選択したアプローチと簡潔さとのトレードオフを docs/tradeoffs.md（またはファイル内のテンプレート）に記録しています。