agent-teams

エージェントチームスキル

目的： Maggy で初期化されたすべてのプロジェクトは、連携する AI エージェントチームとして動作します。これはデフォルトのワークフローであり、任意ではありません。チームでは、どのステップも省略できない厳格な TDD パイプラインを適用します。

セットアップ： エージェント定義は、適切なフロントマター（name、description、model、tools、disallowedTools、maxTurns、effort）とともに .claude/agents/ に配置します。形式についてはエージェントファイルを参照してください。

---

中核となる原則

すべての機能は、タスクの依存関係によって適用される変更不可のパイプラインに従います。

┌─────────────────────────────────────────────────────────────────┐
│  STRICT FEATURE PIPELINE (IMMUTABLE)                            │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  1. SPEC        Write feature specification                      │
│       ↓         (Feature Agent)                                  │
│  2. REVIEW      Quality Agent reviews spec completeness          │
│       ↓         (Quality Agent)                                  │
│  3. TESTS       Write failing tests for all acceptance criteria  │
│       ↓         (Feature Agent)                                  │
│  4. RED VERIFY  Quality Agent confirms ALL tests FAIL            │
│       ↓         (Quality Agent)                                  │
│  5. IMPLEMENT   Write minimum code to pass tests                 │
│       ↓         (Feature Agent)                                  │
│  6. GREEN VERIFY Quality Agent confirms ALL tests PASS + coverage│
│       ↓         (Quality Agent)                                  │
│  7. VALIDATE    Lint + type check + full test suite              │
│       ↓         (Feature Agent)                                  │
│  8. CODE REVIEW Multi-engine review, block on Critical/High      │
│       ↓         (Code Review Agent)                              │
│  9. SECURITY    OWASP scan, secrets detection, dependency audit  │
│       ↓         (Security Agent)                                 │
│  10. BRANCH+PR  Create feature branch, stage files, create PR    │
│                 (Merger Agent)                                    │
│                                                                  │
│  No step can be skipped. Task dependencies enforce ordering.     │
│  Quality Agent verifies RED/GREEN transitions.                   │
│  Code Review + Security Agents gate the merge path.              │
│  Merger Agent handles branching and PR creation.                 │
└─────────────────────────────────────────────────────────────────┘

---

デフォルトのエージェント構成

すべてのプロジェクトでは、5 つの常駐エージェントと N 個の機能エージェントが起動します。

┌─────────────────────────────────────────────────────────────────┐
│  DEFAULT TEAM ROSTER                                             │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  PERMANENT AGENTS (always present)                               │
│  ─────────────────────────────────                               │
│  Team Lead        Orchestration, task breakdown, assignment      │
│                   Uses delegate mode - NEVER writes code         │
│                                                                  │
│  Quality Agent    TDD verification (RED/GREEN phases)            │
│                   Coverage gates (>= 80%)                        │
│                   Spec completeness review                       │
│                                                                  │
│  Security Agent   OWASP scanning, secrets detection              │
│                   Dependency audit, .env validation               │
│                   Blocks on Critical/High                        │
│                                                                  │
│  Code Review Agent  Multi-engine code review                     │
│                     Claude / Codex / Gemini / All                │
│                     Blocks on Critical/High                      │
│                                                                  │
│  Merger Agent     Creates feature branches                       │
│                   Stages feature-specific files only              │
│                   Creates PRs via gh CLI                          │
│                   NEVER merges - only creates PRs                │
│                                                                  │
│  DYNAMIC AGENTS (one per feature)                                │
│  ────────────────────────────────                                │
│  Feature Agent    Implements one feature end-to-end              │
│  (x N features)   Follows strict pipeline above                  │
│                   Uses Ralph loops for implementation             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

エージェント	役割	Plan モード	コードの編集
team-lead	オーケストレーション、タスクの分割、割り当て	いいえ（委任モード）	いいえ
quality-agent	TDD の検証、カバレッジのゲート	はい	いいえ（読み取り専用）
security-agent	OWASP スキャン、シークレットの検出	はい	いいえ（読み取り専用）
review-agent	複数エンジンによるコードレビュー	はい	いいえ（読み取り専用）
merger-agent	ブランチの作成、PR の管理	いいえ	いいえ（git のみ）
feature-{name}	機能の実装（機能ごとに 1 つ）	いいえ	はい

---

チームリードの責務

チームリードはオーケストレーターです。コードは決して書きません。

1. _project_specs/features/*.md を読み、すべての機能を特定する
2. 各機能を 10 タスクからなる依存関係チェーンに分割する（下記参照）
3. 機能ごとに機能エージェントを 1 つ起動する
4. 最初のタスク（仕様書の作成）を機能エージェントに割り当てる
5. TaskList を継続的に監視し、進捗とブロッカーを確認する
6. ブロックされたタスクに対処し、再割り当てを行う
7. 機能間の依存関係を調整する
8. すべての PR が作成されたら、すべてのエージェントに shutdown_request を送信する
9. 完了したらチームをクリーンアップする

委任モードは必須です。 チームリードが使用するのは、以下のみです。

• TeamCreate、TaskCreate、TaskUpdate、TaskList、TaskGet
• SendMessage（message、broadcast、shutdown_request）
• Read、Glob、Grep（監視用）

---

機能エージェントのワークフロー（必須）

各機能エージェントは、必ず次の順序どおりに進めてください。タスクの依存関係によって順序が強制されるため、ステップ N が完了して検証されるまでは、機能エージェントはステップ N+1 を開始できません。

ステップ 1：仕様書を作成する

• _project_specs/features/{feature-name}.md を作成する
• 説明、受け入れ基準、テストケースの表、依存関係を含める
• base.md スキルのアトミックな TODO 形式に従う
• タスクを完了としてマークする -> Quality Agent がレビュー

ステップ 2：テストを書く（RED フェーズ）

• 仕様書のテストケース表に基づいてテストファイルを書く
• テストではすべての受け入れ基準を必ず網羅する
• まだ存在しないモジュールをインポートする（テストは失敗します）
• タスクを完了としてマークする -> Quality Agent がテストの存在と失敗を検証

ステップ 3：RED の検証を待つ

• Quality Agent がテストを実行し、新しいテストがすべて失敗することを検証する
• 実装がないのに合格するテストがあれば、テストを書き直す
• Quality Agent が検証完了としてマークする -> 実装が可能になる

ステップ 4：実装する（GREEN フェーズ）

• すべてのテストに合格するために必要な最小限のコードを書く
• base.md のシンプルさに関するルールに従う（関数あたり 20 行、ファイルあたり 200 行、引数 3 個）
• 反復的な実装には Ralph ループ（/ralph-loop）を使用する
• 実装後にテストを実行する - すべて合格する必要がある
• タスクを完了としてマークする -> Quality Agent がテストの合格を検証

ステップ 5：GREEN の検証を待つ

• Quality Agent がテストスイート全体を実行し、カバレッジを確認する
• カバレッジは 80% 以上である必要がある
• テストに失敗する場合、またはカバレッジが不十分な場合は、修正して再度リクエストする
• Quality Agent が検証完了としてマークする -> 検証工程が可能になる

ステップ 6：検証する

• リンターを実行する（ESLint / Ruff）
• 型チェッカーを実行する（TypeScript / mypy）
• カバレッジ付きでテストスイート全体を実行する
• 問題があれば修正する
• タスクを完了としてマークする -> コードレビューが可能になる

ステップ 7：コードレビューを待つ

• Code Review Agent が変更したファイルに対して /code-review を実行する
• Critical または High の問題があれば、修正してレビューを再度リクエストする
• Code Review Agent が完了としてマークする -> セキュリティスキャンが可能になる

ステップ 8: セキュリティスキャンを待つ

• セキュリティエージェントがセキュリティチェックを実行します
• Critical または High の問題がある場合 -> 修正してスキャンを再リクエストします
• セキュリティエージェントが完了とマーク -> マージのロックが解除されます

ステップ 9: ブランチ + PR を待つ

• マージャーエージェントがフィーチャーブランチを作成し、ファイルをステージングし、PR を作成します
• PR が作成された時点でフィーチャーは完了です

---

タスク依存関係チェーンモデル

各フィーチャー「X」について、チームリードは厳密な順序で次の 10 個のタスクを作成します:

┌────────────────────────────────────────────────────────────────┐
│  TASK CHAIN FOR FEATURE "X"                                     │
│                                                                  │
│  Task 1:  X-spec                                                │
│           owner: feature-X                                       │
│           blockedBy: (none)                                      │
│           ↓                                                      │
│  Task 2:  X-spec-review                                         │
│           owner: quality-agent                                   │
│           blockedBy: X-spec                                      │
│           ↓                                                      │
│  Task 3:  X-tests                                               │
│           owner: feature-X                                       │
│           blockedBy: X-spec-review                               │
│           ↓                                                      │
│  Task 4:  X-tests-fail-verify                                   │
│           owner: quality-agent                                   │
│           blockedBy: X-tests                                     │
│           ↓                                                      │
│  Task 5:  X-implement                                           │
│           owner: feature-X                                       │
│           blockedBy: X-tests-fail-verify                         │
│           ↓                                                      │
│  Task 6:  X-tests-pass-verify                                   │
│           owner: quality-agent                                   │
│           blockedBy: X-implement                                 │
│           ↓                                                      │
│  Task 7:  X-validate                                            │
│           owner: feature-X                                       │
│           blockedBy: X-tests-pass-verify                         │
│           ↓                                                      │
│  Task 8:  X-code-review                                         │
│           owner: review-agent                                    │
│           blockedBy: X-validate                                  │
│           ↓                                                      │
│  Task 9:  X-security-scan                                       │
│           owner: security-agent                                  │
│           blockedBy: X-code-review                               │
│           ↓                                                      │
│  Task 10: X-branch-pr                                           │
│           owner: merger-agent                                    │
│           blockedBy: X-security-scan                             │
└────────────────────────────────────────────────────────────────┘

フィーチャーの並列実行

複数のフィーチャーがそれぞれのチェーンを並列で実行します。共有エージェントは、タスクのブロックが解除されると処理します:

Feature: auth         Feature: dashboard      Feature: payments
  auth-spec             dash-spec               pay-spec
  auth-spec-review      dash-spec-review        pay-spec-review
  auth-tests            dash-tests              pay-tests
  auth-fail-verify      dash-fail-verify        pay-fail-verify
  auth-implement        dash-implement          pay-implement
  auth-pass-verify      dash-pass-verify        pay-pass-verify
  auth-validate         dash-validate           pay-validate
  auth-code-review      dash-code-review        pay-code-review
  auth-security         dash-security           pay-security
  auth-branch-pr        dash-branch-pr          pay-branch-pr
       |                     |                       |
       v                     v                       v
   [All chains run simultaneously]
   [Quality Agent handles all verify tasks as they unblock]
   [Review Agent handles all review tasks as they unblock]
   [Security Agent handles all scan tasks as they unblock]
   [Merger Agent handles all branch-pr tasks as they unblock]

---

エージェント間通信

ダイレクトメッセージ（対象を絞った作業向け）

Feature Agent -> Quality Agent:  "Tests written for auth, ready for RED verify"
Quality Agent -> Feature Agent:  "All 7 tests fail as expected. Proceed to implement"
Feature Agent -> Review Agent:   "Implementation complete, ready for code review"
Review Agent  -> Feature Agent:  "2 High issues found: [details]. Fix before proceeding"
Security Agent -> Merger Agent:  "Security scan passed for auth feature"
Merger Agent  -> Team Lead:      "PR #42 created for auth feature"

タスクリスト（状態の信頼できる唯一の情報源）

• すべてのエージェントは作業完了後に TaskList を確認します
• 品質エージェントは検証タスクを自動的に引き受けます
• レビューエージェントはコードレビュータスクを自動的に引き受けます
• セキュリティエージェントはセキュリティスキャンタスクを自動的に引き受けます
• マージャーエージェントはブランチ PR タスクを自動的に引き受けます

ブロードキャスト（まれ - ブロッキング問題のみ）

• チームリード -> 全員: 「auth と dashboard の間にブロッキング依存関係が見つかりました」
• セキュリティエージェント -> 全員: 「共有依存関係に Critical 脆弱性があります」

---

フィーチャーエージェントの生成

チームリードはフィーチャーごとに 1 つのフィーチャーエージェントを生成します:

1. _project_specs/features/*.md を読み込みます
2. 各フィーチャー仕様について、フィーチャーエージェントを生成します:
   • name: feature-{feature-name}
   • .claude/agents/feature.md 定義を使用します
   • 生成プロンプトにはフィーチャー名と仕様の場所が含まれます
3. そのフィーチャーの 10 個のタスクからなる完全な依存関係チェーンを作成します
4. 仕様作成タスクをフィーチャーエージェントに割り当てます

例

プロジェクトに 3 つのフィーチャーがある場合: auth、dashboard、payments

• 生成: feature-auth、feature-dashboard、feature-payments
• 合計 30 個のタスク（フィーチャーごとに 10 個）を作成します
• 各フィーチャーエージェントは仕様タスクから開始します
• 3 つすべてが並列で動作します

---

ブランチと PR の戦略

フィーチャーごとに 1 ブランチ。フィーチャーごとに 1 PR。

Branch naming:  feature/{feature-name}
PR title:       feat({feature-name}): {short description}
PR body:        Generated from spec + test results + review + security results

マージャーエージェントは次のことを行います:

1. git checkout main && git pull origin main
2. git checkout -b feature/{feature-name}
3. このフィーチャーで変更されたファイルのみをステージングします（決して git add -A は使いません）
4. 検証結果を含む説明的なメッセージでコミットします
5. git push -u origin feature/{feature-name}
6. gh pr create を完全なテンプレートとともに実行します。これには以下が含まれます:
   • フィーチャー仕様からの概要
   • 品質検証によるテスト結果
   • レビューエージェントによるコードレビューの概要
   • セキュリティエージェントによるセキュリティスキャン結果
   • 完了したすべてのパイプラインステップのチェックリスト

---

品質ゲート

ワークフローの強制（タスク依存関係による）

• タスク依存関係により、ステップをスキップすることは構造的に不可能になります
• 品質エージェントが「tests-fail-verify」を完了するまで、フィーチャーエージェントは「implement」を認識できません
• これが主要な強制メカニズムです

エージェント間の検証（信頼するが検証する）

• 品質エージェントは独立してテストを実行します（フィーチャーエージェントの報告を信頼しません）
• セキュリティエージェントは独立してスキャンします（レビューエージェントを信頼しません）
• マージャーエージェントは、ブランチを作成する前にすべての先行タスクが完了していることを検証します

ブロッキングルール

• 品質エージェント: テストが失敗しない（RED）場合、または成功しない（GREEN）場合、またはカバレッジが 80% 未満の場合はブロックします
• コードレビューエージェント: Critical または High の重大度の問題でブロックします
• セキュリティエージェント: Critical または High の重大度の検出結果でブロックします
• マージャーエージェント: いずれかの先行タスクが未完了の場合、ブランチの作成を拒否します

---

既存のスキルとの統合

既存のスキル	エージェントチームでの活用方法
base.md	TDD ワークフロー、アトミックな ToDo、シンプルさに関するルールに、すべてのエージェントが従います
code-review.md	レビューエージェントは、このスキルに従って /code-review を実行します
security.md	セキュリティエージェントは、このスキルの OWASP パターンに従います
session-management.md	各エージェントが独自のセッション状態を維持します
iterative-development.md	機能エージェントは、実装に Stop フックの TDD ループを使用します
project-tooling.md	マージャーエージェントは、ブランチと PR に gh CLI を使用します
team-coordination.md	自動調整には agent-teams を使用するため、このスキルは置き換えられます
icpg.md	チームリードが ReasonNode を作成します。機能エージェントは制約とリスクを照会します。品質エージェントはドリフトを確認します。PreToolUse フックがコンテキストを挿入します。Stop フックがシンボルを自動記録します。
code-graph.md	機能エージェントは、意図のコンテキストを把握するための iCPG と併せて、グラフをシンボル検索に使用します

---

環境設定

必須の設定

// settings.json or environment
{
  "env": {
    "agent teams (via .claude/agents/ definitions)": "1"
  }
}

プロジェクト構造（/initialize-project によって作成）

.claude/
  agents/            # Agent definitions (from agent-teams skill)
    team-lead.md
    quality.md
    security.md
    code-review.md
    merger.md
    feature.md
  skills/
    agent-teams/     # This skill
      SKILL.md
      agents/        # Agent definition templates
    base/
    code-review/
    security/
    ...

---

チームの起動

自動（/initialize-project 経由）

プロジェクトのセットアップが完了すると、フェーズ 6 で機能について確認し、チームを自動的に起動します。

手動（/spawn-team 経由）

既存のプロジェクトの場合は、/spawn-team を実行して、既存の機能仕様からチームを起動します。

---

コンテナー分離（Polyphony）

Docker／OrbStack が利用可能な場合、機能エージェントはデフォルトで Polyphony コンテナー内で実行されます。チームリードと共有エージェント（品質、セキュリティ、レビュー、マージャー）は、読み取りと調整のみを行うため、引き続きネイティブ環境で実行されます。

Polyphony による変更点

項目	Polyphony なし	Polyphony あり
機能エージェント	共有ファイルシステム	専用コンテナーと git ブランチ
ファイルの競合	チームリードが直列化する必要があります	発生しません（クローンが分離されます）
テストの実行	共有され、相互に干渉する可能性があります	コンテナーごとに独立します
ブランチ戦略	マージャーエージェントがブランチを作成します	各コンテナーに専用のブランチがあります

仕組み

1. /spawn-team が Docker と polyphony CLI を検出します
2. 各機能に対して polyphony spawn "$FEATURE" --type feature を実行します
3. Polyphony が専用の git クローンとブランチを持つコンテナーを作成します
4. エージェント CLI がコンテナー内で起動します
5. 完了すると、変更は PR を作成できる専用ブランチに保存されます

フォールバック

Docker が利用できない場合、/spawn-team はネイティブの Agent ツール（共有ファイルシステム）にフォールバックします。次のメッセージが表示されます。

"コンテナー分離なしで実行しています（Docker が見つかりません）。エージェントはワークスペースを共有します。"

---

制限事項

• 実験的機能 - エージェントチームには実験的な環境変数が必要です
• ネストされたチームには非対応 - チームメイトはサブチームを起動できません
• 1 セッションにつき 1 チーム - 新しいチームを開始する前に、現在のチームをクリーンアップしてください
• セッションの再開には非対応 - セッションが終了した場合は、/spawn-team を再実行してください（タスクは保持されます）
• ファイルの競合 - ファイルを共有する機能は、チームリードが直列化する必要があります（Polyphony コンテナーを使用する場合を除く）
• トークンコスト - 各エージェントは独立した Claude インスタンスです（5 + N 個のインスタンス）