ハーネスエンジニアリング Claude Codeで実装する評価ループ構築完全ガイド

こんにちは！株式会社雲海設計の技術部です。

「Claude Codeでエージェントを組んだものの、品質が安定しない」「評価をスプレッドシートで手動採点していて、改善サイクルが回らない」「サブエージェントとhookの使い分けが曖昧で、ハーネスが膨れ上がっている」——2025年に生成AIエージェントの実装案件が一気に増えた結果、2026年に入ってからハーネスエンジニアリング Claude Codeでの実装相談がほぼ毎週のように入ってきます。本記事では、ハーネスエンジニアリング Claude Codeの実装手順を、サブエージェント・hook・カスタムコマンドという3つの仕組みを使った評価ループ構築の観点で、現場目線で整理します。

• TL;DR

• ハーネスエンジニアリングとは「LLMを業務に耐える形で繋ぎ込み、評価し続ける足回りの設計」であり、Claude Codeはこの実装に最適化された数少ない環境

• Claude Codeでハーネスを組む3点セットはサブエージェント（評価役）・hook（自動検証）・カスタムコマンド（ループ起動）

• 評価ループは「実行 → 自動採点 → 失敗ケース蓄積 → プロンプト改修 → 再評価」の5段で回す。手動採点では2026年のスピードに追いつかない

• サブエージェントは本番エージェントとは別人格の「批評者」として配置すると、自己採点バイアスを避けられる

• hookでPreToolUse / PostToolUse / Stopに検証を差し込むと、コード変更や危険操作の事故を未然に止められる

そもそもハーネスエンジニアリングとは何か？

結論から言うと、ハーネスエンジニアリングとは「LLM単体ではなく、LLMを業務に耐える形で繋ぎ込み、評価・改善し続けるための足回り全体を設計する技術」です。プロンプトエンジニアリングが「文の中身」を磨く技術だとすれば、ハーネスエンジニアリングは「文を流す配管・計測器・安全弁」を組む技術と言えます。

Anthropicが2025年後半に公開したエンジニアリングブログでも、本番品質のエージェントには「モデルそのものよりも、評価ハーネスの設計が成果を決める」と明言されています。

2026年にClaude Codeが選ばれる理由

Claude Codeは単なるAIコーディング支援ツールではなく、サブエージェント・hook・カスタムコマンド・MCPという4つの拡張機構を標準で備えており、これらを組み合わせることでハーネスをそのままリポジトリ内に同梱できます。CursorやDevinが「コードを書く」ことに最適化されているのに対し、Claude Codeは「コードを書きながら評価ループを回す」ことに向いています。詳しくはAIコーディングエージェント選定ガイドでも比較していますので、選定段階の方は併読してください。

Claude Codeでハーネスを組む3点セットの役割分担は？

結論、サブエージェント＝評価役、hook＝自動検証ゲート、カスタムコマンド＝ループ起動装置として役割を分けるのが鉄則です。混ぜると保守できなくなります。

役割分離の原則

• 本番エージェントと評価エージェントは必ず別ファイル：自己採点は3割甘くなる

• hookには「判定ロジック」だけを置き、業務処理は書かない：hookが肥大化すると本番影響が読めなくなる

• カスタムコマンドは「動詞＋対象」で命名：/eval-rag、/regen-fixtures など、何を起動するか一目で分かる粒度

評価ループの5段階はどう回す？

結論、評価ループは「①実行 → ②自動採点 → ③失敗ケース蓄積 → ④プロンプト/コード改修 → ⑤再評価」の5段で回します。手動採点をスプレッドシートで運用していると、2026年のモデル更新ペースに追いつけません。

graph LR
  A[評価データセット] --> B[本番エージェント実行]
  B --> C[サブエージェント採点]
  C --> D{合格?}
  D -->|No| E[失敗ケース蓄積]
  E --> F[プロンプト改修]
  F --> B
  D -->|Yes| G[リグレッション保存]

ステップ別の実装ポイント

1. 評価データセットは最低30件、敵対的15件・境界15件・ハッピーパス20件から始める

2. 採点はサブエージェントにJSONで返させる：{score, reason, failure_category} の3フィールド固定

3. 失敗ケースはfixturesディレクトリにそのまま追記：再現性が命

4. 改修はGit commit単位で評価スコアと紐づける：どの変更が効いたか後から辿れる

5. 再評価はカスタムコマンド一発で起動：/eval-all で全件回るようにしておく

評価設計の詳細な考え方はハーネスエンジニアリング ベストプラクティスでも掘り下げています。

サブエージェントで評価役をどう実装するか？

結論、サブエージェントは「批評者」「再現性チェッカー」「セキュリティ監査者」の3役を最低構成として配置します。

批評者エージェントの定義例

---
name: critic
description: 本番エージェントの出力を業務要件に照らして採点する
tools: Read, Grep
---

あなたは厳格なコードレビュアーです。
本番エージェントの出力を以下の観点で採点してください。

# 評価観点
1. 要件充足度 (0-5)
2. エラーハンドリングの妥当性 (0-5)
3. テスト可能性 (0-5)

# 出力形式
必ず以下のJSONで返却:
{
  "score": number,
  "reason": string,
  "failure_category": "requirement"|"error"|"testability"|"none"
}

採点が甘くなりがちなので、迷ったら必ず低い点を付けてください。

サブエージェント設計の3原則

• tools を最小権限に：批評者にWriteは不要、Read/Grepのみ

• 出力形式をJSON固定：自由記述させると後段の集計が壊れる

• 「迷ったら低い点」と明示：Anthropic自身がモデルは楽観バイアスを持つと公表している

hookで自動検証ゲートをどう仕込むか？

結論、hookはPreToolUse（実行前）・PostToolUse（実行後）・Stop（終了時）の3ポイントに、目的を絞って配置します。

典型的なhook配置パターン

settings.jsonの設定例

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/guard-dangerous.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npm run lint && npm run typecheck"
      }]
    }]
  }
}

hookは強力ですが、本番DBの破壊的操作を遮断する設計はアプリ層・権限層との二重化が前提です。詳しくはAIセキュリティ対策実装ガイド2026を併読してください。

カスタムコマンドで評価ループをどう起動するか？

結論、カスタムコマンドは「定型作業の動詞化」で運用します。/eval-all、/regen-fixtures、/diff-scoreの3つがあれば最低限ループが回ります。

/eval-all コマンドの定義例

---
description: 評価データセット全件に対して本番エージェントを走らせ、criticエージェントで採点する
argument-hint: [dataset-path]
allowed-tools: Bash, Read, Write
---

以下を順番に実行してください:

1. {{argument}} 配下のJSONLを読み込む
2. 各ケースについて本番エージェント（agents/main.md）を起動
3. 出力をcriticサブエージェントに渡して採点
4. results/{timestamp}.csv に score, reason, failure_category を保存
5. 平均スコアと失敗カテゴリ別件数を標準出力に表示

運用上の注意

• コマンド数は10個以内に抑える：増やすほど誰も使わなくなる

• argument-hint を必ず書く：チームメンバーが補完候補で意味を理解できる

• CIから叩けるよう headless モード対応：claude -p "/eval-all ..." で夜間自動実行

本番投入前のチェックリスト

ハーネスを組んだら、本番投入前に以下を必ず確認します。1つでも欠けると、3ヶ月後に必ず事故が起きます。

• ☐ 評価データセットが30件以上あり、敵対的・境界・ハッピーパスの3種を含む

• ☐ サブエージェントの採点結果がJSONで構造化保存されている

• ☐ PreToolUse hookで破壊的操作が遮断されることをテスト済み

• ☐ PostToolUse hookでlint/typecheck/testが自動実行される

• ☐ /eval-all がCI上で完走する

• ☐ 評価スコアの推移がGitコミットと紐づいている

• ☐ サブエージェントのtoolsが最小権限になっている

• ☐ プロンプト全文・ツール呼び出し・最終出力が監査ログとして保存される

よくある質問

Q. プロンプトエンジニアリングだけでは不十分なのでしょうか？

A. 不十分です。プロンプトは「文の中身」を磨く技術ですが、業務利用ではモデル更新・データ変化・利用者の悪意ある入力に継続的に耐える必要があり、評価ループ＝ハーネスがないとプロンプト改修の効果すら測れません。プロンプト設計の記事と本記事をセットで読むと全体像が掴めます。

Q. Claude Code以外でも同じことはできますか？

A. 可能ですが、サブエージェント・hook・カスタムコマンドが標準機構として揃っているのは2026年5月時点でClaude Codeが頭一つ抜けています。CursorやDevinでも自前で評価スクリプトを組めばハーネスは作れますが、「リポジトリにそのまま同梱して再現性を確保する」という観点ではClaude Codeが最短です。

Q. 小規模チームでも導入できますか？

A. できます。むしろ小規模ほど効果が出ます。最初はサブエージェント1つ＋PostToolUse hook 1つ＋/eval-all コマンド1つの最小構成で十分です。評価データセットも30件あれば回り始めます。

Q. 評価データセットはどう作ればいいですか？

A. 過去のバグ報告・問い合わせログ・敵対的入力の3ソースから集めます。「実際に現場で起きた失敗ケース」を再現性のあるfixtureに落とすのが最優先です。新規モデルへの切り替え時にも同じデータセットでリグレッションが取れます。

Q. 導入支援は受けられますか？

A. はい。雲海設計ではDXソリューションおよびITコンサルティングとして、Claude Codeを中核に据えたハーネス設計・評価ループ構築の伴走支援を提供しています。

まとめ：ハーネスは「あとから足す」では遅い

2026年の現場では、AIエージェントの品質を決めるのはモデルではなくハーネスです。Claude Codeのサブエージェント・hook・カスタムコマンドを組み合わせれば、評価ループはリポジトリに同梱できる開発資産になります。逆に、ハーネスを後回しにしたプロジェクトは、3ヶ月後に「動いているけど直せない」状態に陥ります。

「自社のエージェント実装にハーネスを後付けしたい」「Claude Codeを評価ループ込みで導入したい」という方は、ぜひお問い合わせください。雲海設計の技術部が現状のリポジトリ構成を踏まえた上で、最小構成のハーネス導入から伴走します。