概要

Hypothesis-Driven Planning（仮説駆動プランニング）は、大規模コードベースにおけるAI主導の過剰な探索と過剰なプラン生成を抑制し、人間がレビュー可能なサイズで設計判断を行うための開発手法である。

本手法の目的はコード生成ではない。

目的は設計判断の品質向上と認知負荷の最適化である。

大まかなフロー

HDPでは次の流れを採用する。

要求
↓
変更仮説
↓
共同調査
↓
仮説検証
↓
設計判断
↓
プラン
↓
実装

適用条件

HDPを適用するケース。

• ユーザーからの要望
• 大規模コードベース
• 複数レイヤーへ影響する変更
• 変更箇所が明確でない案件
• AIによる探索が必要な案件
• プラン生成前の調査コストが高い案件

適用しないケース。

• 単純なバグ修正
• 小規模な機能追加
• 変更対象が明確な作業
• 単一ファイル修正

基本原則

原則1: プランより先に仮説を作る

悪い例

要求
↓
AIが自由探索
↓
巨大プラン

良い例

要求
↓
変更仮説
↓
調査
↓
仮説検証
↓
プラン

原則2: 調査結果ではなく意思決定をレビューする

AIが出力すべきもの。

• 何を変えるか
• なぜ変えるか
• 何を変更しないか
• 想定リスク

AIが出力してはならないもの。

• 大量の調査ログ
• 大量の依存関係
• 大量の参照関係
• 大量のコード解説

原則3: コードは理解のために使う

小規模実装やプロトタイプは許可する。

ただし目的は実装ではない。目的は理解の獲得である。

設計判断を具体化するために利用する。

原則4: Diffは補助資料である

Diffは出力してもよい。

しかしDiffを中心成果物にしてはならない。Diffは設計判断を理解するための補助資料として扱う。

レビュー対象は常に設計判断である。

ワークフロー

Step 1: 仮説定義

人間が変更仮説を提示する。

仮説は正しい必要はない。探索空間を制約できれば十分である。

テンプレート

仮説:
認証責務をUserServiceへ集約する

制約:
DB変更なし
API変更なし

変更対象候補:
UserService

Step 2: 制約定義

探索範囲を明示する。

目的は網羅性ではない。レビュー可能性である。

例

探索上限:
5ファイル

DB層は除外

フロントエンドは除外

Step 3: 仮説検証

AIは仮説の妥当性を調査する。

調査目的は以下のみ。

• 仮説を支持する根拠
• 仮説を否定する根拠
• 見落としている影響範囲

出力形式

結果:
概ね妥当

支持根拠:
2件

反証:
1件

追加調査候補:
1件

Step 4: 理解促進

必要に応じて最小実装を行う。

目的

• 設計判断の具体化
• 理解の促進
• 責務移動の確認

許可される成果物

• サンプルコード
• 概念実装
• 小規模Diff
• 責務移動例

禁止事項

• 完成実装
• 大量実装
• 本番相当Diff

Step 5: 仮説更新

人間とAIが共同で仮説を修正する。

例

変更前:
UserServiceへ集約

変更後:
UserService + AuthPolicyへ集約

Step 6: プラン生成

十分な理解が得られた後にのみプランを作成する。

標準プランフォーマット

# 採用仮説

# 背景

# 設計判断

# 根拠

# 変更対象

# 非変更対象

# 影響範囲

# リスク

# 未解決事項

# 実装方針

AI出力ルール

優先順位

1. 設計判断
2. 根拠
3. 影響範囲
4. 変更対象
5. 実装例
6. コード

禁止事項

巨大調査レポート

• 全探索結果
• 全依存関係
• 全参照関係
• 全変更候補

巨大Diff

• 数百行以上のDiff
• 完成実装全体
• 大量コード出力

網羅主義

• すべての可能性
• すべての代替案
• すべての実装方法

探索の目的は理解であり、網羅ではない。

レビュー規約

人間がレビューする対象。

• 採用仮説
• 設計判断
• 影響範囲
• リスク

成功条件

設計判断に合意できた