はじめに

Claude Code でカスタムワークフロー（Skills）を自作している方なら、こんな経験があるんじゃないかと思います。

「とにかく成果物を作って、後から直せばいい」と単一エージェントに任せたら、視野が狭くて偏った出力が返ってきた。
修正の指摘を追加してみたが、エージェントは素直に従うだけで「本当にそれでいいのか」という疑問を持ってくれない。
単一エージェントへの長い指示書を書いても、結局「一つの視点からの最適解」を超えられない。

これを解決できるかもしれないっと思ったのが 「作る前に複数エージェントに構成案を議論させる」 パターンです。
既存の Skill のパイプラインに Agent Teams の議論フェーズを差し込むだけで、単一エージェントでは引き出せなかった多角的な改善提案が生まれます。

この記事で分かる3点を最初に示します。

Agent Teams の基本アーキテクチャと通常パイプラインとの違い
既存の Skill に議論フェーズを差し込む具体的な実装方法（設計ファイル2つの中身）
議論プロトコルの設計指針と、向いているユースケースの判断基準

記事執筆を実例として使いますが、コードレビュー・技術選定・設計議論など、あらゆるカスタムワークフローに同じパターンを応用できます。

全体アーキテクチャ -- Skill + Agent Teams の関係

まず、通常のパイプラインと Agent Teams 挿入後のパイプラインを比較してみましょう。

通常パイプライン

Agent Teams 挿入後のパイプライン（`--teams` モード）

planner が策定した構成案を、3つのエージェントがそれぞれ独自の視点で評価し、お互いに議論します。
その議論を経た refined な構成案だけを worker に渡すので、worker は「すでに多角的に検討済みの案」を受け取ることになります。

どんなワークフローに適用できるか

ワークフロー	チーム構成例
記事執筆	構成エキスパート / 技術精度エキスパート / 読者体験エキスパート
コードレビュー	セキュリティ専門家 / パフォーマンス専門家 / 可読性専門家
設計議論	スケーラビリティ重視 / 実装コスト重視 / 保守性重視
技術選定	技術的成熟度評価 / チーム習熟度評価 / 長期コスト評価

今回は、既存のSkillsを壊したくなかったので--teams オプションで切り替え可能にしてます。

実際の議論を覗いてみる

「百聞は一見に如かず」なので、実際に Agent Teams が行った議論を見てみましょう。
以下は debate-result.md に記録された、3エージェントによる記事構成議論の抜粋です。

議論の対象: useState / useEffect は使えるがカスタムフックをまだ書いたことがない初級入門者向けの「React カスタムフック入門」記事。

planner が策定した8セクションの構成案を、structure-agent・tech-agent・reader-agent の3者が評価しました。

議論では複数の論点が生まれましたが、ここでは特に鋭い対立が起きた2つを抜粋します。

論点1: セクション順序「落とし穴 vs 設計指針」

planner の構成案は「設計指針 → 落とし穴」の順でしたが、structure-agent が順序変更を提案しました。

「落とし穴を設計指針の前に移動すべき。失敗パターンを先に見せることで設計指針の説得力が増す」

reader-agent もすぐに同意し、tech-agent も「概ね同意、ただし基本ルールとの重複に注意」と条件付きで賛成。
3者が同じ方向を向いたため、1往復で全員合意という珍しいケースになりました。

論点2: Server Components への言及

前提: カスタムフックは useState などのフックを内部で使うため、React Server Components（RSC）では使えません。Next.js 等でカスタムフックを含むコンポーネントを使う場合、'use client' ディレクティブの宣言が必要になります。planner の構成案はこれを「設計指針」セクションで言及していました。
問題は「初心者向け記事で RSC に触れるべきか」という判断でした。

この論点では、最も鋭い対立が起きました。

tech-agent の主張（初回 broadcast）:

「削除ではなく 'use client' の一文に圧縮。技術的に正確であり完全削除は不誠実」

tech-agent は「嘘をつかない」という技術的誠実さを重視し、削除には断固反対しました。

reader-agent の反発（直接 SendMessage）:

「削除または脚注への隔離を主張。対象読者の認知負荷を増大させるリスクが高い」

reader-agent は「対象読者はまだ RSC を学ぶ段階ではない」という読者視点から、完全削除を主張。
tech-agent の「不誠実」という言葉に対して、「完全な説明を省くことが不誠実なら、初心者向け記事は全部不誠実になる」と反論しています。

structure-agent による折衷案（2往復目）:

「設計指針セクションに収める形で一文に圧縮し、『詳細は別記事』という誘導を添えれば両立できる」

structure-agent が両者の主張を引き取り、セクション配置という構成の問題として再定義することで収束させました。

最終合意:

'use client' ディレクティブが必要 という1文と補足注記に圧縮し、RSC 詳細は削除

tech-agent は「圧縮は妥当」と認め、reader-agent は「隔離の形ならよい」と立場を変化させています。

論点3: `useFetch` の扱い

発言者	主張
tech-agent	具体的なコードが必須。骨格だけでも示せ。React 19 の `use()` フックへの注記も追加すべき
reader-agent	AbortController の説明が不足すると初級入門者が混乱する。「この目的で使う」という一文を追加すべき
structure-agent	useFetch の分量が他の2パターンより重くなることによる読者離脱リスクを指摘。React 19 注記はサイドメモ扱いに

3者の主張が噛み合うことで、「コードは掲載する（tech 支持）」「AbortController は一文説明を付ける（reader 支持）」「React 19 注記は注記ブロックに隔離する（structure 支持）」という三者妥協案が生まれました。

定量情報: この議論では、3つの論点それぞれで最低2往復のやり取りが行われ、元の構成案から5箇所の具体的な改善が生まれました。

議論の成果 -- Before / After

議論によって構成案がどう変化したかを対比します。

セクション構成の変化

#	Before（元の構成案）	After（refined 構成案）	変化の出所
1	はじめに	はじめに（基本ルールを統合）	structure-agent: 「冒頭を軽くして本題への到達を早めよ」
2	カスタムフックの基本ルール	実践パターン1: useFormInput	structure-agent + reader-agent の合意
3	実践パターン1: useFormInput	実践パターン2: useFetch	-
4	実践パターン2: useFetch	実践パターン3: useLocalStorage	-
5	実践パターン3: useLocalStorage	よくある落とし穴	structure-agent: 「落とし穴→設計指針の順の方が説得力が増す」
6	カスタムフックを書くときの設計指針	カスタムフックを書くときの設計指針（Server Components 注記を統合）	3者の折衷案
7	よくある落とし穴	まとめ（次のステップ3点を明示）	reader-agent: 「まとめに具体的なアクションが必須」
8	まとめ	-	-

元の8セクションから7セクション（基本ルールを統合し、重複なく整理）へ再編されました。

この変化は単一エージェントへの指示では引き出せなかった視点から生まれています。
構成担当・技術担当・読者担当がそれぞれ独立して評価し、互いの論点に反発・納得・折衷を繰り返したからこそ、「セクション削除」「順序変更」「注記の隔離」という具体的かつ多方向な改善が同時に起きました。
単一エージェントにいくら「複数の観点から評価して」と言っても、自分自身に反論することはできないのです。

設計ファイル1: team-workflow.md -- 汎用議論プロトコル

Agent Teams の議論を機能させる核心は .claude/rules/common/team-workflow.md に書かれた汎用プロトコルです。

5ステップのワークフロー

.claude/rules/common/team-workflow.md（抜粋）

### ステップ1: タスク実行

担当タスクを実行し、成果物（調査結果・コード・レポート等）をまとめよ。

### ステップ2: タスク完了の記録

TaskUpdate(taskId="...", status="completed")

### ステップ3: 成果の共有（必須）

タスク完了後、全チームメンバーに向けて成果を共有せよ。

SendMessage(
  type="broadcast",
  content="[自身の担当領域の調査結果・成果の要約]",
  summary="[5〜10語の要約]"
)

### ステップ4: リアクション議論（必須・最重要）

他メンバーの共有を受け取ったら、即座に・率直に・感情を込めて反応せよ。

### ステップ5: チームリードへ最終報告

議論プロトコルの要件

ステップ4が最も重要です。
以下の4つの要件が明示されています。

team-workflow.md（議論プロトコル部分）

- 驚き・納得・反発 を率直に表明せよ
  - 例: 「それは詭弁だ。なぜなら…」

- 相手の論の具体的な箇所を引用して反応せよ
  - 例: 「『93%が再選択』という主張だが、これはサバイバーバイアスではないか」

- 自分の立場がどう変化したか（あるいはしなかったか）を明示せよ
  - 例: 「この点については考えを改める必要がある」

- 新たな疑問や反論を積極的に投げ返せ
  - 例: 「では、〇〇の場合はどう説明する？」

これが「単なるフィードバック交換」ではなく「本物の議論」になる鍵です。
「ご意見ありがとうございます」式の礼儀正しいやり取りに終始させないために、プロトコルが感情表明・引用・立場変化の明示・最低2往復を明示的に要求しています。

broadcast と直接 SendMessage の使い分け

初回共有: SendMessage(type="broadcast") -- 全メンバーへ同時共有
以降の議論: SendMessage(type="message", recipient="[相手名]") -- 特定メンバーへ直接

broadcastは最初の評価共有にのみ使います。
その後の議論は1対1の直接メッセージで行うことで、特定の論点についての深い往復が可能になります。

なぜ `.claude/rules/common/` に置くのか

Claude Code は .claude/rules/common/ 配下のファイルを全プロジェクト・全セッションで自動読み込みします。
team-workflow.md はどのプロジェクトの Skill からでも参照できる汎用資産として、ここに配置するのが適切です。
特定プロジェクト専用のルールは .claude/rules/ に置くとプロジェクト内で有効になります。

設計ファイル2: debate-team.md -- タスク特化チーム定義

汎用プロトコルに対して、debate-team.md はタスク特化のチーム定義です。

チーム構成の定義

.claude/skills/qiita-writer/agents/debate-team.md（チーム構成部分）

## チーム構成

| メンバー | 役割 | 担当観点 |
|---|---|---|
| structure-agent | 構成エキスパート | 論理フロー・セクション順序・記事の流れ |
| tech-agent | 技術精度エキスパート | コード例の正確性・技術的深さ・バージョン整合性 |
| reader-agent | 読者体験エキスパート | わかりやすさ・対象読者への適切さ・冗長性 |

3人という人数は意図的です。
2人だと対立が膠着しやすく（票が割れると収束しない）、4人以上だと収束に時間がかかり議論が拡散します。
3人の場合、2人が合意すれば多数決的に収束しつつ、1人が異論を保持できます。

スポーンプロンプトの構造

各エージェントへのスポーンプロンプトは「評価観点」と「完了後の手順」の2部構成です。

debate-team.md（structure-agent スポーンプロンプト）

あなたは「構成エキスパート」として、以下の記事構成案を評価せよ。

[planner の構成案JSONをここに貼る]

評価観点:
- セクションの論理的な順序は適切か
- 読者が「なぜ」「どうやって」「次に何をすべきか」を理解できる流れか
- セクション数・分量のバランス
- はじめに・本編・まとめの三部構成として成立しているか

## 完了後の手順（必須）
1. TaskUpdate でタスクを completed に更新
2. SendMessage(broadcast) で評価結果と改善提案を全メンバーに共有
3. 他メンバーの報告を受け取ったら、即座に・率直に・感情を込めてリアクションを SendMessage で返せ
   - 相手の論の具体的な箇所を引用して反応せよ
   - 驚き・納得・反発を率直に表明せよ
   - 自分の立場がどう変化したか明示せよ
   - 最低2往復のやり取りを行ってから収束させよ
4. 議論完了後、チームリード（team-lead）に最終報告を送れ
   （最終報告には「相手の主張で認めた点」「同意できなかった点」「議論で変化した考え」を含めること）

「完了後の手順」は .claude/rules/common/team-workflow.md と内容が重複しています。
これは意図的な設計です。グローバルルールの読み込みは保証されますが、スポーンプロンプトに直接書くことでエージェントが「このタスクで必須」と認識する確実性が上がります。

並列スポーンのポイント

3エージェントを同一メッセージ内で同時に起動することが重要です。
順次起動では最初のエージェントの評価が後のエージェントに影響し、独立した視点が失われます。

チームの解散手順

// 全メンバーの最終報告が揃ったら
SendMessage(type="shutdown_request")  // 各メンバーへ個別に送信
TeamDelete                            // チームを削除

解散を忘れると不要なエージェントが残り続けます。
md レポート出力の完了を確認してから解散するのが正しい順序です。

自分のワークフローに適用するためのステップ

Step 1: team-workflow.md を配置する

mkdir -p .claude/rules/common
# team-workflow.md をここに配置

.claude/rules/common/ に配置すると Claude Code が全セッションで自動読み込みします。
すでにある場合はスキップしてください。

Step 2: タスク特化の debate-team.md を作成する

以下が最小テンプレートです。

agents/debate-team.md（最小テンプレート）

# [タスク名] Debate Team

[タスクの説明]

## チーム構成

| メンバー | 役割 | 担当観点 |
|---|---|---|
| agent-a | [役割名] | [評価観点] |
| agent-b | [役割名] | [評価観点] |
| agent-c | [役割名] | [評価観点] |

## オーケストレーターの手順

### Step 1: 3エージェントを並列スポーン

**agent-a へのプロンプト**:
あなたは「[役割名]」として、以下の[対象物]を評価せよ。

[対象物の内容をここに貼る]

評価観点:
- [観点1]
- [観点2]
- [観点3]

## 完了後の手順（必須）
1. TaskUpdate でタスクを completed に更新
2. SendMessage(broadcast) で評価結果と改善提案を全メンバーに共有
3. 他メンバーの報告を受け取ったら、即座に・率直に・感情を込めてリアクションを SendMessage で返せ
   - 最低2往復のやり取りを行ってから収束させよ
4. 議論完了後、チームリード（team-lead）に最終報告を送れ

（agent-b, agent-c も同様の構造で記述）

### Step 2: 全メンバーの最終報告を待つ

### Step 3: 議論結果を Markdown に出力

[team-name]-result.md を保存先ディレクトリに出力。

### Step 4: チームを解散

SendMessage(type="shutdown_request") → TeamDelete

Step 3: SKILL.md に `--teams` オプションを追加する

既存の SKILL.md に以下を追加します。

SKILL.md への追記例

## オプション

| オプション | 説明 |
|---|---|
| `--teams` | Agent Teams による多角的議論モードを有効化 |

## `--teams` モードのフロー

### Step 1: planner を起動（通常モードと同じ）

### Step 2: debate-team を起動（--teams 専用）

`agents/debate-team.md` の手順に従い、3エージェントを並列スポーン。
議論完了後、[task-name]-result.md を出力。

### Step 3: worker を起動

refined な成果物仕様を渡すこと（planner の元案ではなく debate-team の出力を使う）。

（以降は通常モードと同じ）

他ワークフローへの応用例:

コードレビューチーム（セキュリティ/パフォーマンス/可読性の3視点）: --review-teams フラグで設計議論前にコードを多角的評価
設計議論チーム（スケーラビリティ/実装コスト/保守性の3視点）: アーキテクチャ決定の前に複数案を議論

設計上の Tips と注意点

エージェント数は3が最適

2人: 対立が膠着しやすい。どちらかが折れないと収束しない
3人: 2対1の多数決が生まれやすく収束しやすい。1人の異論が残ることで多様性も保たれる
4人以上: 全員に発言機会が生まれるため議論が拡散し、収束に時間がかかる

議論ルールの全要件が揃って初めて機能する

「驚き・納得・反発の表明」「相手の論の具体的な引用」「自分の立場変化の明示」「最低2往復」の4要件は、どれか一つでも欠けると議論が形骸化します。
特に「立場変化の明示」がないと、エージェントが意見を変えたのか変えていないのかが分からず、収束の判断ができません。

向いているユースケース / 向いていないユースケース

向いている	向いていない
複雑な成果物の設計（多角的評価が有効）	定型フォーマットへの変換（評価の余地がない）
「正解が一つでない」トレードオフの判断	単純な検索・集計・変換処理
長期間使い回す重要な設計の意思決定	1回限りの使い捨てタスク
対象読者・品質基準が複数の観点から存在する成果物	明確な仕様が既に決まっているタスク

議論フェーズは追加のコストと時間がかかります。
単純な成果物生成や明確な仕様が既にある場合は通常モードの方が効率的です。
--teams はオプションとして設計し、必要な場面でだけ使うのが正解です。

議論レポートが残る価値

debate-result.md のような議論レポートは、成果物そのものと同じくらい価値があります。
「なぜこの構成になったのか」「どの案が却下されてその理由は何か」が追跡可能になります。
数週間後に「なぜここをこうしたんだっけ」となったとき、レポートを見れば議論の経緯が分かります。
これは単一エージェントワークフローでは絶対に得られない副産物です。

まとめ

「作る前に議論させる」パターンの価値を整理します。

単一エージェントは「一つの視点からの最適解」しか出せない。Agent Teams は複数の独立した視点を持つエージェントに議論させることで、単一エージェントでは引き出せなかった改善を実現する
必要なファイルは2つ: 汎用議論プロトコルの team-workflow.md と、タスク特化チーム定義の debate-team.md
既存の Skill に --teams オプションを追加するだけで段階的に導入できる。通常モードを壊す必要はない
議論レポートは「なぜその設計になったか」の追跡可能な根拠として残り続ける
他ワークフローへの応用（コードレビューチーム等）が可能

Agents Teamが今後出力品質を維持するためには必須になってくる予感がしました。

参考