team-plan

Team Plan

5つの専門エージェントがチームでコードベースを調査・議論し、 AI 間で十分に話し合って合意形成した上で Plan Mode の実装計画を作成する。 不明点はユーザーに質問し、手戻りのない計画を目指す。

ワークフロー概要

Step 1: タスク受領・チーム作成
Step 2: 並列調査（researcher + analyst + pattern-expert）
Step 3: 議論・合意形成（architect 主導、全員参加）
        ↳ 不明点 → リーダー経由でユーザーに質問 → 回答を共有
Step 4: 計画書作成（plan-writer → 全員レビュー）
Step 5: Plan Mode（リーダーが計画書をもとに作成、ユーザー承認）
Step 6: 実装（承認後）
Step 7: クリーンアップ

---

Step 1: タスク受領・チーム作成

1a: フルチーム起動 vs スキップ

フルチーム起動（1つでも該当すれば）:

• 複数ファイルにまたがる変更
• 影響範囲が不明
• 複数のアプローチが考えられる
• 既存の設計パターンの理解が必要

スキップ条件（以下を 全て 満たす場合は直接 EnterPlanMode へ）:

• 変更対象のファイルパスがユーザーから明示されている
• 単一ファイル内の 1〜3 行の変更（typo 修正・定数値の変更等）
• 他のファイルへの影響が明らかにない

「簡単そうだから」という主観的な判断でのスキップは禁止。

1b: チーム作成

TeamCreate で team-plan チームを作成。

name	役割	視点	主な手段
code-researcher	コードベース調査・既存実装の把握	「何がある」	Read, Grep, Glob, Task(全タイプ)
dependency-analyst	依存関係・影響範囲・リスク評価	「何が壊れる」	Read, Grep, Glob, Task(全タイプ), WebSearch, WebFetch
pattern-expert	類似パターン・命名規則・慣例分析	「どう書くべき」	Read, Grep, Glob, Task(全タイプ)
solution-architect	実装方針設計・議論リード・合意形成	「どう実装する」	Read, Grep, Glob, WebSearch
plan-writer	議論の統合・計画書の執筆	「どう伝える」	Read, Grep, Glob, Write, Edit

1c: タスク作成

TaskCreate で6つのタスクを作成:

1. code-researcher: コードベース調査（依存なし）
2. dependency-analyst: 依存関係・影響分析（依存なし）
3. pattern-expert: 類似パターン・慣例分析（依存なし）
4. solution-architect: 実装方針設計・議論リード（addBlockedBy: ["1","2","3"]）
5. plan-writer: 計画書作成（addBlockedBy: ["4"]）
6. team-lead: Plan Mode 作成（addBlockedBy: ["5"]）

1d: エージェント起動

5エージェントを 1つのメッセージで並列に Task ツールで起動する。

subagent_type: "team-plan:{role-name}"
team_name: "team-plan"
name: "{role-name}"
mode: "bypassPermissions"
run_in_background: true

プロンプトに含める情報（省略禁止）:

• ユーザーのタスク説明（原文をそのまま）
• 作業ディレクトリの絶対パス
• 計画書の出力先パス: {作業ディレクトリ}/.claude/team-plan-output/plan.md
• CLAUDE.md のプロジェクト固有ルール（あれば要約）
• チームメンバー一覧（名前と役割）

---

Step 2: 並列調査フェーズ

Round 1（並列）:
  code-researcher  → 変更対象のファイル・関数・クラスを特定
  dependency-analyst → 依存関係マッピング、影響範囲分析
  pattern-expert    → 類似実装、命名規則、コードベースの慣例を分析

3エージェントが並列に調査し、それぞれの調査結果を solution-architect に共有する。 リーダーは待機。

---

Step 3: 議論・合意形成フェーズ

Round 2（議論）:
  solution-architect → 調査結果を統合し実装方針を提案（broadcast）
  code-researcher    → 方針に対するフィードバック（見落としファイル等）
  dependency-analyst → リスク観点からの批判的レビュー
  pattern-expert     → 慣例・パターンとの整合性をチェック
  solution-architect → フィードバックを踏まえて方針を修正・再提案

ユーザー質問エスカレーションプロトコル

議論の過程で「ユーザーに確認が必要」と判断された場合:

1. エージェント → team-lead に以下の形式で SendMessage:

[USER-QUESTION]
質問: {質問内容}
背景: {なぜこの情報が必要か}
選択肢（あれば）:
- A: {選択肢A}
- B: {選択肢B}

2. リーダー → ユーザー に AskUserQuestion で質問

3. リーダー → 全エージェント に broadcast でユーザーの回答を共有:

SendMessage(
  type: "broadcast",
  content: "[USER-ANSWER] {質問者} の質問に対するユーザーの回答:
{回答内容}
引き続き議論を進めてください。",
  summary: "ユーザー回答共有"
)

リーダーの行動ルール

• 見守りが基本: エージェントの議論には介入しない
• 介入タイミング:
  • [USER-QUESTION] を受信した時 → ユーザーに質問して回答を返す
  • 同じ議論が 3 往復以上繰り返される時 → 方向性を指示
  • エージェントが blockedBy 待ちのまま進まない時 → 状況を確認
  • 明らかに方向性がずれている時 → 軌道修正

---

Step 4: 計画書作成フェーズ

Round 3:
  plan-writer        → 議論の合意内容を計画書にまとめて書き出す
  solution-architect → 計画書をレビュー（方針との整合性）
  code-researcher    → 計画書をレビュー（ファイルパスの正確性）
  dependency-analyst → 計画書をレビュー（リスク対策の網羅性）
  pattern-expert     → 計画書をレビュー（慣例との整合性）
  plan-writer        → フィードバックを反映して最終化
  plan-writer        → team-lead に完成を報告

計画書は {作業ディレクトリ}/.claude/team-plan-output/plan.md に書き出される。

---

Step 5: Plan Mode

1. plan-writer から完成報告を受け取る
2. .claude/team-plan-output/plan.md を Read で読み込む
3. EnterPlanMode を呼び出す
4. 計画書の内容を Plan ファイルに転記（必要に応じて補足・調整）
5. 変更対象ファイルの該当箇所を Read で直接確認し、計画書との整合性を検証
6. ExitPlanMode でユーザーの承認を求める

Plan ファイルの構造

## 実装計画

### チーム調査・議論で判明した事項
- 既存構造の概要（変更対象ファイルと役割）
- 依存関係と影響範囲
- コードベースの慣例・パターン
- リスク・注意点
- ユーザーへの質問で確認した事項（あれば）

### 変更対象ファイル一覧
| ファイル | 変更内容 |
|---------|---------|
| {絶対パス} | {何をどう変えるか} |

### 実装ステップ（順序付き）
1. {具体的なステップ}
   - 対象: {ファイルパス}
   - 挿入位置の目印: {周辺コード・関数名}

### テスト計画
- {確認すべきこと}

### リスク・注意点
- {リスクと対策}

### 検討した代替案
- {採用しなかったアプローチとその理由}

Note: 行番号は参考情報。実装時は必ず Read でファイルを再確認すること。

---

Step 6: ユーザー承認後の実装

承認された場合

実装を開始する。以下のガイドラインに従う:

• 実装前に必ずファイルを再読み込みする: 編集対象のファイルは Edit の直前に必ず Read で最新内容を取得し、old_string に使う文字列を目視確認すること
• 行番号ではなくコンテキスト（周辺コード）で編集位置を特定する: Edit ツールの old_string には十分な周辺コンテキストを含める
• 計画通りのステップで実装する
• 計画外の変更が必要になった場合: 即座にユーザーに報告し、続けてよいか確認する
• 各ステップ完了後に簡潔に進捗を報告する
• エラーが発生した場合は原因を分析し、計画の見直しを提案する

修正を求められた場合

EnterPlanMode に戻り、ユーザーのフィードバックをもとに計画を更新する。 必要であればエージェントチームを再起動して追加調査。

---

Step 7: クリーンアップ

1. 全エージェントに shutdown_request を送信
2. 全員シャットダウン後に TeamDelete でチーム削除

---

注意事項

• 並列起動を徹底: 5エージェントを常に1メッセージで同時起動
• Plan Mode を省略しない: チームの合意があっても必ず Plan Mode を経由してユーザーの承認を得る
• ユーザー質問は必ずリーダー経由: エージェントは直接ユーザーに聞けない。リーダーが AskUserQuestion で橋渡しする
• 実装は Plan Mode 承認後: チーム議論中にコードを変更しない
• Explore サブエージェント: 調査エージェント (code-researcher, dependency-analyst, pattern-expert) は Task(Explore) を自由に並列起動して調査を分担できる。体数制限なし
• コスト意識: 軽微な変更にはスキップ条件を適用する