Claude Codeのマルチエージェント機能を仕事で試してみました。Manager・Developer・Tester・Security・UX Reviewerの5役に分けてワークフローを設計したところ、自分が確認するのは「Managerからの最終報告だけ」になり、確認コストが体感で大きく下がりました。「試してみた」レベルの記事ですが、構成とポイントをまとめます。
対象読者: Claude Codeを使っていて、1エージェント運用に限界を感じている人。AIに実装は任せられてきたけど、レビューや確認は全部自分、という状況を変えたい人。
はじめに
「AIに任せたいけど、結局自分が全部チェックするの？」という感覚、ありませんか？
チャット1本で開発を進めていたころは、まさにそれでした。AIが書いたコードを自分でレビューして、テストして、セキュリティ観点で確認して…結局エンジニアとしての確認工数はあまり減らない。
マルチエージェントを使って、その感覚が少し変わりました。完全自動化には程遠いですが、「丸投げできる未来が近づいてる」という手触りは確かにありました。
前提：ドキュメント駆動開発との組み合わせ
マルチエージェントの前に、ドキュメント駆動開発が必須です。
以前こんな記事を書きました。
要件定義・設計・仕様をMarkdownで固めてからAIに渡すと、手戻りが激減します。マルチエージェントでも、この「事前にドキュメントを固める」ステップは変わりません。むしろ、エージェントが複数になるぶん、仕様の曖昧さが各エージェントの誤動作として連鎖・増幅します。
ドキュメントの作り方は上の記事を参考にしてください。この記事では、ドキュメントが固まった後の話をします。
マルチエージェントの構成
今回は以下の5役割でエージェントを分けました。
| 役割 | 担当 |
|---|---|
| Manager | ユーザーとの窓口・要件整理・各エージェントへの指示・最終判断 |
| Developer | 実装（work/ 配下のコードのみ触れる） |
| Tester | テスト実行・検証 |
| Security | セキュリティ観点でのレビュー（read-only） |
| UX Reviewer | UX・デザイン観点でのレビュー（read-only） |
ポイントは「ユーザーが触るのはManagerだけ」という点です。
チャット開発のときは：
ユーザー → AI（全部1体）
└ 実装して
└ テストして
└ セキュリティ確認して
└ UX確認して
└ ユーザーが全部最終チェック ← ここが重い
マルチエージェントでは（代表フロー）：
ユーザー → Manager（仕様固め）
Manager → Security / UX Reviewer（実装前の設計レビュー）
Manager → Developer（実装）
Manager → Tester / Security / UX Reviewer（実装後レビュー）
Manager → ユーザー（最終報告のみ）
各エージェントが自分の専門観点でレビューし、問題があればManagerがDeveloperへ再依頼を出す、というループをワークフロー定義で制御します。ユーザーに来るのは「完了報告」か「エスカレーション」だけです。
ループ上限について: SecurityとUX Reviewerの差し戻しはそれぞれ独立して最大3回までカウントします。Tester由来の差し戻しは上限対象外で、テスト失敗がある限り修正ループが続きます。3回で合意できなければManagerがUserにエスカレーションします。
補足: 「自動でやり直し」といっても、Claude Codeが勝手にループするわけではありません。ManagerエージェントがワークフローのMarkdown定義を読んで「問題があればDeveloperへ差し戻す」という判断をする、という設計です。ツールやスクリプトによる自動化ではなく、Managerの役割定義によって制御しています。
なぜこの設計にしたか
役割分離の主目的は「品質向上」よりも確認責任の集中を避けることです。
チャット1本では、実装・テスト・レビューの判断が全部1つのコンテキストに混在します。その結果、レビューが甘くなる（自分の実装を自分で評価する）か、確認する人間（自分）のコストが増えるか、どちらかになります。
役割を分けることで：
- Developerは実装に集中し、レビュー観点を持ち込まない
- SecurityはSecurityだけを見るので、見落としが減る
- Managerはコードを書かないので、仕様の整合性だけに集中できる
また work/ 配下への制限と3回ループ上限は、エージェントが暴走したり無限ループに陥るリスクを最小化するための設計判断です。
リポジトリ構造
AiCompany/
├── CLAUDE.md # Claude Codeへの入口（エージェントが最初に読む）
├── MULTI_AGENT_WORKFLOW.md # エージェント全体のルール定義
└── roles/ # 各役割の定義ファイル
├── MANAGER.md
├── DEVELOPER.md
├── TESTER.md
├── SECURITY.md
└── UX_REVIEWER.md
MULTI_AGENT_WORKFLOW.md
全エージェント共通のルールを定義するファイルです。主な内容：
- 進め方の手順（User→Manager→Developer→Tester→Manager→Userの流れ）
- 権限マトリクス（誰が何を読み書きできるか）
- レビューループの収束条件（同一案件でのやり直しは最大3回まで、超えたらエスカレーション）
- 禁止事項（Managerは実装しない、DeveloperはSpecDocsを変更しない、など）
このファイルがあることで、エージェントが迷ったときの「立ち戻り先」になります。
roles/MANAGER.md の要点
Managerには依頼テンプレートが定義されています。
## Task
- 目的:
- 背景:
## Scope
- 変更してよいファイル / モジュール:
- 触ってはいけない範囲:
## Requirements
- 要件:
## Acceptance Criteria
- [ ] 条件:
## Constraints
- 実装は `work/` 配下に置く
これをDeveloperへの依頼時に使うことで、「何をどこまでやるか」が明確になります。Security・UX Reviewer・Testerへの依頼テンプレートもそれぞれ定義されています。
work/ ディレクトリの分離（ルール定義）
ワークフロー定義では、Developerが触れるのはwork/の中だけ、というルールになっています。これはOSやツールレベルの強制ではなく、役割定義のMarkdownに明記することでエージェントに守らせる運用上のルールです。
-
MULTI_AGENT_WORKFLOW.mdやroles/はManagerのみ更新可（参照は各ロールが行う） - Developerが
work/の外を書き換えると、ワークフロー定義自体が壊れるのを防ぐ目的
実案件が発生したタイミングでwork/を作成し、実装コードをすべてここに置く運用を想定しています。エージェントに明示的なスコープを与えることで、意図しない変更が広がるリスクを抑えられます。
Markdownで定義することのポイント
エージェントのコンテキストをMarkdownで制御する
Claude Codeはプロジェクト内のMarkdownファイル（特にCLAUDE.md）をコンテキストとして読み込みます。つまりルールをMarkdownで書く＝エージェントへの指示書になります。
役割定義ファイル（roles/MANAGER.mdなど）をCLAUDE.mdから参照させることで、「このプロジェクトでどう動くべきか」をエージェントに永続的に伝えられます。
# CLAUDE.md（記述例）
このプロジェクトはマルチエージェントで開発します。
作業前に必ず `MULTI_AGENT_WORKFLOW.md` を読み、自分の役割を確認してください。
役割の詳細は `roles/` 配下の該当ファイルを参照してください。
Claude Codeは起動時にCLAUDE.mdをコンテキストとして参照しやすいため、ここにルールを書いておくと役割に応じた行動を促しやすくなります。詳細なルール（権限・禁止事項・テンプレート）はroles/に分離しているので、CLAUDE.md自体はシンプルに保てます。
権限を明示する
## 権限マトリクス
| Role | Spec Docs | Prod Code | Test Code |
|-----------|-------------|-------------|-------------|
| Manager | Read/Write | Read Only | Read Only |
| Developer | Read Only | Read/Write | Read/Write |
| Security | Read Only | Read Only | Read Only |
テーブルで権限を定義しておくと、エージェントが「これは自分がやっていい作業か」を判断しやすくなります。
「やらないこと」を書く
## やらないこと
- 実装コードを直接編集しない
- 曖昧な仕様のまま実装を始めさせない
- `Tester` の確認前に完了扱いにしない
制約の明示がないと、エージェントは「良かれと思って」スコープ外を触ります。禁止事項の定義は地味ですが効果が高い。
運用してわかったメリット
確認コストが明らかに減った
チャット1本のときは、AIが実装したコードを自分でレビューする必要がありました。マルチエージェントでは、SecurityエージェントがセキュリティリスクをSeverity付きでレポートし、UX ReviewerがUX問題を列挙し、Testerがテスト結果を返してきます。
自分が確認するのは「Managerからの最終報告」だけ。各専門観点からのチェックは済んでいる状態です。
各エージェントのレビューが専門観点に集中している
SecurityエージェントはUXを気にしなくていい、TesterはSecurityを気にしなくていい。役割が分かれているぶん、各エージェントのレビューが深くなる感覚がありました。チャット1本で「全部見て」と頼むより、的を絞った指摘が出やすいです。
運用してわかった課題
最初のドキュメント整備コストは減らない（むしろ増える）
エージェントが複数いる分、仕様の曖昧さが各エージェントの誤動作として増幅します。ドキュメント駆動開発の習慣がない状態でマルチエージェントに移行しても、混乱するだけだと思います。
ロール定義の質が出力の質に直結する
「SecurityエージェントはどこまでをRead Onlyにするか」「Testerは何をもって完了とするか」など、役割定義の設計が甘いと途中で詰まります。最初はシンプルに始めて、実際に使いながら育てていくのが良いと感じました。
失敗したケース: Testerの完了条件を曖昧に書いたまま運用したところ、「テスト実行した」だけで完了扱いになり、Managerへの返却フォーマットが空欄だらけで戻ってきました。完了条件を具体的に定義し直して解決しました。
「丸投げ時代」は近づいていると思う
完全自動化はまだ先ですが、確認の構造が変わりました。
チャット開発は「AIが提案→自分が確認→自分が判断」の繰り返しでした。マルチエージェントは「AIが実装→AIが専門観点でレビュー→ManagerがDeveloperへ差し戻し→自分は最終判断だけ」になっています。
自分が関与する場所が「仕様を固める最初」と「エスカレーションの最終判断」だけになりつつある。
AI活用そのものより、運用ルールを設計して破綻しにくい形に落とし込むことに価値がある、と今回改めて感じました。エンジニアとして「どう使うか」の設計力が、これからの差になると思います。
まとめ
| チャット1本 | マルチエージェント | |
|---|---|---|
| 確認コスト | 高い（全部自分） | 低い（Managerからの報告だけ） |
| やり直し | 手動で指示 | Managerがループを制御 |
| ドキュメント | あると便利 | 必須 |
| 初期設定コスト | 低い | 高い |
| スケール感 | 個人作業レベル | チーム開発に近い感覚 |
Claude Codeでマルチエージェントを始める手順
-
CLAUDE.mdを作り、MULTI_AGENT_WORKFLOW.mdとroles/を参照するよう書く -
MULTI_AGENT_WORKFLOW.mdを作り、役割・権限・ループ条件を定義する -
roles/MANAGER.mdなど各ロールのMarkdownを作る（依頼テンプレートと禁止事項を必ず入れる） - 実案件が来たら
work/ディレクトリを作り、Developerの作業領域を分離する - まずは小さい機能追加1つで試す（Managerにだけ依頼を出す）
設定ファイル一式は GitHub で公開しています。特に MULTI_AGENT_WORKFLOW.md と roles/MANAGER.md から読むと設計意図がわかりやすいです。
ドキュメントの作り方はこちらの記事（AI開発の最短ルート：ドキュメント先行で手戻りを約9割削減）を参考にしてください。この記事で紹介したワークフロー定義は GitHub で公開しています。