本仕様書は、LLMエージェントが複雑なタスクを効果的に処理するためのプランニングプロセスを定義します。
本仕様は以下をカバーします：
- プランニングプロセスの6つのフェーズの詳細
- 各フェーズの入出力形式
- アーキテクチャ設計と実装詳細設計
- システムプロンプト拡張仕様
- 設定オプションと環境変数
- エラーハンドリング戦略
- LLMエージェントは既存のMCPサーバーと連携可能
- タスクはGitHub IssueまたはGitLab Issue/MRとして提供される
- LLMはJSON形式での応答が可能
- システムプロンプトによる動作制御が可能
- システムプロンプトは必ず英語で記述する
flowchart TD
subgraph Planning[計画フェーズ]
A[目標の理解] --> B[タスクの分解]
B --> C[行動系列の生成]
end
subgraph Execution[実行フェーズ]
D[アクション実行] --> E{成功?}
E -->|Yes| F[次のアクション]
E -->|No| G[エラー処理]
F --> H{完了?}
H -->|No| D
H -->|Yes| I[検証フェーズへ]
end
subgraph Verification[検証フェーズ]
V1[実装完全性チェック] --> V2{検証合格?}
V2 -->|Yes| V3[完了報告]
V2 -->|No| V4[追加作業特定]
V4 --> V5[追加アクション実行]
V5 --> V6{再検証?}
V6 -->|Yes| V1
V6 -->|No| V3
end
subgraph Reflection[振り返りフェーズ]
J[結果評価] --> K{計画修正必要?}
K -->|Yes| L[計画修正]
L --> D
K -->|No| M[継続]
end
C --> D
G --> J
I --> V1
V3 --> N[タスク完了]
- 目標の理解（Goal Understanding）: ユーザーからの指示や達成すべき目標を理解
- タスクの分解（Task Decomposition）: 複雑な目標を実行可能な小さなサブタスクに分割
- 行動系列の生成（Action Sequence Generation）: 実行順序とツール使用計画を策定
- 実行（Execution）: 計画された行動を順番に実行
- 検証（Verification）: すべてのアクション完了後に実装の完全性を検証
- 監視と修正（Monitoring and Reflection）: 実行結果を評価し、必要に応じて計画を修正
エージェントはまず、ユーザーからの指示や達成すべき目標を理解します。
- Issue/PR/MRの内容
- ユーザーコメント
- リポジトリコンテキスト
- 同じIssue/MRで過去に実行した計画と実行履歴（JSONLファイルから取得）
- 要求の意図を分析
- 成功基準の特定
- 制約条件の識別
- 過去の計画・実行内容を参照し、継続性を保つ
以下の情報を含むJSONオブジェクトを出力します：
- main_objective: メインの目標を明確に記述
- success_criteria: 成功条件のリスト
- constraints: 制約条件のリスト
- context: タスクの背景情報
複雑な目標を実行可能な小さなサブタスク（ステップ）に分割します。
- Chain-of-Thought (CoT): 思考プロセスを段階的に展開
- Hierarchical Task Network: 階層的なタスク構造
- Dependency Analysis: 依存関係の分析
以下の情報を含むJSONオブジェクトを出力します：
- reasoning: タスク分解の理由と考え方（Chain-of-Thought）
- subtasks: サブタスクの配列
- id: サブタスクの識別子
- description: サブタスクの説明
- dependencies: 依存するサブタスクのリスト
- estimated_complexity: 推定複雑度（low/medium/high）
- required_tools: 必要なツールのリスト
分解されたサブタスクに基づき、実行順序とツール使用計画を策定します。
- タスク間の依存関係
- ツールの利用可能性
- 実行効率
- エラー回復戦略
以下の情報を含むJSONオブジェクトを出力します：
- execution_order: 実行順序のリスト
- actions: アクションの配列
- task_id: 対応するタスクID
- action_type: アクションタイプ
- tool: 使用するツール
- purpose: このアクションの目的
- expected_outcome: 期待される結果
- fallback_strategy: 失敗時の代替手段
sequenceDiagram
participant PC as PlanningCoordinator
participant LLM as LLMClient
participant MCP as MCPToolClient
participant Task as Task
PC->>LLM: アクション実行依頼
LLM-->>PC: function_call応答
PC->>MCP: ツール実行
MCP-->>PC: 実行結果
PC->>LLM: 結果送信
alt 成功
LLM-->>PC: 次のアクション
else 失敗
LLM-->>PC: リフレクション要求
end
PC->>Task: 進捗コメント更新
実行ループ内で以下の処理を繰り返します：
- シグナルチェック: 各アクション実行前に以下をチェック
- 一時停止シグナル（pause_signal）の存在確認
- アサイン解除（タスク停止）の確認
- 新規コメントの検出とコンテキストへの追加
- アクションの選択: 次に実行するアクションを選択
- 前提条件の確認: アクション実行の前提条件を確認
- ツールの実行: MCPサーバーを通じてツールを実行
- 結果の記録: 実行結果をコンテキストに記録
- リフレクション判定: 設定に応じてリフレクションを実行
- 進捗更新: Issue/MRのチェックリストコメントを更新
- 次のアクションへ: 次のアクションを選択して繰り返し
すべての計画アクション完了後、実装の完全性を検証するフェーズです。プレースホルダの検出、成功基準の達成度確認を行い、必要に応じて追加作業を実行します。
以下の項目を検証します：
- すべての関数/メソッドが完全に実装されているか（プレースホルダなし）
- すべてのコードパスが完成しているか
- タスクで要求されたすべての機能が実装されているか
- テスト（必要な場合）が実装され、合格しているか
- ドキュメント（必要な場合）が完成しているか
以下のパターンを検出します：
TODOFIXME'...''# implementation here'- 実装が必要な
pass文 raise NotImplementedError
flowchart TD
A[検証開始] --> B[ファイル再読み込み]
B --> C[プレースホルダ検出]
C --> D[成功基準チェック]
D --> E{検証合格?}
E -->|Yes| F[完了報告]
E -->|No| G[問題特定]
G --> H[追加アクション生成]
H --> I[追加作業実行]
I --> J{再検証?}
J -->|Yes| B
J -->|No| F
検証結果は以下のJSON形式で出力されます：
{
"phase": "verification",
"verification_passed": true,
"issues_found": ["問題1", "問題2"],
"placeholder_detected": {
"count": 0,
"locations": []
},
"additional_work_needed": false,
"additional_actions": [
{
"task_id": "verification_fix_1",
"action_type": "tool_call",
"tool": "ツール名",
"parameters": {},
"purpose": "不完全な実装の修正",
"expected_outcome": "完全に実装された機能"
}
],
"completion_confidence": 0.95,
"comment": "検証結果のサマリー"
}検証で問題が検出された場合：
- 追加アクションを計画に追加
- チェックリストを更新（元の計画と追加作業を区別）
- 追加アクションを実行
- 最大検証ラウンド数まで再検証を繰り返し
config.yamlのplanning.verificationセクションで以下を設定：
- enabled: 検証フェーズの有効/無効（デフォルト: true）
- max_rounds: 最大検証ラウンド数（デフォルト: 2）
- アクションの成功/失敗
- 期待される結果との差異
- 副作用や予期しない影響
実行結果を評価し、以下の情報を出力します：
- action_id: 評価対象のアクションID
- status: 成功/失敗/部分成功
- evaluation: 結果の評価
- alignment_with_plan: 計画との整合性
- issues_identified: 特定された問題
- plan_revision_needed: 計画修正が必要かどうか
- Issueコメントでの指摘
- PRレビューでのフィードバック
- 明示的な修正要求
flowchart TD
A[問題の特定] --> B[根本原因の分析]
B --> C[代替アプローチの検討]
C --> D[計画の更新]
D --> E[実行の継続]
- 問題の特定
- 根本原因の分析
- 代替アプローチの検討
- 計画の更新
- 実行の継続
classDiagram
class PlanningCoordinator {
-task
-llm_client
-mcp_client
-history_store
+execute_with_planning()
-_planning_phase()
-_execution_phase()
-_execute_verification_phase()
-_reflection_phase()
}
class PlanningHistoryStore {
-history_file_path
+append_entry()
+get_recent_entries()
+load_full_history()
+save_verification()
}
class TaskHandler {
+handle(task)
-_handle_with_planning()
}
TaskHandler --> PlanningCoordinator
PlanningCoordinator --> PlanningHistoryStore
プランニングプロセス全体を調整するコーディネータークラスです。
責務:
- 6つのフェーズの制御
- LLMとの対話管理
- 履歴の管理
- Issue/MRへの進捗コメント投稿
検証フェーズ関連メソッド:
_execute_verification_phase(): 検証フェーズを実行_build_verification_prompt(): 検証プロンプトを構築_build_executed_actions_summary(): 実行済みアクションのサマリー作成_extract_success_criteria(): 成功基準の抽出_post_verification_result(): 検証結果をIssue/MRに投稿_update_checklist_for_additional_work(): 追加作業用にチェックリストを更新
計画と実行の履歴を永続化するストアクラスです。
責務:
- 履歴のJSONL形式での保存
- 履歴の読み込みと参照
- 古い履歴の管理
- 検証結果の保存
計画のサブタスク一覧をMarkdownチェックリスト形式でIssue/MRにコメントします。
計画完了時に以下のフォーマットでコメントを投稿します：
- タイトル（絵文字付き）
- 目標の説明
- チェックリスト項目（未完了状態）
- フッター
- 計画完了時: チェックリストを新規投稿
- 各サブタスク完了時: チェックリストを更新（チェック済みに変更）
- 計画修正時: チェックリストを再投稿
- 検証フェーズで追加作業が必要な場合: 元の計画（完了）と追加作業（未完了）を区別してチェックリストを更新
検証フェーズで追加作業が必要になった場合、以下の形式でチェックリストを更新します：
## 📋 Execution Plan (Verification Round)
### Original Plan (Completed)
- [x] **task_1**: 実装する
- [x] **task_2**: テストを追加
### Additional Work (From Verification)
- [ ] **verification_fix_1**: プレースホルダを完全実装に置き換え
- [ ] **verification_fix_2**: 不足しているテストを追加
*Progress: 2/4 (50%) - Verification found 2 additional items*planningセクションで以下を設定します：
- enabled: プランニングモードの有効/無効（デフォルト: false）
- max_reflection_count: 最大リフレクション回数（デフォルト: 3）
- max_plan_revision_count: 最大計画修正回数（デフォルト: 2）
- reflection_interval: リフレクション間隔（アクション数、デフォルト: 5）
検証フェーズ設定（planning.verification）:
- enabled: 検証フェーズの有効/無効（デフォルト: true）
- max_rounds: 最大検証ラウンド数（デフォルト: 2）
- PLANNING_ENABLED: プランニングモードの有効/無効（true/false）
ツール実行が失敗した場合：
- エラー内容をLLMに通知
- リフレクションを実行
- 代替アプローチを検討
- 必要に応じて計画を修正
計画生成が失敗した場合：
- エラーログを記録
- Issue/MRにエラーコメントを投稿
- 処理を中断
計画修正が最大回数を超えた場合：
- 警告ログを記録
- Issue/MRに警告コメントを投稿
- 現在の計画で実行を継続
検証フェーズで最大ラウンド数に達した場合：
- 検証結果をIssue/MRに投稿
- 特定された問題をリスト化
- タスクを完了として扱う（部分完了として記録）
文書バージョン: 3.0
最終更新日: 2025-01-17
ステータス: 実装済み（検証フェーズ追加）