Agent Teamと「チームとして」会話する技術

# Agent Team の構造

Leader（オーケストレーター）
├── TaskCreate    # タスクリスト作成
├── Task          # チームメイト起動（並列可）
├── SendMessage   # チームメイトへの指示
└── TaskUpdate    # 進捗管理

Teammate A（Haiku / Sonnet）
├── 自分のタスクを TaskGet で取得
├── 作業実行（Read, Write, Bash等）
├── SendMessage でリーダーに報告
└── TaskUpdate で完了を記録

Teammate B（Haiku / Sonnet）
└── ... 同様に独立して作業

# BAD: 2エージェントが同じファイルを触る
Task 1: "APIハンドラーとバリデーションを実装"  → src/handler.ts
Task 2: "エラーハンドリングを実装"            → src/handler.ts  ← 衝突!

# GOOD: ファイル所有権を分離
Task 1: "APIハンドラーを実装"     → src/handler.ts
Task 2: "バリデーションを実装"   → src/validator.ts
Task 3: "エラー型を定義"         → src/errors.ts

# BAD: 暗黙の前提に依存
"先ほどの設計に基づいて、APIを実装してください"
→ チームメイトは「先ほどの設計」を知らない

# GOOD: 必要な情報をすべて含める
"以下の仕様に基づいてAPIを実装してください：
- エンドポイント: GET /api/users/:id
- レスポンス型: { id: string, name: string, email: string }
- 認証: Bearer Token必須
- 実装先: src/handlers/user.ts
- 参照ファイル: src/types/user.ts（型定義あり）"

# 企業リサーチの例: Haiku ワーカー × N + Sonnet 集約

Phase 1: リーダー（Opus）が戦略を立案
Phase 2: 調査チームメイト × 10（Haiku）が各社を並列調査
Phase 3: 集約チームメイト × 1（Sonnet）がCSVにまとめる

# コスト: Haiku 10体 ≈ Sonnet 1体分
# 速度: 10社を並列調査 → 逐次の 1/10 の時間

# タスク依存関係の設計

[Task 1] OpenAPI スキーマ設計        ← 最初に完了すべき
    ↓ blocks
[Task 2] フロントエンド実装            ← Task 1 に依存
[Task 3] バックエンド実装              ← Task 1 に依存
    ↓ blocks (Task 2 + Task 3)
[Task 4] 結合テスト                    ← Task 2, 3 両方に依存

# TaskUpdate で依存関係を設定
TaskUpdate: { taskId: "2", addBlockedBy: ["1"] }
TaskUpdate: { taskId: "3", addBlockedBy: ["1"] }
TaskUpdate: { taskId: "4", addBlockedBy: ["2", "3"] }

# 悪い例: 全部終わってからレビュー
Phase 1: 計画      → Phase 2: 全部実装 → Phase 3: レビュー
                                                 ↑ ここで問題発覚 → 全部やり直し

# 良い例: フェーズごとにリーダーが確認
Phase 1: 計画 → Leader Review
Phase 2: 設計 → Leader Review
Phase 3: 実装 → Leader Review
Phase 4: テスト
↑ 各フェーズで軌道修正できる

# 正しい終了手順
1. 全タスクの完了を TaskList で確認
2. 各チームメイトに SendMessage (type: "shutdown_request")
3. チームメイトが SendMessage (type: "shutdown_response", approve: true)
4. 全員シャットダウン後に TeamDelete でクリーンアップ

# 忘れると...
- idle 状態のエージェントがバックグラウンドに残る
- チームファイル (~/.claude/teams/) が蓄積
- タスクファイル (~/.claude/tasks/) が蓄積

# Phase 1: リーダーが計画（Opus）
├── リサーチ戦略を策定 → 01_strategy.md
├── 調査対象企業リストを作成 → 02_company_list.md
└── ユーザーに確認を求める

# Phase 2: Haiku チームメイト × N が並列調査
├── Teammate A → 03_companies/company-a.md
├── Teammate B → 03_companies/company-b.md
├── Teammate C → 03_companies/company-c.md
└── ... 各自が1社を担当（ファイル競合なし）

# Phase 3: Sonnet チームメイトが集約
└── 全 .md を読み込み → 04_summary.csv + 04_summary_notes.md

# Phase 4: リーダーがレビュー＆クリーンアップ
├── 成果物の品質確認
├── チームメイトをシャットダウン
└── TeamDelete

# Q1: タスクを「同じ形の小タスク」に分解できるか？

タスクの構造は？
│
├── 同じ作業の繰り返し（N社調査、N件変換、Nページ要約…）
│   │
│   └── 各小タスクの結果を 突き合わせる 必要がある？
│        │
│        ├── No  → Subagent
│        │         例: 10社の企業調査 → 各社独立に調べてCSVに集約
│        │
│        └── Yes → Agent Team（Swarm + 集約フェーズ）
│                  例: 5つの仮説を並列検証 → 最善案をリーダーが選択
│
├── 異なる専門性が必要な工程の連鎖（設計→実装→テスト…）
│   │
│   └── 一部の工程を 同時に進められる か？
│        │
│        ├── No  → 単一セッション
│        │         例: 1ファイルの修正 → 逐次で十分
│        │
│        └── Yes → Agent Team（Pipeline）
│                  例: FE設計 ∥ API調査 → 結合 → テスト
│
└── 1つの集中した作業（バグ修正1件、設定変更…）
    │
    └── 単一セッション
          Agent Teamのオーバーヘッドがタスク本体より大きくなる

# Agent Team の起動コスト内訳

1. TeamCreate         ← チーム設定ファイル生成
2. TaskCreate × N     ← タスクリスト作成・依存関係設定
3. Task（起動）× N    ← チームメイトの起動・コンテキスト読込
4. SendMessage × M    ← 進捗報告・完了通知のやりとり
5. shutdown × N       ← 全員のシャットダウン
6. TeamDelete         ← クリーンアップ

# 例: 「1関数追加」を Agent Team でやると…

単一セッション:
  実作業 5分
  合計   5分

Agent Team（3人）:
  起動コスト  3分  (TeamCreate + TaskCreate + メイト起動)
  コンテキスト共有  2分  (各メイトが既存コードをRead)
  実作業  5分  (並列化しても1人で足りるので短縮なし)
  通信・集約  2分  (SendMessage + リーダー確認)
  終了処理  2分  (shutdown × 3 + TeamDelete)
  合計   14分  ← 2.8倍遅い

# トークン消費の比較（同じタスクを完了する場合）

単一セッション:
  入力: ユーザー指示 + ファイル読込
  出力: 実装コード
  合計: 〜1x

Agent Team（3人チーム）:
  リーダー入力:   ユーザー指示 + ファイル読込 + 設計判断      0.5x
  メイトA入力:    タスク指示 + ファイル読込 + 実装            0.8x
  メイトB入力:    タスク指示 + ファイル読込 + 実装            0.8x
  メイトC入力:    タスク指示 + ファイル読込 + 実装            0.8x
  リーダー集約:   全メイトの報告受信 + レビュー               0.5x
  通信オーバーヘッド: SendMessage × 6〜10往復                0.5x
  合計: 〜4x

# 30分タスクの並列化 → 時間は変わらず、コストだけ4倍
# 3時間タスクの並列化 → 時間が1/3に短縮、コスト4倍でも価値あり

         Leader（オーケストレーター）
        ┌────┼────┐
        ↓    ↓    ↓
      Worker Worker Worker
     (企業A) (企業B) (企業C)
        ↓    ↓    ↓
        └────┼────┘
         集約・CSV出力

# 適: 企業調査、ファイル変換、大量コードレビュー
# 不適: タスク間に依存関係がある場合

# Figma → 実装パイプラインの実例

Phase 1 (Sequential):  Figma分析 → ボックスモデル → レスポンシブ → レビュー
Phase 2 (Parallel):    Frontend設計 ∥ API調査
Phase 3 (Parallel):    FEレビュー ∥ (Backend設計 → DB設計)
Phase 4 (Converge):    全体整合性レビュー

# 適: 段階が明確で各段階に異なる専門性が必要
# 不適: 全工程が密結合な場合

         同じバグ
        ┌────┼────┐
        ↓    ↓    ↓
     仮説A  仮説B  仮説C
    "状態管理" "API応答" "型の不整合"
        ↓    ↓    ↓
        └────┼────┘
     Leader が最も説得力のある解を採用

# なぜ有効か:
# 逐次調査だとアンカリングバイアスが発生する。
# 最初の仮説に引きずられて後続の調査が偏る。
# 並列で独立検証すると、生き残った仮説の信頼性が高い。

Worker（実行） → Watcher（監視） → 問題検出 → ロールバック

# 例: DBマイグレーション
Worker: マイグレーション実行
Watcher: SELECT COUNT(*) で行数監視 + エラーログ監視
         異常検知 → Worker に SendMessage で停止指示

# 適: 本番変更、破壊的操作、金融系処理

# やってしまったこと（Agent Teamの意味なし）
Task 1 → Task 2 → Task 3 → Task 4 → Task 5
# 所要時間: 単一セッションと同じ + チーム管理のオーバーヘッド

# 本来のあるべき姿
Task 1 ──→ Task 3 ──→ Task 5
Task 2 ──→ Task 4 ──↗
# 所要時間: 約半分

# 問い: 「このタスクは本当に前のタスクの出力が必要か？」
# 答えがNoなら並列化できる

# コスト最適化されたチーム構成の例

Leader:     Opus   ← 全体統括・品質判定
Researcher: Haiku  ← Web調査（5-10体並列OK）
Implementer: Sonnet ← コード実装
Reviewer:   Sonnet ← コードレビュー

# Haiku 10体のコスト ≈ Sonnet 1体分
# 10社並列調査が Sonnet 1回分のコストで完了

# チーム構成: 29 エージェント
Leader:  Opus  ← 設計方針・タスク分割・統合レビュー

# 5タスクのPipeline + Swarm
Task 1: "現在のバックグラウンド再生実装を監査し問題点を特定"   ✓
Task 2: "バックグラウンド音声再生の安定化と修正"               ✓
Task 3: "バックグラウンド連続再生（プレイリスト自動進行）を実装" ✓
Task 4: "MiniPlayer UIを実装"                                 ✓
Task 5: "iOS実機でバックグラウンド再生・連続再生をテスト"       ✓

# 技術スコープ
├── TrackPlayer ネイティブモジュール統合
├── バックグラウンドオーディオ・ライフサイクル管理
├── キュー管理（プレイリスト自動進行）
├── iOS Control Center / Now Playing 対応
├── MiniPlayer UIコンポーネント
└── Appium E2Eテスト

# チーム構成: 26 エージェント
Leader:  Opus  ← 調査戦略・仮説管理

# 10タスク（Competing Hypotheses パターン）
Task 1:  "TrackPlayer バックグラウンドオーディオ遷移フロー調査"
Task 2:  "iOS Now Playing 要件と TrackPlayer ネイティブ動作調査"
Task 3:  "track-url-resolver とオーディオURL処理調査"
Task 4:  "バックグラウンド再生の次トラック処理コード調査"
Task 5:  "TrackPlayer キューとイベントシステム調査"
Task 6:  "Appium でバックグラウンド次トラックテスト"
Task 7:  "バックグラウンド次トラック自動再生の修正実装"       ← 実装
Task 8:  "now-playing-video コンテンツIDの発生源調査"
Task 9:  "フォアグラウンド復帰時のナビゲーションフロー調査"
Task 10: "now-playing-video コンテンツIDバグ修正"            ← 実装

# 実装タスクの典型的なチーム構成

Leader（Opus）
├── Phase 1: 並列調査
│   ├── auth-investigator   ← 認証フロー専門
│   ├── nav-investigator    ← ナビゲーション状態専門
│   ├── track-investigator  ← TrackPlayerネイティブ専門
│   ├── queue-investigator  ← キュー管理専門
│   └── url-investigator    ← URL解決専門
│
├── Phase 2: 仮説統合（Leader自身が判断）
│
├── Phase 3: 修正実装
│   └── mobile-fixer        ← 修正を実装
│
└── Phase 4: 検証
    └── e2e-tester          ← Appium でテスト実行

# ポイント:
# 1. 調査エージェントは「観点」で分ける（ファイルではない）
# 2. 仮説統合はLeaderが行う（最も判断力が高いモデル）
# 3. 修正実装は最小限のエージェントで（ファイル競合回避）

# チーム構成
Leader:  Opus   ← 全体統括・修正方針決定

# 4タスクのPipeline
Task 1: "Mobile MCPでアプリの現状確認・エラー特定"         ✓ completed
Task 2: "mobileパッケージのコード構造・エラー調査"         ✓ completed
Task 3: "frontendの実装パターンを参考にmobileのAPI修正"  ✓ completed
Task 4: "Mobile MCPで修正後の動作検証"                   ⧖ in_progress

# ポイント: Task 1 と Task 4 でMobile MCPスクリーンショットを使い
# 「目で見て確認」する Watchdog 的な検証を組み込んだ

# チーム構成（全員 Opus + typescript-pro）
Leader:           Opus  ← 設計・タスク分割・統合レビュー
freee-connector: Opus  ← OAuth2認証・APIクライアント・データ取得
tax-engine:      Opus  ← 所得税計算・消費税計算・税制定数

# 成果物: 14ファイル / 2,730行
src/freee/
  ├── types.ts      (157行) Zodスキーマ
  ├── auth.ts       (103行) OAuth2フロー
  ├── client.ts     (203行) APIエンドポイント
  └── data-fetcher.ts (57行) 一括データ取得

src/tax/
  ├── types.ts      (206行) 税額計算の入出力型
  ├── constants.ts  (480行) 令和7年分税制定数
  └── calc.ts       (1,350行) 所得税・消費税計算

# 提案資料生成のAgent Team構成
Leader（Opus）: ソースMD分析 → 最終レビュー
   ↓
slide-planner（Sonnet）: スライド構成 + 発表者ノート設計
   ∥  ← 並列
visual-designer（Sonnet）: HTML→PNG ビジュアルアセット生成
   ↓  ← 両方完了後
deck-assembler（Sonnet）: gogcli でGoogle Slidesデッキ組立

# 成果物フォルダ（1デッキあたり約20ファイル）
proposal-slides/YYYY-MM-DD-{slug}/
├── 01_structure.json       # スライド構成仕様
├── 02_slide_plan.md        # テキストコンテンツ
├── 02_speaker_notes/       # 発表者ノート
├── 03_assets/html/         # 自己完結HTML（1920x1080）
├── 03_assets/png/          # Playwrightスクリーンショット
├── 04_deck_info.json       # デッキID・URL
└── output.pptx / .pdf      # エクスポート

# ビジネスモデル分析のAgent構成
Leader（Opus/Sonnet）: 企業URL受け取り → 最終レビュー
   ↓
web-researcher（Haiku）: WebSearchで企業サイト・IR・記事を収集
   ↓
model-analyst（Sonnet）: 収集データから9マス図解 + Mermaid生成

# 分析対象の例
├── 競合サービス分析
├── 提案先企業のビジネス構造把握
└── 自社サービスのポジショニング整理

# 成果物
bizgram-outputs/YYYY-MM-DD-{company}.md
├── 9マス図解（テキスト + Mermaid）
├── モノ・カネ・情報の流れ
├── 収益モデルの特徴
└── 差別化要因の分析

# 21ジャンルのクリエイター市場調査
Leader（Opus）: ジャンル選定 → チームメイト割り当て → CSV統合

# 各チームメイトが1ジャンルを担当（Swarm型）
genre-01（Haiku）: ヨガ・ピラティス     → 01_ヨガピラティス.csv
genre-02（Haiku）: パーソナルトレーニング → 02_パーソナルトレーニング.csv
genre-03（Haiku）: ダンス・バレエ         → 03_ダンスバレエ.csv
  ...
genre-21（Haiku）: ライフスタイル・その他 → 21_ライフスタイルその他.csv

# 各CSVに含まれるカラム
名前, プラットフォームURL, Instagram, フォロワー数,
提供サービス, 価格帯, ターゲット層, 差別化ポイント

# 事業リサーチの実績

"海外インディーハッカー調査"
├── Reddit / Indie Hackers / Hacker News から収益データ収集
├── 成功パターンの分類（SaaS / API / マーケットプレイス）
└── 出力: indie-hacker-global-business-research-2026.md

"ソロ開発者グローバルSaaS戦略"
├── 市場規模・参入障壁・収益モデルの調査
├── 実証済みビジネスモデルパターンの整理
└── 出力: solo-developer-global-saas-strategy-guide.md

"キャリア開発計画"
├── 自分の現在地と目標のギャップ分析
├── 6ヶ月のマイルストーン設計
└── 出力: executive-development-2026.md

# 社内勉強会資料の構成

"Claude製品の使い分けガイド（ビジネスサイド向け）"
├── 3つの製品の全体像（Chat / Code / API）
├── 各製品の使い分けフローチャート
├── 具体的な業務別ユースケース
├── 料金プラン比較表
└── 導入ステップ（非エンジニア向け手順書）

# プロンプトの工夫
→ 「エンジニア用語を使わず、業務の言葉で書く」を指示
→ 「各セクションに "こんな場面で使える" を1つ以上入れる」
→ 「スクリーンショットの代わりに操作手順を箇条書きで」

# Agent Team 月次実績

チーム起動回数:          11
総エージェント起動数:    〜150
最大チームサイズ:        32 エージェント（fix-mobile-auth-refresh）

# 実装成果物
モバイルアプリ実装:      2チーム（音声再生・Control Center対応）
実装タスク:              15タスク（bg-audio 5 + control-center 10）
生成コード（ツール）:    3,538行（TypeScript / freee-shinkoku）
生成スライド:            91枚（5デッキ）
バグ修正タスク:          17タスク（認証・再生・ナビゲーション）

# 非エンジニアリング成果物
企業分析レポート:        9件（ビジネスモデル図解）
クリエイター市場調査:    21ジャンル（各20〜50プロフィール / CSV出力）
事業リサーチレポート:    3件（海外市場・SaaS戦略・キャリア計画）
社内勉強会資料:          1件（ビジネスサイド向けClaude製品ガイド）

# 完了率
チーム完走率:            100%（途中クラッシュゼロ）
bg-audio タスク完了:     100%（5/5）
control-center タスク:   進行中（10タスク）

# 品質指標
ファイル競合:            0件（1エージェント1ファイル原則を遵守）
型エラー:               0件（Zodスキーマ + strict TypeScript）
E2Eテスト:              Appium自動化（モバイル実装チーム）
手戻り:                 1件（gogcli ノートAPI制約）

# BAD: 全部直列（Agent Teamの意味なし）
Task 1 → Task 2 → Task 3 → Task 4 → Task 5

# GOOD: 可能な限り並列
Task 1 ──→ Task 3 ──→ Task 5
Task 2 ──→ Task 4 ──↗

# チームメイト起動時にプロンプトに仕様を埋め込む
Task(
  team_name = "freee-shinkoku",
  name      = "freee-connector",
  prompt    = """
あなたは freee-connector 担当です。

## 実装するファイル
### src/freee/auth.ts - OAuth2認証
- getAuthorizationUrl(clientId, redirectUri): 認証URL生成
- exchangeCode(clientId, clientSecret, code, redirectUri): トークン取得
- refreshToken(clientId, clientSecret, refreshToken): リフレッシュ
- OAuth2エンドポイント: https://accounts.secure.freee.co.jp/...

### src/freee/client.ts - APIクライアント
- getCompanies(): GET /api/1/companies
- getDeals(companyId, params): GET /api/1/deals
- レート制限対応: 429 → 指数バックオフ

## 注意事項
- 金額は全てint（円単位）。float禁止
- any型禁止（unknownを使用）
"""
)

# Phase 1: リーダーが設計書を書き出す
Write("design/01_api_spec.md", api_design_content)
Write("design/02_db_schema.md", db_schema_content)

# Phase 2: チームメイトに「先にファイルを読め」と指示
Task(
  name   = "backend-engineer",
  prompt = """
まず以下のファイルを Read で読んでから実装を開始してください:
1. design/01_api_spec.md（API仕様）
2. design/02_db_schema.md（DBスキーマ）

実装先: src/handlers/
"""
)

# 別のチームメイトも同じファイルを参照できる
Task(
  name   = "frontend-engineer",
  prompt = """
まず design/01_api_spec.md を Read で読み、
API仕様に合わせたフロントエンド実装を行ってください。
"""
)

# プロジェクトの CLAUDE.md に書いておくと全員が従う

## コーディング規約
- TypeScript strict モード
- any 型禁止（unknown を使用）
- 金額は int（円単位）、float 禁止

## アーキテクチャ
- API: Hono + Zod バリデーション
- DB: Prisma ORM
- テスト: Vitest

## ファイル構成
src/
├── handlers/    # APIハンドラー
├── services/    # ビジネスロジック
├── types/       # 型定義
└── utils/       # ユーティリティ

# → チームメイト全員がこの構成に従って実装する

# タスクの description にコンテキストを含める
TaskCreate(
  subject     = "OAuth2認証モジュール実装",
  description = """
freee OAuth2フローを実装する。
- 認証URL: https://accounts.secure.freee.co.jp/public_api/authorize
- トークンURL: https://accounts.secure.freee.co.jp/public_api/token
- スコープ: read write
- トークン保存先: .freee-tokens.json

[依存] Task #1 の型定義（src/freee/types.ts）が必要。
先に TaskGet(#1) で型定義の詳細を確認すること。
"""
)

# 別のチームメイトが TaskGet で内容を確認できる
# → 自分のタスクとの整合性を自発的にチェック可能

# 作業中に発見した問題を関係者に即座に共有
SendMessage(
  type      = "message",
  recipient = "frontend-engineer",
  content   = """
APIレスポンスの型が変わりました。
変更前: { users: User[] }
変更後: { data: User[], meta: { total: number } }

src/types/api.ts を更新済みなので Read で確認してください。
"""
)

# 注意: broadcast は全員に送信されるため、
# 「全員停止」「根本方針変更」以外では使わない

# チームメイトはチーム設定を読んでメンバー構成を把握できる
Read("~/.claude/teams/freee-shinkoku/config.json")

# → members 配列から以下がわかる:
#   - "freee-connector": freee API連携担当（型定義は彼に聞く）
#   - "tax-engine": 税額計算ロジック担当
#   - "team-lead": オーケストレーター

# これにより、チームメイト同士が
# 「型定義について freee-connector に SendMessage する」
# といった自発的な連携が可能になる

# コンテキスト共有の使い分け

起動前に確定している情報？
├── Yes → 方法1: プロンプト埋め込み（最も確実）
│         └── 例: API仕様、型定義、実装ルール
└── No → 情報は全チームメイト共通？
          ├── Yes → 方法3: CLAUDE.md（自動読み込み）
          │         └── 例: コーディング規約、アーキテクチャ方針
          └── No → 情報はファイルとして残すべき？
                    ├── Yes → 方法2: 中間ファイル（最も汎用）
                    │         └── 例: 設計書、スキーマ、中間成果物
                    └── No → 方法5: SendMessage（即時通知）
                              └── 例: 方針変更、発見した問題

# 望むアーキテクチャ（マイクロサービス的な分離）
src/
├── auth/          # 認証ドメイン
├── payment/       # 決済ドメイン
├── notification/  # 通知ドメイン
└── shared/types/  # 共有型定義

# → エージェント構成をアーキテクチャに合わせる
Agent "auth-engineer"         → src/auth/ のみ担当
Agent "payment-engineer"      → src/payment/ のみ担当
Agent "notification-engineer" → src/notification/ のみ担当
Agent "type-architect"        → src/shared/types/ を先に確定

# 各エージェントがドメイン境界を越えないため、
# 自然とクリーンなモジュール分離が維持される

{
  "agents": {
    "api-designer":    { "type": "complicated-subsystem", "domain": "API設計" },
    "frontend":        { "type": "stream-aligned",       "domain": "UI実装" },
    "backend":         { "type": "stream-aligned",       "domain": "サーバー実装" },
    "reviewer":        { "type": "enabling",            "domain": "品質保証" }
  },
  "interactions": [
    {
      "from": "api-designer",
      "to": ["frontend", "backend"],
      "mode": "x-as-a-service",
      "contract": "design/openapi-spec.yaml",
      // ↑ api-designerはこのファイルを「成果物」として出力し、
      //   frontendとbackendはこれを「入力仕様」として消費する
    },
    {
      "from": "frontend",
      "to": "backend",
      "mode": "collaboration",
      "shared_files": ["src/types/"],
      // ↑ 型定義を双方が参照・更新する（ファイルの共同所有）
    },
    {
      "from": "reviewer",
      "to": ["frontend", "backend"],
      "mode": "facilitating",
      // ↑ reviewerは実装を検証し改善提案するが、自らは書き換えない
    }
  ]
}

# X-as-a-Service モード: 一方通行の仕様提供
Phase 1: api-designer → design/openapi-spec.yaml を出力
Phase 2: frontend, backend が spec.yaml を Read して並列実装
         # frontendはapi-designerに直接質問しない（契約で定義済み）

# Collaboration モード: 双方向の共同作業
Phase 2: frontend ⟷ backend が src/types/ を共同編集
         # 型変更時は SendMessage で相互通知

# Facilitating モード: 検証と改善提案
Phase 3: reviewer が frontend, backend の成果物をレビュー
         # 直接修正はしない。改善点をメッセージで指摘する

{
  "tasks": {
    "api-design": {
      "R": "api-designer",
      "A": "team-lead",
      "C": ["frontend", "backend"],
      "I": ["reviewer"]
    },
    "frontend-impl": {
      "R": "frontend",
      "A": "team-lead",
      "C": ["api-designer"],
      "I": ["backend"]
    }
  }
}

# api-designer がタスク完了すると、Auto-Router が:
# 1. team-lead（A）に全文レポートを送信 → 承認要求
# 2. frontend, backend（C）に設計概要 + 「意見ありますか？」を送信
# 3. reviewer（I）に「API設計完了」の1行通知のみ送信

// PostToolUse フックで TaskUpdate(status: "completed") を検知
function onTaskCompleted(taskId: string, output: string) {
  const raci = readRaciConfig(teamName);
  const task = raci.tasks[taskId];

  // Accountable: 全文 + 承認要求
  sendMessage(task.A, {
    content: `タスク完了: ${output}\n\n承認をお願いします。`,
    summary: `${taskId} 完了 - 承認要求`
  });

  // Consulted: 要約 + 意見求む
  for (const agent of task.C) {
    sendMessage(agent, {
      content: `${taskId} が完了しました。\n概要: ${summarize(output)}\n影響がありそうな点があればお知らせください。`,
      summary: `${taskId} 完了 - レビュー依頼`
    });
  }

  // Informed: 1行通知のみ
  for (const agent of task.I) {
    sendMessage(agent, {
      content: `[通知] ${taskId} が完了しました。`,
      summary: `${taskId} 完了通知`
    });
  }
}

# 知識の永続化ディレクトリ
~/.claude/memory/team-learnings/
├── retros/                          # 自動生成レトロスペクティブ
│   ├── 2026-02-15-freee-shinkoku.md
│   ├── 2026-02-20-proposal-slides.md
│   └── 2026-02-25-bg-audio-playback.md
├── patterns/                        # 成功パターン集
│   ├── effective-prompts.md         # よく効いたプロンプト設計
│   ├── cost-optimization.md         # コスト最適化の知見
│   └── parallel-patterns.md         # 並列化パターン
└── anti-patterns/                   # 失敗パターン集
    ├── context-sharing-failures.md
    └── over-parallelization.md

# .claude/settings.json に追加するフック
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "TeamDelete",
        "script": "~/.claude/hooks/generate-retro.sh"
      }
    ]
  }
}

# generate-retro.sh の動作:
# 1. チームのタスクリストを読み込み
# 2. 完了タスクの description, blockedBy, 所要時間を集計
# 3. レトロスペクティブを自動生成:
#    - チーム構成（メンバー数、モデル配分）
#    - タスク完了率、並列化率
#    - ボトルネックになったタスク
#    - 使えたパターン / 改善すべき点
# 4. ~/.claude/memory/team-learnings/retros/ に保存

# Retrospective: freee-shinkoku (2026-02-15)

## チーム構成
- リーダー: Opus（オーケストレーション）
- freee-connector: Opus（API連携実装）
- tax-engine: Opus（税額計算エンジン）

## 成果
- 14ファイル / 3,538行のTypeScriptコード
- 全タスク完了率: 100%

## 学び
- [有効] 起動プロンプトに80行の詳細仕様を埋め込み → 追加指示ゼロ
- [有効] 金額int/float禁止ルールをプロンプトに明記 → 端数処理バグなし
- [改善] 3名全員Opusは過剰。freee-connectorはSonnetで十分だった
- [改善] freee APIのレート制限429をプロンプトで言及したが、
         実際のテストは不足

## 次回への推奨
- API連携系エージェントはSonnetで起動すること
- テストタスクを独立した4番目のエージェントに分離すること

# 新チーム起動時のリーダープロンプト
"""
## 過去の学び（自動注入）
~/.claude/memory/team-learnings/retros/ を Read して、
同種プロジェクトの学びを活かしてください。

特に以下を確認:
- 同じドメインの過去レトロ
- anti-patterns/ の回避すべきパターン
- patterns/ の有効なプロンプト設計
"""

# チームメイトが品質問題を発見した場合の手順

# 1. Andon ファイルを作成（全エージェントが監視）
Write(".claude/andon/{team-name}.json", {
  "triggered_by": "backend-engineer",
  "severity": "critical",
  "reason": "DB スキーマの外部キー制約が全エンドポイントに影響",
  "timestamp": "2026-02-28T14:30:00Z"
})

# 2. PreToolUse フックが全エージェントの Write/Edit を一時停止
#    → "Andon が発動中です。.claude/andon/ を確認してください"

# 3. リーダーが問題を確認し、解決策を決定

# 4. Andon ファイルを削除 → 全エージェントの作業再開
Bash("rm .claude/andon/{team-name}.json")

# PreToolUse フック例:
# if [ -f ".claude/andon/${TEAM_NAME}.json" ]; then
#   echo "BLOCK: Andon発動中。作業を一時停止してください。"
#   exit 1
# fi

# 組織論をAgent Teamに適用するロードマップ

Phase 1: 今すぐできること
├── Inverse Conway Maneuver
│   └── ディレクトリ構造 = エージェント境界
└── CLAUDE.md による組織文化の共有
    └── コーディング規約・アーキテクチャ方針

Phase 2: プロンプト設計で実現
├── Team Topologies の連携モード
│   └── .claude/team-topologies/*.json をリーダーが参照
├── RACI Matrix
│   └── .claude/raci/*.json に基づきリーダーが手動ルーティング
└── Andon の簡易版
    └── "問題発見時は broadcast + 全員作業停止" をプロンプトに明記

Phase 3: フック / スクリプトで自動化
├── RACI Auto-Router
│   └── PostToolUse フックで TaskUpdate を検知 → 自動送信
├── Andon Signal
│   └── PreToolUse フックでファイル存在チェック → 強制停止
└── Organizational Memory
    └── TeamDelete 前にレトロ自動生成 → memory/ に永続化

# 推奨: Phase 1 → 2 を今日から実践し、
# Phase 3 は繰り返し使うチーム構成が固まってから投資する