harness

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: {role and activation conditions}
model: opus
allowed-tools: {tool list}
---

# {Agent Name}

## Core Responsibilities
- {primary responsibility 1}
- {primary responsibility 2}

## Operational Principles
1. {principle 1}
2. {principle 2}

## Input Protocol
- Receives: {what inputs this agent consumes}
- Format: {expected format}

## Output Protocol
- Produces: {what outputs this agent delivers}
- Format: {output format and location}

## Error Handling
- On failure: {recovery behavior}
- Escalation: {when to notify orchestrator}

## Team Communication
- Reports to: {orchestrator or peer}
- Communicates with: {peer agents via SendMessage}
- Completion signal: {how to signal done}

速度が重要でない限り、デフォルトですべてのエージェントに model: opus を使います。

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

チームが必要とするスキルごとに、Agent Skills 仕様に従って .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：統合とオーケストレーション

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

実行前：エージェントチームモードを使用するため、環境で CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が設定されていることを確認してください。

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：調査ハーネス（ファンアウト／ファンイン）

Prompt: "Build a harness for deep technology research"

Generated agents:
  .claude/agents/official-researcher.md    — documentation & official sources
  .claude/agents/media-researcher.md       — investment trends & news
  .claude/agents/community-researcher.md   — social response & forums
  .claude/agents/background-researcher.md  — competitive landscape
  .claude/agents/research-orchestrator.md  — synthesizes findings

Pattern: Fan-out/Fan-in (4 parallel researchers → orchestrator)

例 2：コードレビュー用ハーネス（エキスパートプール）

Prompt: "Design an agent team for thorough code review"

Generated agents:
  .claude/agents/security-reviewer.md      — OWASP, injection, secrets
  .claude/agents/performance-reviewer.md   — complexity, memory, latency
  .claude/agents/testing-reviewer.md       — coverage, assertions, mocks
  .claude/agents/review-orchestrator.md    — consolidates findings

Key feature: reviewers communicate directly (cross-domain issue detection)

例 3：コンテンツ制作ハーネス（パイプライン＋並列処理）

Prompt: "Build a harness for webtoon production"

Phase 1 (parallel): worldbuilder + character-designer + plot-architect
Phase 2 (sequential): prose-stylist writes based on Phase 1
Phase 3 (parallel): science-consultant + continuity-manager review
Phase 4 (sequential): prose-stylist incorporates feedback

ベストプラクティス

1. エージェントは常にファイルベースにする — Agent ツールのプロンプトに役割を直接埋め込むと、セッション間で再利用できません
2. デフォルトでエージェントチームを使用する — 調整が必要な作業では、サブエージェントよりも TeamCreate と SendMessage を優先します
3. 「積極的な」説明を記述する — 受け身の説明ではスキルが起動しません。積極的に促す表現を使用します
4. 内容だけでなく理由も説明する — エージェントは固定的なコマンドよりも、理由に沿って適切に動作します
5. 中間成果物を保持する — _workspace/ のファイルは、実行後の検証やデバッグに役立ちます
6. デプロイ前に検証する — 本番環境でハーネスを使用する前に、トリガー評価（クエリ 20 件）とドライランを実行します
7. 階層は最大 2 レベルにする — それ以上深くネストしても品質は向上せず、調整の負荷が増します

参考資料

• エージェント設計パターン
• オーケストレーターテンプレート
• チームの例
• スキル作成ガイド
• スキルテストガイド
• harness GitHub
• エージェントスキル仕様