新しいチームを作成する

複数の視点、専門知識、またはフェーズを必要とするタスクを達成するために2つ以上のエージェントを調整するマルチエージェントチーム構成を定義する。結果のチームファイルはチームレジストリと統合され、名前でClaude Codeでアクティブ化できる。

使用タイミング

• タスクが単一エージェントが提供できない複数の視点を必要とする場合（例: コードレビュー + セキュリティ監査 + アーキテクチャレビュー）
• 一貫した役割割り当てとハンドオフパターンを持つ繰り返される協調ワークフローが必要な場合
• 既存のエージェント構成が繰り返し使用されており、正式化すべき場合
• 複雑なプロセスが自然に異なるエージェントが処理するフェーズや専門知識に分解される場合
• スプリントベース、パイプラインベース、または並行作業のための調整されたグループを定義したい場合

入力

• 必須: チーム名（小文字ケバブケース、例: data-pipeline-review）
• 必須: チームの目的（複数のエージェントが必要な問題を説明する一段落）
• 必須: リードエージェント（agents/_registry.yml に存在しなければならない）
• 任意: 調整パターン（デフォルト: hub-and-spoke）。hub-and-spoke、sequential、parallel、timeboxed、adaptive のいずれか
• 任意: メンバー数（デフォルト: 3〜4; 推奨範囲: 2〜5）
• 任意: ソース素材（正式化する既存のワークフロー、ランブック、またはアドホックなチーム構成）

手順

ステップ1: チームの目的を定義する

複数のエージェントが共同作業を必要とする問題を明確にする。有効なチームの目的は以下に答える必要がある:

1. このチームが提供する成果は何か? （例: 包括的なレビューレポート、デプロイされたアプリケーション、スプリント増分）
2. 単一エージェントではなぜできないのか? 必要な少なくとも2つの異なる専門知識または視点を特定する。
3. このチームはいつアクティブ化されるべきか? トリガー条件を定義する。

人間またはエージェントがこのチームをアクティブ化するかどうかを決定するために読める一段落として目的を書く。

期待結果： 少なくとも2つの異なる専門知識が特定された、チームの価値提案を説明する明確な段落。

失敗時： 2つの異なる専門知識を特定できない場合、タスクはおそらくチームを必要としない。代わりに複数のスキルを持つ単一エージェントを使用する。

ステップ2: リードエージェントを選択する

リードエージェントはチームを調整する。agents/_registry.yml から以下のエージェントを選ぶ:

• チームの主要な成果に関連するドメイン専門知識を持つ
• 受け取ったリクエストを他のメンバーへのサブタスクに分解できる
• 複数のレビュワーからの結果を一貫した成果物に合成できる

# 利用可能なすべてのエージェントを一覧表示する
grep "^  - id:" agents/_registry.yml

リードはチーム構成のメンバーとしても表示される必要がある（リードは常にメンバーだ）。

期待結果： リードとして選ばれた一つのエージェントが、エージェントレジストリに存在することが確認されている。

失敗時： リード役に適した既存のエージェントがない場合、先に create-agent スキル（または agents/_template.md を手動で）を使用してエージェントを作成する。存在しないエージェント定義のリードを持つチームを作成しない。

ステップ3: メンバーエージェントを選択する

重複しない責任を持つ明確な2〜5のメンバー（リードを含む）を選ぶ。各メンバーに対して定義する:

• id: エージェントレジストリからのエージェント名
• role: 短いタイトル（例: 「品質レビュワー」「セキュリティ監査人」「アーキテクチャレビュワー」）
• responsibilities: このメンバーが他のメンバーが行わないことを説明する一文

# 各候補エージェントが存在することを確認する
grep "id: agent-name-here" agents/_registry.yml

重複しないことを確認する: 2人のメンバーが同じ主な責任を持つべきではない。責任が重複する場合、役割をマージするか境界を明確にする。

期待結果： 2〜5のメンバーが選ばれ、それぞれが固有の役割と明確な責任を持ち、すべてがエージェントレジストリで確認されている。

失敗時： 必要なエージェントが存在しない場合、先に作成する。2人のメンバー間で責任が重複している場合、境界を明確にするために書き直すか、一方のメンバーを削除する。

ステップ4: 調整パターンを選択する

チームのワークフローに最も適したパターンを選択する。5つのパターンとそのユースケース:

パターン	使用タイミング	チームの例
hub-and-spoke	リードがタスクを配布し、結果を収集し、合成する。レビューと監査のワークフローに最適。	r-package-review, gxp-compliance-validation, ml-data-science-review
sequential	各エージェントが前のエージェントの出力に基づいて構築する。パイプラインと段階的なワークフローに最適。	fullstack-web-dev, tending
parallel	すべてのエージェントが独立したサブタスクで同時に作業する。サブタスクに依存関係がない場合に最適。	devops-platform-engineering
timeboxed	固定長のイテレーションに整理された作業。バックログを持つ継続的なプロジェクト作業に最適。	scrum-team
adaptive	タスクに基づいてチームが自己組織化する。未知または非常に可変なタスクに最適。	opaque-team

決定ガイド:

• リードが出力を生成する前にすべての結果を見る必要がある: hub-and-spoke
• エージェントBがエージェントAの出力を開始するために必要: sequential
• すべてのエージェントが互いの出力を見ずに作業できる: parallel
• 作業が計画セレモニーを伴う複数のイテレーションにわたる: timeboxed
• タスク構造を事前に予測できない: adaptive

期待結果： 選択に対する明確な根拠を持つ一つの調整パターン。

失敗時： 不明確な場合、hub-and-spokeをデフォルトにする。これは最も一般的なパターンで、ほとんどのレビューと分析ワークフローで機能する。

ステップ5: タスク分解を設計する

典型的な受信リクエストがチームメンバー間でどのように分割されるかを定義する。フェーズとして構造化する:

1. セットアップフェーズ: リードがリクエストを分析してタスクを作成するために何をするか
2. 実行フェーズ: 各メンバーが何を担当するか（調整パターンに応じて並行、順次、またはスプリントごと）
3. 合成フェーズ: 結果がどのように収集され、最終成果物が生成されるか

各メンバーについて、典型的なリクエストで実行する3〜5の具体的なタスクを一覧する。これらのタスクは「タスク分解」の散文セクションとCONFIGブロックの tasks リストの両方に表示される。

期待結果： メンバーごとの具体的なタスクを含むフェーズ構造の分解が、選択した調整パターンと一致している。

失敗時： タスクが曖昧すぎる（例: 「ものをレビューする」）場合、具体的にする（例: 「tidyverseスタイルガイドに対するコードスタイルをレビューし、テストカバレッジを確認し、エラーメッセージの品質を評価する」）。

ステップ6: チームファイルを作成する

テンプレートをコピーしてすべてのセクションを入力する:

cp teams/_template.md teams/<team-name>.md

順番に以下のセクションを入力する:

1. YAMLフロントマター: name、description、lead、version（"1.0.0"）、author、created、updated、tags、coordination、members[]（各メンバーはid、role、responsibilitiesを持つ）
2. タイトル: # Team Name（人間が読める、タイトルケース）
3. イントロダクション: 一段落の要約
4. 目的: このチームが存在する理由、組み合わせる専門知識
5. チーム構成: Member、Agent、Role、Focus Areas列を持つテーブル
6. 調整パターン: フローのASCII図を含む散文の説明
7. タスク分解: メンバーごとの具体的なタスクを含むフェーズ分解
8. 設定: 機械可読なCONFIGブロック（ステップ7を参照）
9. 使用シナリオ: サンプルユーザープロンプトを含む2〜3の具体的なシナリオ
10. 制限事項: 3〜5の既知の制約
11. 参照: メンバーエージェントファイルと関連するスキル/チームへのリンク

期待結果： すべてのセクションが入力された完全なチームファイルで、テンプレートのプレースホルダーテキストが残っていない。

失敗時： 既存のチームファイル（例: teams/r-package-review.md）と比較して構造を確認する。「your-team-name」や「another-agent」などのテンプレートプレースホルダー文字列を検索して未入力のセクションを見つける。

ステップ7: CONFIGブロックを作成する

<!-- CONFIG:START --> と <!-- CONFIG:END --> マーカーの間のCONFIGブロックは、ツール用の機械可読なYAMLを提供する。以下のように構造化する:

<!-- CONFIG:START -->
```yaml
team:
  name: <team-name>
  lead: <lead-agent-id>
  coordination: <pattern>
  members:
    - agent: <agent-id>
      role: <role-title>
      subagent_type: <agent-id>  # Claude Code subagent type for spawning
    # ... repeat for each member
  tasks:
    - name: <task-name>
      assignee: <agent-id>
      description: <one-line description>
    # ... repeat for each task
    - name: synthesize-report  # final task if hub-and-spoke
      assignee: <lead-agent-id>
      description: <synthesis description>
      blocked_by: [<prior-task-names>]  # for dependency ordering
```
<!-- CONFIG:END -->

subagent_type フィールドはClaude Codeのエージェントタイプにマップする。.claude/agents/ で定義されたエージェントには、エージェントIDをsubagent_typeとして使用する。タスクの依存関係（例: 合成はすべてのレビュータスクによってブロックされる）を表現するために blocked_by を使用する。

期待結果： CONFIGブロックが有効なYAMLで、すべてのエージェントがフロントマターのメンバーリストと一致し、タスクの依存関係が有効なDAG（サイクルなし）を形成する。

失敗時： YAML構文を検証する。タスクリストのすべての assignee がメンバーリストの agent と一致することを確認する。blocked_by がリストの前に定義されたタスク名のみを参照していることを確認する。

ステップ8: レジストリに追加する

teams/_registry.yml を編集して新しいチームを追加する:

- id: <team-name>
  path: <team-name>.md
  lead: <lead-agent-id>
  members: [<agent-id-1>, <agent-id-2>, ...]
  coordination: <pattern>
  description: <one-line description matching frontmatter>

レジストリの先頭の total_teams カウントを更新する（現在8; 1つのチームを追加すると9になる）。

# エントリが追加されたことを確認する
grep "id: <team-name>" teams/_registry.yml

期待結果： レジストリに新しいエントリが表示され、total_teams カウントが1増加する。

失敗時： チーム名がレジストリに既に存在する場合、別の名前を選ぶか既存のエントリを更新する。YAMLのインデントが既存のエントリと一致していることを確認する。

ステップ9: READMEオートメーションを実行する

更新されたレジストリからREADMEファイルを再生成する:

npm run update-readmes

これにより teams/README.md の動的セクションと、チームデータを参照する <!-- AUTO:START --> / <!-- AUTO:END --> マーカーを持つその他のファイルが更新される。

期待結果： コマンドが0で終了し、teams/README.md に新しいチームが一覧される。

失敗時： npm run check-readmes を実行して同期していないファイルを確認する。スクリプトが失敗する場合、リポジトリルートに package.json が存在し js-yaml がインストールされていることを確認する（npm install）。

ステップ10: チームのアクティベーションを確認する

Claude Codeでチームをアクティブ化できることをテストする:

User: Use the <team-name> team to <typical task description>

Claude Codeは以下を行うべきだ:

1. teams/<team-name>.md でチームファイルを見つける
2. リードとメンバーを特定する
3. ファイルで説明された調整パターンに従う

期待結果： Claude Codeがチーム名を認識し、正しいリードとメンバーを特定し、調整パターンに従う。

失敗時： チームファイルが teams/<team-name>.md にあることを確認する（サブディレクトリではない）。すべてのメンバーエージェントが .claude/agents/（agents/ にシンリンク）に存在することを確認する。チームが teams/_registry.yml に一覧されていることを確認する。

ステップ11: 翻訳ファイルを生成する

すべてのチームに必須。 このステップは、この手順に従う人間の著者とAIエージェントの両方に適用される。スキップしない — 欠落した翻訳は古いバックログとして蓄積される。

新しいチームをコミットした直後に、サポートされている4つのロケールすべての翻訳ファイルを生成する:

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- teams <team-name> "$locale"
done

その後、各ファイル内の生成されたプロセを翻訳する（コードブロックとIDは英語のまま）。最後にステータスファイルを再生成する:

npm run translation:status

期待結果： i18n/{de,zh-CN,ja,es}/teams/<team-name>.md に4つのファイルが作成され、すべての source_commit が現在のHEADと一致する。npm run validate:translations は新しいチームに対して0件の古さ警告を示す。

失敗時： 足場作りが失敗した場合、チームが teams/_registry.yml に存在するか確認する。ステータスファイルが更新されない場合、npm run translation:status を明示的に実行する — CIでは自動的にトリガーされない。

バリデーション

• チームファイルが teams/<team-name>.md に存在する
• YAMLフロントマターがエラーなく解析される
• 必須フロントマターフィールドすべてが存在する: name、description、lead、version、author、coordination、members[]
• フロントマターの各メンバーに id、role、responsibilities がある
• すべてのセクションが存在する: 目的、チーム構成、調整パターン、タスク分解、設定、使用シナリオ、制限事項、参照
• CONFIGブロックが <!-- CONFIG:START --> と <!-- CONFIG:END --> マーカーの間に存在する
• CONFIGブロックのYAMLが有効で解析可能
• すべてのメンバーエージェントIDが agents/_registry.yml に存在する
• リードエージェントがメンバーリストに表示されている
• 2人のメンバーが同じ主な責任を持っていない
• チームが teams/_registry.yml に正しいパス、リード、メンバー、調整パターンで一覧されている
• レジストリの total_teams カウントがインクリメントされている
• npm run update-readmes がエラーなく完了する

よくある落とし穴

• メンバーが多すぎる: 5人を超えるメンバーを持つチームは調整が困難になる。タスクの配布と結果の合成のオーバーヘッドが追加の視点の利益を上回る。2つのチームに分割するか、必須の専門知識に削減する。
• 重複する責任: 2人のメンバーが両方とも「コード品質をレビューする」と言う場合、その発見は衝突し、リードが重複排除に時間を無駄にする。各メンバーは明確に異なるフォーカスエリアを持つ必要がある。
• 間違った調整パターン: エージェントが互いの出力を必要とする場合にhub-and-spokeを使用する（sequentialであるべき）か、エージェントが独立して作業できる場合にsequentialを使用する（parallelであるべき）。ステップ4の決定ガイドを確認する。
• CONFIGブロックの欠落: CONFIGブロックはオプションの散文装飾ではない。ツールが TeamCreate でチームを自動作成するために読む。それなしでは、チームファイルは人間が読めるだけで、プログラム的にアクティブ化できない。
• メンバーリストにないリードエージェント: リードはメンバーとして固有の役割と責任を持って表示される必要がある。「調整する」だけで実質的な作業をしないリードはスロットを無駄にする。リードに具体的なレビューまたは合成責任を与える。

関連スキル

• create-skill - SKILL.mdファイルを作成するための同じメタパターンに従う
• create-agent - チームメンバーとして機能するエージェント定義を作成する
• commit-changes - 新しいチームファイルとレジストリ更新をコミットする