harness - エージェントチーム & スキルアーキテクト

キーワード: harness · build a harness · design agent team · harness engineering

メタスキル: harness は、ドメイン作業を実行するチームとスキルを設計します。

Harness は複雑なタスクを、専門化されたエージェントの調整されたチームに分解します。ドメインを分析し、適切なアーキテクチャパターンを選択し、エージェント定義ファイルとスキルを生成してから、ハーネスをエンドツーエンドで検証します。

エージェントチームには以下が必要です: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

このスキルをいつ使用するか

• 複雑なプロジェクトを調整されたマルチエージェントチームに分解する
• 適切なアーキテクチャを選択する: パイプライン、ファンアウト/ファンイン、エキスパートプール、プロデューサーレビュアー、スーパーバイザー、または階層的委譲
• .claude/agents/{name}.md エージェント定義ファイルを生成する
• バンドルされたリソースを含む .claude/skills/{name}/SKILL.md スキルファイルを生成する
• トリガー条件を検証し、ドライランを実行し、ハーネスの有無で品質を比較する
• 以下のハーネスを構築する: 調査、コーディング、コンテンツ作成、コードレビュー、データパイプライン、マーケティング

手順

ステップ1: ドメイン分析

タスクとプロジェクトコンテキストを分析します:

1. コードベースまたはユーザーリクエストを読んで、ドメイン、サブタスク、出力を特定する
2. ユーザーの専門知識レベルを検出する(初心者 → 詳細なスキャフォルディング; 専門家 → シンプルな定義)
3. 個別のタスクタイプをリストアップする — これらはエージェントロールにマップされます
4. 実行モードを決定する:
   • エージェントチーム(デフォルト): 2つ以上のエージェントが通信またはクロス検証を必要とする → TeamCreate + SendMessage を使用
   • サブエージェント(軽量): タスクが独立しており結果はオーケストレーターに返すのみ → Agent ツールを使用

ステップ2: チームアーキテクチャの設計

タスク構造に基づいてパターンを選択します(references/agent-design-patterns.mdを参照):

パターン	使用する場合	例
パイプライン	順序的に依存するステージ	設計 → コード → レビュー → デプロイ
ファンアウト/ファンイン	並列した独立した作業を最後にマージ	4人の調査員 → シンセサイザー
エキスパートプール	入力タイプによる動的ルーティング	セキュリティ、パフォーマンス、またはスタイルエキスパートへのルーティング
プロデューサーレビュアー	生成 + 検証サイクル	ライター + エディターループ
スーパーバイザー	動的割り当てを行う中央コーディネーター	スーパーバイザー + マイグレーター
階層的委譲	再帰的分解(最大2レベル)	PM → テックリード → エンジニア

主要ルール:

• エージェントチームがデフォルトです; エージェント間通信が不要な場合のみサブエージェントを選択します
• すべてのエージェントはファイルベース (.claude/agents/{name}.md) である必要があります — Agent ツールプロンプトにロールをインラインで埋め込まないでください
• チームのネストを避けます(チームメンバー自体がチームを作成することはできません)
• 階層的委譲の最大2レベル

ステップ3: エージェント定義ファイルの生成

各エージェントに対して .claude/agents/{agent-name}.md を作成します。このテンプレートを使用します:

---
name: {agent-name}
description: {ロールと活動化条件}
model: opus
allowed-tools: {ツールリスト}
---

# {Agent Name}

## コア責任
- {主要責任1}
- {主要責任2}

## 運用原則
1. {原則1}
2. {原則2}

## 入力プロトコル
- 受け取る: {このエージェントが使用する入力}
- フォーマット: {予想されるフォーマット}

## 出力プロトコル
- 生成する: {このエージェントが配信する出力}
- フォーマット: {出力フォーマットと場所}

## エラーハンドリング
- 失敗時: {リカバリー動作}
- エスカレーション: {オーケストレーターに通知するとき}

## チームコミュニケーション
- レポート先: {オーケストレーターまたはピア}
- コミュニケーション対象: {SendMessage 経由のピアエージェント}
- 完了シグナル: {完了をシグナルする方法}

特別な理由がない限り、すべてのエージェントに model: opus を使用します。

ステップ4: スキルファイルの生成

チームが必要とするスキルごとに、エージェントスキル仕様に従って .claude/skills/{skill-name}/SKILL.md を作成します:

1. 「強気な」説明を書く — 特定の条件と同義語で積極的にトリガーを招待する
2. なぜ(コンテキスト)を説明する、単なる何を(コマンド)ではなく
3. SKILL.md を500行以下に保つ — 詳細なドキュメントは references/ に移す
4. 再利用可能なロジックを scripts/ にバンドルする
5. プログレッシブディスクロージャーを適用する: メタデータ → 本文 → 参考資料

オーケストレータースキルテンプレートについては、references/orchestrator-template.mdを参照してください。 チームアーキテクチャの例については、references/team-examples.mdを参照してください。

ステップ5: 統合 & オーケストレーション

オーケストレーターのスキルまたはエージェントで完全なワークフローを定義します:

1. フェーズの依存関係を指定します(次のフェーズが開始する前に完了する必要があるエージェント)
2. データ受け渡しを定義します: 中間アーティファクトには _workspace/ にアンカーされた絶対パスを使用
3. エージェント失敗、タイムアウト、データ競合のエラーハンドリングを追加
4. 中間アーティファクトを保持して実行後の検証を可能にします — 削除しないでください

ステップ6: 検証 & テスト

ハーネスを使用する前に検証を実行して確認します:

bash scripts/validate-harness.sh .claude/agents/ .claude/skills/

検証チェック:

• 構造: エージェント定義ファイルに必要なセクションが存在
• トリガー条件: 20の評価クエリ(10は トリガー対象 + 10は トリガー対象外)
• ドライラン: 実際のタスクを実行せずにチーム実行をシミュレート
• 比較: ハーネスありとなしの品質(ベースライン) — +50%スコア改善を目指す

テスト方法については、references/skill-testing-guide.mdを参照してください。

例

例1: 調査ハーネス(ファンアウト/ファンイン)

プロンプト: "Build a harness for deep technology research"

生成されるエージェント:
  .claude/agents/official-researcher.md    — ドキュメント & 公式ソース
  .claude/agents/media-researcher.md       — 投資トレンド & ニュース
  .claude/agents/community-researcher.md   — ソーシャルレスポンス & フォーラム
  .claude/agents/background-researcher.md  — 競争環境
  .claude/agents/research-orchestrator.md  — 調査結果を統合

パターン: ファンアウト/ファンイン(4人の並列調査員 → オーケストレーター)

例2: コードレビューハーネス(エキスパートプール)

プロンプト: "Design an agent team for thorough code review"

生成されるエージェント:
  .claude/agents/security-reviewer.md      — OWASP、インジェクション、シークレット
  .claude/agents/performance-reviewer.md   — 複雑性、メモリ、レイテンシ
  .claude/agents/testing-reviewer.md       — カバレッジ、アサーション、モック
  .claude/agents/review-orchestrator.md    — 調査結果を統合

主要機能: レビュアーが直接通信(クロスドメイン問題検出)

例3: コンテンツ制作ハーネス(パイプライン + 並列)

プロンプト: "Build a harness for webtoon production"

フェーズ1(並列): worldbuilder + character-designer + plot-architect
フェーズ2(順序): prose-stylist がフェーズ1 に基づいて執筆
フェーズ3(並列): science-consultant + continuity-manager がレビュー
フェーズ4(順序): prose-stylist がフィードバックを組み込む

ベストプラクティス

1. ファイルベースのエージェントを常に使用 — Agent ツールプロンプトにロールをインラインで埋め込むと、セッション全体で再利用できない
2. デフォルトではエージェントチーム — 調整を必要とする作業には、サブエージェントより TeamCreate + SendMessage を優先
3. 「強気な」説明 — パッシブな説明はスキルが起動することはありません; 能動的な招待を書く
4. なぜを説明する、単なる何ではなく — エージェントは厳密なコマンドより推論に従う
5. 中間アーティファクトを保持 — _workspace/ ファイルにより実行後の検証とデバッグが可能
6. デプロイ前に検証 — 本番環境でハーネスを使用する前にトリガー評価(20クエリ)とドライランを実行
7. 最大2つのヒエラルキーレベル — より深いネストは、品質向上なしに調整オーバーヘッドを発生させる

参考資料

• Agent Design Patterns
• Orchestrator Template
• Team Examples
• Skill Writing Guide
• Skill Testing Guide
• harness GitHub
• Agent Skills Specification