🦾 技術調査 - harness

概要

harness（revfactory/harness）は、Claude Code 向けのメタスキルプラグインです。「このプロジェクト向けの harness を作って」という一言から、ドメイン特化のエージェントチームと専用スキルを自動生成します。

Claude Code エコシステムにおける位置づけ

harness は Claude Code エコシステムを 3 層で捉えたときの L3 Meta-Factory 層 に位置します。各層の役割は以下のとおりです。

L3 はさらに 2 つのサブ層に分かれ、harness は前者を担います。

L3 Meta-Factory 層
├── Team-Architecture Factory  ← harness（チーム構造とメッセージプロトコルを生成）
└── Runtime-Configuration Factory  ← Archon（実行時の決定論的設定を生成）

この層モデルは Martin Fowler の "Harness Engineering" 記事および revfactory/harness の README で整理されています。詳細は本記事末尾の参考リンクを参照してください。

Claude Code の構成要素との関係

harness は Claude Code の Agent Teams・Subagents・Skills の 3 つすべてを活用します。

harness を実行すると、.claude/agents/ と .claude/skills/ 配下に Markdown 形式のエージェント定義とスキルファイルが生成されます。

類似ツールとの比較

revfactory エコシステム内の関連リポジトリ

周辺ツールとの比較

手動構成方式との比較

A/B テスト結果

revfactory/claude-code-harness リポジトリで実施した 15 タスク（Basic・Advanced・Expert 各 5 件）の比較実験結果です。

タスク難易度別の品質向上幅は、Basic +23.8 点、Advanced +29.6 点、Expert +36.2 点であり、タスクが複雑になるほど改善効果が大きくなります。著者による計測値（n=15）であり、第三者による再現検証は未実施です。

特徴

• メタスキルとしての自律生成: 単一のプロンプトから、エージェント定義・スキル・オーケストレーション設定を一括生成
• 6 種のアーキテクチャパターン: Pipeline・Fan-out/Fan-in・Expert Pool・Producer-Reviewer・Supervisor・Hierarchical Delegation から最適なパターンを自動選択
• Progressive Disclosure によるコンテキスト最適化: 詳細情報を必要なときだけロードし、コンテキストウィンドウを効率的に使用
• 2 つの実行モード: 複数エージェントが協調する Agent Teams モードと、単体で動作する Subagents モードを使い分け
• 検証フレームワーク内蔵: トリガー検証・ドライランテスト・A/B 比較テストで生成物の品質を担保
• 進化ループ: 初期設計と最終成果物の差分を蓄積し、次回生成の品質を継続改善
• harness-100 によるテンプレート提供: 10 ドメイン・100 種のプロダクション対応チーム構成を参照可能

ユースケース別推奨パターン

Deep Research チームの構成例（Fan-out/Fan-in パターン）

Code Review チームの構成例（Fan-out/Fan-in パターン）

構造

システムコンテキスト図

コンテナ図

Harness スキルパッケージ — 要素説明

Claude Code ランタイム — 要素説明

生成物 — 要素説明

コンポーネント図

references ドキュメント群 — 要素説明

生成されるエージェント例 — 要素説明

生成されるスキル例 — 要素説明

データ

概念モデル

概念モデル補足

エージェント間データ受け渡し方式

harness は用途に応じて 4 方式を使い分けます。

Agent Teams モードのライフサイクルは TeamCreate でチーム編成 → TaskCreate で作業分配 → SendMessage / TaskGet で調整 → TeamDelete でチーム解散の順で進みます。Phase 間でチームを再構成する場合、一度 TeamDelete で解散し、成果物を _workspace/ に保存してから次の TeamCreate を呼び出します（エージェント・チームはネストできないためこの手順が必須です）。

• ファイルベースは _workspace/ 配下で命名規則 {phase}_{agent}_{artifact}.{ext} に従って配置します。

_workspace/
├── phase1_analyst_domain-summary.md
├── phase2_architect_team-design.md
└── phase3_builder_agent-definitions.md

• 2 体以上のエージェントが協調する場合は Agent Teams をデフォルトとし、メッセージ・タスク・ファイルを組み合わせます。
• Subagent モードでは SendMessage / TaskCreate を使えないため、戻り値ベースとファイルベースの 2 方式のみ選択できます。

情報モデル

属性一覧

Domain

ArchitecturePattern

Agent

Skill

Task

Message

Workspace

構築方法

前提条件

• Claude Code がインストール済みであること
• バージョン 1.2.0 以降の harness プラグインに対応する Claude Code が必要
• Agent Teams 機能を有効にするため、環境変数 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

インストール方法 1: マーケットプレイス経由

Claude Code のプラグインマーケットプレイスを使って 2 ステップでインストールします。

/plugin marketplace add revfactory/harness
/plugin install harness@harness

インストール方法 2: 直接コピー

リポジトリを clone し、スキルディレクトリを手動でコピーします。

git clone https://github.com/revfactory/harness.git
cp -r harness/skills/harness ~/.claude/skills/harness

バージョン確認

インストール後、プラグイン情報でバージョンを確認します。

/plugin list

harness@1.2.0 のように表示されれば正常にインストール済みです。

プラグイン構成

harness/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── harness/
│       ├── SKILL.md
│       └── references/
│           ├── agent-design-patterns.md
│           ├── orchestrator-template.md
│           ├── team-examples.md
│           ├── skill-writing-guide.md
│           ├── skill-testing-guide.md
│           └── qa-agent-guide.md
└── README.md

利用方法

重要パラメータ一覧

トリガーコマンド

Claude Code のプロンプトに以下のいずれかを入力して harness を起動します。

Build a harness for this project
Design an agent team for this domain
Set up a harness

日本語でも起動できます。

ハーネスを構成して
ハーネス構築して

8 フェーズワークフローの実行

トリガー後、harness スキルは以下の 8 フェーズ（Phase 0〜7）を自動で進行します。なお公式 README は中核となる 6-Phase（Phase 1〜6）を前面に出しており、Phase 0（現況監査）と Phase 7（ハーネス進化・運用保守）は内部 SKILL.md に含まれる拡張フローです。

Phase 0: 現況監査
  ↓
Phase 1: ドメイン分析
  ↓
Phase 2: チームアーキテクチャ設計
  ↓
Phase 3: エージェント定義の生成
  ↓
Phase 4: スキル生成
  ↓
Phase 5: 統合とオーケストレーション
  ↓
Phase 6: 検証とテスト
  ↓
Phase 7: ハーネス進化（フィードバック反映・運用/保守）

フェーズごとの入出力・参照 references 対応表

Phase 0: 現況監査

• .claude/agents/・.claude/skills/・CLAUDE.md を読み込み、既存 harness の状態を確認します
• 「新規構築」「既存拡張」「運用・保守」の 3 モードに分岐します
• 監査結果をユーザーに報告し、実行計画の確認を求めます

Phase 1: ドメイン分析

• ユーザーの要求からドメインと核心的な作業種別を特定します
• プロジェクトのコードベースを探索し、技術スタック・データモデルを把握します
• 既存エージェント・スキルとの重複や競合を検出します

Phase 2: チームアーキテクチャ設計

• 実行モード（Agent Teams / Subagent / Hybrid）を決定します
• 6 アーキテクチャパターンから最適なものを選択します（agent-design-patterns.md を参照）
• エージェント分離基準（専門性・並列性・コンテキスト・再利用性）で構成を決定します

Phase 3: エージェント定義の生成

• 各エージェントを プロジェクト/.claude/agents/{name}.md として出力します
• 必須セクション: 核心的役割、作業原則、入出力プロトコル、エラーハンドリング、協働方式
• 全 Agent 呼び出しに model: "opus" パラメータを明示します
• .claude/agents/{name}.md の最小スケルトン例:

---
name: analyst
description: Domain analysis specialist. Triggered by orchestrator for Phase 1 tasks.
model: opus
---
## Core Responsibilities
- ユーザー要求からドメインと作業種別を特定する
- 技術スタックとデータモデルを把握する

## Work Principles
- 既存スキル・エージェントとの重複を検出して報告する

## Input Protocol
- orchestrator からの `SendMessage` でタスク内容を受領する

## Output Protocol
- `_workspace/phase1_analyst_domain-summary.md` に分析結果を書き出す

## Error Handling
- 要求が曖昧な場合は orchestrator へ追加情報を要求する

Phase 4: スキル生成

• 各エージェントが使うスキルを プロジェクト/.claude/skills/{name}/SKILL.md として出力します
• スキル本文は 500 行以内を目標とし、超過する場合は references/ に分離します
• description はトリガーを積極的に誘導する文章で記述します
• .claude/skills/{name}/SKILL.md の最小スケルトン例:

---
name: analyze
description: Use when the user requests domain analysis, asks to analyze codebase, or mentions "analyze this project". Triggers automatically on analysis requests.
disable-model-invocation: false
allowed-tools: [Read, Glob, Grep, Bash]
---

# Analyze Skill

## 目的
ドメイン分析を構造化されたワークフローで実行する。

## 手順
1. プロジェクトのコードベースを探索する
2. 技術スタックを `_workspace/phase1_analyst_stack.md` に記録する

## 参照ドキュメント
- 詳細ルールは `references/domain-taxonomy.md` を参照する

Phase 5: 統合とオーケストレーション

• オーケストレータースキルを 1 つ生成し、エージェント間のデータフローとエラーハンドリングを定義します
• 中間成果物の保存先として _workspace/ ディレクトリを使用します（ファイル名規則: {phase}_{agent}_{artifact}.{ext}）
• CLAUDE.md にトリガー規則と変更履歴のみを記録します（エージェント一覧は記録しない）

## ハーネス: {ドメイン名}

**目標:** {ハーネスの核心的目標を一行で}

**トリガー:** {ドメイン} 関連の作業要求時に `{orchestrator-skill-name}` スキルを使用する。

**変更履歴:**
| 日付       | 変更内容 | 対象 | 理由 |
| ---------- | -------- | ---- | ---- |
| YYYY-MM-DD | 初期構築 | 全体 | -    |

Phase 6: 検証とテスト

• 全エージェントファイルの存在・配置を確認します（構造検証）
• 各スキルに対して 2〜3 個のテストプロンプトを実行します（with-skill vs without-skill 比較）
• should-trigger クエリ 10 個・should-NOT-trigger クエリ 10 個（合計 20 個）でトリガーを検証します
• オーケストレーターのフェーズ順序・データ連結・エラー経路をドライランで確認します

Phase 7: ハーネス進化

• 本番投入直後にフィードバックと差分（delta）を収集し、次回生成の出発点を改善します
• 既存ハーネスの点検・修正・同期（運用/保守）もこのフェーズの一部として扱います
• 変更内容は CLAUDE.md の変更履歴テーブルに記録します
• 修正範囲がトリガーに影響する場合、Phase 6 のトリガー検証を再実行します

6 アーキテクチャパターン概要

エージェント構成例と実行モード適性

生成物の配置と確認方法

ハーネス生成後のプロジェクト構造は以下のとおりです。

your-project/
├── CLAUDE.md
└── .claude/
    ├── agents/
    │   ├── analyst.md
    │   ├── builder.md
    │   └── qa.md
    └── skills/
        ├── orchestrator/
        │   └── SKILL.md
        ├── analyze/
        │   └── SKILL.md
        └── build/
            ├── SKILL.md
            └── references/

生成完了チェックリスト（Phase 6 でも確認されます）:

- [ ] .claude/agents/ にエージェント定義ファイルが存在する
- [ ] .claude/skills/ にスキルファイルが存在する（SKILL.md + references/）
- [ ] オーケストレータースキルが 1 つ存在する
- [ ] 全 Agent 呼び出しに model: "opus" が明示されている
- [ ] .claude/commands/ には何も生成されていない
- [ ] CLAUDE.md にハーネスポインタが登録されている
- [ ] スキル description に後続作業キーワードが含まれている

生成された Agent / Skill の実行方法

• 生成後は、CLAUDE.md に登録されたトリガー語句でオーケストレータースキルが自動起動します

ディープリサーチを実行して

• 個別エージェントはオーケストレーターが TeamCreate + SendMessage + TaskCreate を使って自律的に管理します
• 後続作業（再実行・部分修正）もトリガー語句で実行できます

前回の結果を更新して
分析部分だけもう一度やり直して

Harness 100 リポジトリの利用方法

revfactory/harness-100 は harness プラグインで生成された 100 種類のプロダクションレディなハーネスを収録したコレクションです。英語（en/）・韓国語（ko/）の 2 言語で提供され、合計 200 パッケージを含みます。

目的に合うハーネスを選び、プロジェクトの .claude/ に直接コピーして使用できます。

git clone https://github.com/revfactory/harness-100.git
cp -r harness-100/en/01-youtube-production/.claude/ /path/to/my-project/.claude/

コピー後は CLAUDE.md のトリガー規則を確認し、プロジェクトのドメインに合わせて編集します。各ハーネスは以下の 3 層スキル構造で提供されます。

運用

プラグイン更新

Marketplace 経由でインストールした場合は、以下のコマンドで更新します。

/plugin marketplace add revfactory/harness
/plugin install harness@harness

直接インストールした場合は、リポジトリを pull してスキルディレクトリを上書きします。

git pull origin main
cp -r skills/harness ~/.claude/skills/harness

• 更新後は既存の Agent・Skill ファイルとの互換性を確認します
• ~/.claude/agents/ と ~/.claude/skills/ 配下の生成済みファイルは上書き対象外のため、手動マージが必要です

Skill バージョン管理

• 生成された Skill ファイル（~/.claude/skills/{name}/SKILL.md）はプロジェクトの Git で管理します
• 変更履歴は CLAUDE.md に「変更ログ」として記録します
• SKILL.md は 500 行以内を維持します。超過分は references/ ディレクトリに分割します

Skill の Evolution（進化）メカニズム

• /harness:evolve スキルを使って、初期アーキテクチャと本番リリース後のアーキテクチャの差分（delta）を取得します
• 差分は harness ファクトリーにフィードバックされ、次回生成時の出発点を改善します

/harness:evolve

• 実行タイミングは「プロジェクト本番投入直後」が推奨です
• 蓄積された進化データにより、同一ドメインの次回生成品質が向上します

Agent Team のテスト実行

• テストは「with-skill あり」と「なし」の 2 つのサブエージェントを並行して比較します
• 最低 2〜3 件の現実的なプロンプトでコアユースケース・エッジケースをカバーします
• タイミングデータ（トークン数・実行時間）はエージェント完了直後に取得します（後から取得不可）

// eval_metadata.json
{
  "prompt": "...",
  "assertions": []
}
// grading.json
{
  "expectations": [
    { "text": "PDFをMarkdownに変換する", "passed": true, "evidence": "出力に Markdown が含まれる" }
  ],
  "summary": {
    "passed": 2,
    "failed": 0,
    "total": 2,
    "pass_rate": 1.00
  }
}
// timing.json
{
  "tokens": 1234,
  "duration_ms": 5678
}

検証・テスト手順

1. should-trigger クエリ 10 件で起動確認します
2. should-NOT-trigger クエリ 10 件（合計 20 件）で誤起動がないことを確認します
3. エッジケースや near-miss を重点的に検証します
4. 既存スキルとの description 競合がないことを確認します

ベストプラクティス

6 アーキテクチャパターンの使い分け指針

• 複合パターンも有効です。例: Fan-out（並列翻訳）＋ Producer-Reviewer（ネイティブチェック）
• 2 つ以上のエージェントが協調する場合は Agent Team をデフォルトとします
• Subagent はエージェント間通信が「不要」と明確な場合のみ採用します

Progressive Disclosure の 3 層構造

各層を分離することで、未使用の詳細情報をコンテキストウィンドウに載せず、トークンコストを最小化しながら精度を維持します。

Progressive Disclosure の黄金則

• SKILL.md には「常にロードすべきメタデータ」のみ記載します
• 詳細コンテンツは references/ ディレクトリに分割し、必要時のみロードします
• 300 行超の参照ファイルには目次（Table of Contents）を必ず付けます
• すべての文章は「トークンコストを正当化できるか」で取捨選択します
• Claude がすでに知っている一般知識は記載しません。エラー防止に必要な情報のみ残します

~/.claude/skills/my-skill/
├── SKILL.md
└── references/
    ├── overview.md
    ├── detail-a.md
    └── detail-b.md

命名規約

• Agent ファイル: ~/.claude/agents/{role-name}.md（ケバブケース、役割を表す名詞）
• Skill ファイル: ~/.claude/skills/{domain-name}/SKILL.md（ドメイン名 + SKILL.md 固定）
• description は「何をするか」と「いつ使うか（トリガー条件）」を明示します

<!-- 良い例 -->
Use when PDF files are mentioned, PDFs are requested as output, 
or text/table extraction from PDF occurs.

<!-- 悪い例 -->
A PDF processing skill.

Skill と Agent の責務分離

• スキルには「why-first」アプローチで記述します（「ALWAYS 使え」より「なぜそれが良いか」を説明）
• 一般化を優先します（特定ファイル名への narrow fix より原則レベルの修正）

QA の組み込み方

• Producer-Reviewer パターンで QA エージェントを配置します
• QA エージェントは単独コンポーネントの正しさより「コンポーネント間の境界整合性」を検証します
• 各モジュール完成後に逐次実行します（全工程完了後まとめて実施しない）
• 検証観点: API レスポンス形状 ↔ フロントエンド型定義、ルーティングパス ↔ ページファイル存在、状態遷移定義 ↔ 実コード
• 最大リトライ回数は 2〜3 回に制限して無限ループを防止します

エージェント設計のアンチパターン

• CLAUDE.md への実装詳細の埋め込み: 実装詳細は Agent/Skill ファイルに記載し、CLAUDE.md にはトリガー規則と変更履歴のみを置きます
• 3 層超の階層化: ネストが 3 層を超えると遅延とコンテキスト消失が増大します。2 層推奨です
• Agent Team のネスト: チームメンバーはサブチームを生成できません。設計時に注意します
• 全エージェント opus 未指定: すべての Agent 呼び出しで model: "opus" を明示指定します
• 500 行超の SKILL.md: コンテキスト肥大化を招くため、超過分を references/ に分割します
• description の受動的記述: トリガー条件を具体的に列挙しない description は誤起動・未起動の原因になります

トラブルシューティング

まとめ

harness は Claude Code 向けのメタスキルプラグインで、ドメイン説明の一文から 8 フェーズワークフローを通じてエージェントチームと専用スキルを自動生成します。6 種のアーキテクチャパターンと Progressive Disclosure を組み合わせ、A/B テスト（著者計測 n=15・第三者による再現検証は未実施）では品質スコア +60%・全勝という効果が報告されており、Claude Code でドメイン特化エージェントを構築したい開発者にとって有力な選択肢になります。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNS でのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント
  • Harness — Agent Team & Skill Architect for Claude Code（公式サイト）
  • Claude Code Agent Teams
  • Claude Code Skills
• GitHub
  • revfactory/harness
  • revfactory/harness — README（英語）
  • revfactory/harness — README（日本語）
  • revfactory/harness — README（韓国語）
  • revfactory/harness — SKILL.md
  • revfactory/harness — references ディレクトリ
  • revfactory/harness-100 — 100 事例集
  • revfactory/claude-code-harness — A/B テスト実験リポジトリ
• 記事
  • deepwiki: revfactory/harness
  • Harness Engineering for Coding Agent Users — Martin Fowler
  • Inside Claude Code Skills: Structure, prompts, invocation
  • SkillsLLM — harness