Agent Teamsの協調が共有ファイルで変わった — 3回の実践記録
個人開発でClaude CodeのAgent Teamsを3回使った。毎回、実行後に振り返り（何がうまくいって、何が問題で、次どうするか）を記録して運用を改善した結果、エンジニア役の修正指示無視が3-4回→1回に、議論の経緯も追えるようになった。
やったことはシンプルで、チーム全員がアクセスできる共有Markdownファイルを置いただけ。この記事では3回の実践で何が起きて、何を直して、何が効いたかを書く。
Agent Teamsとは
Claude Codeの実験的機能で、複数のClaude Codeインスタンスをチームとして協調動作させる仕組み。1つのセッションが「チームリード」として機能し、複数の「チームメイト」にタスクを割り振る。各チームメイトは独立したコンテキストウィンドウを持ち、メッセージで互いにやり取りする。
自分のチーム構成はこう:
| 役割 | 担当 | コード変更 |
|---|---|---|
| PM（チームリード） | 全体指揮、タスク管理、ユーザーへの報告 | ❌ |
| デザイナー | 色、フォント、余白、視覚的バランス | ❌ |
| UI/UX | 操作性、ユーザーフロー、フィードバック設計 | ❌ |
| FEエンジニア | コンポーネント実装（唯一の実装者） | ✅ |
| QA | テスト作成、動作確認 | ✅（テストのみ） |
コードを触るのはFEとQAだけ。PM・デザイナー・UI/UXは提案とレビューに専念する。
問題: 各エージェントが孤立する
Agent Teamsは各エージェントが独立コンテキストで動く。つまり:
- デザイナーが見つけた技術制約を、FEは知らない
- PMが送った修正指示が、FEの会話履歴が上限に達して（コンテキスト枯渇）消える
- 「なぜUIの配置を変えたか」の経緯が、メッセージの中に埋もれて追えない
メッセージは消える。ファイルは残る。 これが出発点。
解決: ホワイトボードパターン
全員がアクセスできる共有ファイル（Markdownファイル）を置いて、発見・事実・決定を書き込む手法。1970年代の音声認識AI（HEARSAY-II）で使われたBlackboard Architectureが原型で、Happy Elements社の記事でAgent Teamsへの適用が紹介されている。
自分のチームでは、この共有ファイルを 2種類に分けた:
| ファイル | 呼び方 | 何が書いてあるか | いつ読むか |
|---|---|---|---|
WHITEBOARD.md |
掲示板 | 最新の事実・決定の一覧 | 作業開始前・レビュー前に必ず |
DISCUSSIONS.md |
議論ボード | トピック単位の議論ログ（問い→議論→決定） | 決定の理由を知りたいとき |
なぜ2つに分けるのか？ 1ファイルだと「今の決定」と「そこに至る議論」が混ざって、どっちも探しにくくなる。
掲示板の良さ:
- 人にとって: 最新の決定・制約が一覧になっているから、チームの現状をサッと把握できる
- AIにとって: 会話履歴が消えても、ファイルを読み返せば最新の決定がわかる。実装前に毎回確認できる
議論ボードの良さ:
- 人にとって: 「なぜこの決定になったか」の経緯が残る。1ファイルだと経緯が制約や事実の間に埋もれて探せない
- AIにとって: 決定が修正されたとき、経緯が残っているからレビュー担当のエージェントが修正理由を参照できる
ただし、最初からこの構成だったわけじゃない。3回の実践で進化した。
結論: 効果のまとめ
先に結果を出す。3回のイテレーションで改善した点:
| 観点 | 第1回（掲示板のみ） | 第2回（議論ボード未作成） | 第3回（2ファイル構成） |
|---|---|---|---|
| 技術制約の共有 | ✅ 事前記載で手戻り減 | ✅ 同様 | ✅ 同様 |
| 議論の経緯 | ❌ 記録なし | ❌ 記録なし | ✅ 6トピック記録 |
| FEの修正指示反映 | — | ❌ 3-4回無視 | ✅ 1回で反映 |
| 決定の見落とし | — | — | ⚠️ 転記漏れで発生 → 対策済 |
第1回: 掲示板だけで始める
WHITEBOARD.md 1ファイルで掲示板だけを試した。
やったこと:
- PMが「接点」を定義（役割間で影響し合う領域。例: サイドバーのデザインはDesigner・UI/UX・FE全員に関わる）
- 技術制約（インラインstyle禁止、テストライブラリの制約等）を掲示板に事前記載
実際の掲示板の内容（抜粋）:
## 掲示板
- [PM] インラインstyle禁止 — Tailwindクラスのみ使用
- [PM] jsdom制約 — navigator.clipboard.writeTextはモック必要
- [PM] 既存UIコンポーネントのパターンに合わせること
結果: デザイナー・UI/UXが具体的なTailwindクラス名で提案 → FEの解釈ズレなし。手戻りは小修正5件のみ。
見えた課題:
- UI/UXがFEに直接レビューを送り、PMに共有されなかった → PM集約が崩れた
- 技術制約がデザイン方針策定前に共有されてなかった
第2回: 議論ボードを追加…したかった
テンプレートに議論ボード（DISCUSSIONS.md）を追加した。が、PMが作成しなかった。
起きた問題:
- PMがWHITEBOARD.mdに「決定事項」セクションを勝手に作り、テンプレート構造を逸脱
- 議論の経緯（誰が何を提案し、なぜその結論になったか）が記録されなかった
- FEがPMの修正指示を3-4回無視。コンテキスト枯渇でメッセージが処理されなかったと推測
テンプレートに追加したもの:
- トピック作成のトリガー（「意見が分かれたとき」「仕様に書かれてない判断が必要なとき」等）
- 排他ルール（「決定はDISCUSSIONS.mdに書く。WHITEBOARD.mdに決定事項セクションを作らない」）
第3回: 2ファイル構成が機能
トリガーと排他ルールを追加した結果、DISCUSSIONS.mdが機能した。
議論ボードの実例（抜粋）:
### トピック2: バッジの配置位置
- [Designer] 右上にアイコンバッジ
- [UI/UX] 右上だと隣接要素と視覚的に混同するリスク。右下推奨
- **決定**: 右上に決定
- **決定（修正）**: 右下に変更。理由: 隣接要素間の視覚的混同リスク
→ 掲示板に転記済み
改善された点:
- 6トピックを記録。議論の経緯が全て追跡可能に
- 配置の決定修正（右上→右下）も、なぜ変わったかが議論ボードに残った。レビュー担当のエージェントが修正理由を後から参照できた
- FEのコンテキスト枯渇問題が大幅改善: FEエージェントが振り返りで「ファイルに書いてあるから、PMからの指示が会話履歴から消えても何度でも読み返せた」と報告。修正指示の無視が3-4回→1回に
新たに見えた問題:
- PMがDISCUSSIONS.mdにだけ決定を書き、掲示板に転記しなかった
- デザイナー・UI/UXが決定の修正を見落とした（掲示板に最新決定がなく、議論ボードのログ途中を探すしかなかった）
テンプレートに追加したもの:
- 決定の転記フロー（
議論ボードで議論→決定→掲示板に1行で転記→全員に通知） - 掲示板の記入基準に「議論ボードで決定した事項」を追加
テンプレート
3回目終了時点のテンプレート。プロジェクトのルートに WHITEBOARD.md と DISCUSSIONS.md を置いて使う。
Agent Teamsの起動プロンプトには、全メンバー共通の指示として以下を含める（起動プロンプトはチームリードにしか渡らないため、各メンバーの指示にも書く）:
- 作業開始前にWHITEBOARD.mdを読み、ルールと掲示板の内容を把握すること
- 議論が発生したらDISCUSSIONS.mdにトピックを作成し、各メンバーは自分の意見を追記すること
- 決定はPMが書く。PMがDISCUSSIONS.mdに決定を記録し、掲示板に1行で転記すること
- 掲示板（WHITEBOARD.md）に書き込むのはPMだけ。他のメンバーは読み取り専用
WHITEBOARD.md テンプレート（クリックで展開）
# WHITEBOARD
## ルール
- **Goal**: {達成すべきことを書く}
- **関係者**:
| 役割 | 担当 | 依存先 |
|---|---|---|
| PM | 全体調整、WHITEBOARD/DISCUSSIONS管理 | 全メンバー |
| {役割名} | {担当領域} | {誰の成果物に依存するか} |
- **接点（Connections）**: {役割間で影響し合う領域を列挙}
- 例: {機能名} — {役割A}(観点) × {役割B}(観点) × {役割C}(観点)
- **掲示板ルール**:
- 書き込むのはPMだけ（ファイル競合を防ぐ）
- 記入基準: 技術制約、既存パターン、DISCUSSIONS.mdで決定した事項
---
## 掲示板
<!-- 最新の事実・決定を追記する。日常の参照先 -->
<!-- 例: [PM] インラインstyle禁止 — CSSフレームワークのクラスのみ使用 -->
<!-- 例: [決定] アイコンはDownloadを使用（トピック1） -->
DISCUSSIONS.md テンプレート（クリックで展開）
# DISCUSSIONS
<!-- トピック作成のトリガー:
- メンバー間で意見が分かれたとき
- 仕様に書かれていない判断が必要なとき
-->
<!-- 排他ルール: 決定はここに書く。WHITEBOARD.mdに「決定事項」セクションを作らない -->
### トピック1: {議論したい問い}
- [{役割}] {意見や提案}
- [{役割}] {別の意見}
- **決定**: {結論と理由}
→ 掲示板に転記済み
<!-- 決定の転記フロー:
1. ここで議論→決定
2. 掲示板に1行で転記
3. 全員に通知
-->
実践から得たルール
- メッセージは消える、ファイルは残る — 重要な情報はファイルに書く。コンテキスト枯渇への根本対策
- 掲示板は日常の参照先、議論ボードはアーカイブ — 決定したら必ず掲示板に転記
- 接点の事前定義が効く — メンバーが「何を報告すべきか」の判断基準になる
- PM集約でファイル競合を防ぐ — 掲示板に書くのはPMだけ。PMはコード書かないので手が空いてる
- テンプレートに書いても使われるとは限らない — トリガー（いつやるか）とフロー（どう流れるか）まで明示する
なぜ効くか
注意点
- PMのコンテキストも消費する。トピック数が多いと負荷が高い
- 全員一致で即決なら議論ボード不要。議論が発生した時だけ使えばいい
次の進化
4回目以降では、議論の中から普遍的な知見を抽出してプロジェクト全体の設定ファイルに配置する「知見のパイプライン」に発展した。これについては別の記事で書く予定。
Discussion