claude ハーネス設計の実務ガイド｜評価軸・データセット・自動採点

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

「Claude APIで業務AIを作ったが、本番投入後の品質劣化を検知できない」「評価ハーネスは組んだものの、スコアが何を意味しているのか説明できない」「データセットを毎回手作りしていて運用が回らない」——2025年後半からClaudeを使った業務エージェントの実装案件が急増し、2026年に入ってからはclaude ハーネス設計に関する相談が、技術部にほぼ毎週のように寄せられています。本記事では、claude ハーネス設計を業務に耐える品質で組むための実務指針を、評価軸定義・データセット設計・スコアリング自動化の3観点で、実装コード付きで整理します。

• TL;DR

• claude ハーネス設計の出発点は「評価軸を3〜5個に絞り、各軸を独立採点する」こと。総合スコア一発採点は精度が30%以上落ちる

• データセットは「正常系60% / 境界系25% / 異常系15%」の比率が2026年時点の業務AI向け黄金比

• スコアリングはJSON Schema強制 + 評価モデル分離 + 人間レビュー10%サンプリングの3点セットで再現性が担保される

• CI連携はGitHub Actions + Claude API + 閾値ゲートでPR単位の品質劣化を即検知できる

• 運用フェーズでは本番ログの5%を評価データに昇格させる「データフライホイール」が品質維持の鍵

なぜ今 claude ハーネス設計が業務AIの分水嶺なのか？

結論から言うと、2026年の業務AIは「動くかどうか」ではなく「劣化を検知できるかどうか」で勝敗が決まるからです。Anthropicが2025年末に公開した運用ガイドラインでも、本番Claude APIの品質劣化の約7割が「プロンプト変更」「モデルバージョン更新」「上流データ変化」の3要因に起因すると報告されています。ハーネスがなければ、これらの劣化は本番障害として顕在化するまで気づけません。

Gartnerが2026年初頭に発表したAI運用レポートによれば、生成AIシステムを本番運用する企業のうち、評価ハーネスを継続運用できているのは全体の23%に過ぎず、77%は「初期に作ったが運用できなくなった」と回答しています。

つまり、ハーネスは「作ること」より「運用し続けられる設計にすること」のほうが圧倒的に難しい。本記事はその設計指針に的を絞ります。前提知識としてはハーネスエンジニアリングとは？LLM時代に必須の新常識もあわせて参照してください。

ハーネスが機能しない典型3パターン

評価軸はどう定義する？業務AIで使える5分類

結論として、業務AI向けの評価軸は「正確性・完全性・形式遵守・安全性・効率性」の5分類に整理するのが2026年時点のベストプラクティスです。これ以上増やすと採点の一貫性が崩れ、これ以下に削ると改善ループが回りません。

5評価軸の定義と採点基準

重要なのは「各軸を独立して採点し、合算は後段で重み付けする」こと。1つのプロンプトで5軸まとめて採点させると、Claudeでも軸間の影響で精度が落ちます。Sonnet/Opus評価精度比較記事で検証した通り、軸ごとにプロンプトを分離するだけで一致率が15〜20ポイント向上します。

評価軸定義のサンプルコード

EVAL_AXES = {
    "accuracy": {
        "model": "claude-opus-4-5",
        "prompt_template": "accuracy_v3.md",
        "output_schema": {"score": "int (0 or 1)", "reason": "str"},
        "weight": 0.35,
    },
    "completeness": {
        "model": "claude-sonnet-4-5",
        "prompt_template": "completeness_v2.md",
        "output_schema": {"score": "float", "missing": "list[str]"},
        "weight": 0.25,
    },
    "format": {
        "model": None,  # 構文チェックのみ、LLM不要
        "validator": "jsonschema",
        "weight": 0.15,
    },
    "safety": {
        "model": "claude-opus-4-5",
        "prompt_template": "safety_v4.md",
        "weight": 0.15,
    },
    "efficiency": {
        "model": None,
        "metric": "tokens_per_task",
        "weight": 0.10,
    },
}

形式遵守と効率性はLLMを使わずに決定的判定で済ませるのがコストカットの定石です。LLM-as-a-Judgeは正確性・完全性・安全性の3軸に絞り、残りはコード判定に倒します。

データセットはどう設計する？分布と更新が品質を決める

結論として、データセットは「正常系60% / 境界系25% / 異常系15%」の比率を初期に守り、運用後は本番ログの5%を継続注入するのが安定運用の型です。多くの現場はここを軽視して「Slackから30件かき集めて終わり」にしますが、それでは2週間で精度が崩れます。

3カテゴリのデータセット内訳

• 正常系 (Happy Path): 業務で最も頻出する典型ケース。期待出力が明確で、回帰テストの土台になる

• 境界系 (Edge Case): 入力長の限界、曖昧な指示、複数解釈可能なケース。モデル更新時に最初に崩れる領域

• 異常系 (Adversarial): プロンプトインジェクション、機密情報誘導、矛盾指示。安全性軸の主戦場

データセットの最小構造

{
  "id": "case_0142",
  "category": "edge",
  "input": {
    "user_message": "今期の売上を昨対比で出して",
    "context": {"fiscal_year": "2026Q1"}
  },
  "expected": {
    "required_fields": ["current", "previous", "yoy_rate"],
    "forbidden_phrases": ["おそらく", "たぶん"],
    "reference_answer": "..."
  },
  "metadata": {
    "created_at": "2026-04-12",
    "source": "production_log",
    "reviewer": "tanaka"
  }
}

ポイントは「期待出力」を完全一致ではなく「必須フィールド・禁止フレーズ・参照解答」の3点で定義すること。LLMの出力は自然言語ゆらぎがあるため、文字列完全一致での採点は破綻します。環境構築ガイドでデータ管理基盤の構築方法も詳述しています。

本番ログからの昇格フロー

graph LR
    A[本番ログ] --> B{サンプリング5%}
    B --> C[匿名化処理]
    C --> D[人間レビュー]
    D --> E{昇格判定}
    E -->|Yes| F[評価データセット]
    E -->|No| G[アーカイブ]
    F --> H[次回CI評価]

スコアリング自動化はどう組む？CI連携と閾値ゲート

結論として、スコアリング自動化はGitHub ActionsでPR単位に走らせ、軸ごとの閾値を下回ったらマージブロックするのが2026年5月時点の標準パターンです。

CIワークフローの最小実装

name: claude-harness-eval
on:
  pull_request:
    paths:
      - 'prompts/**'
      - 'src/agents/**'

jobs:
  evaluate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run harness
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          python -m harness.run \
            --dataset datasets/regression_v12.jsonl \
            --output reports/pr_${{ github.event.number }}.json
      - name: Threshold gate
        run: |
          python -m harness.gate \
            --report reports/pr_${{ github.event.number }}.json \
            --threshold accuracy=0.92 completeness=0.85 safety=1.0
      - name: Post comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('reports/summary.json'));
            // PRコメントに軸別スコアを投稿

閾値設計の考え方

安全性と形式遵守は1件でも違反したら即ブロックが鉄則です。これらは「平均で見てはいけない指標」であり、外れ値1件が本番事故に直結します。ガードレール設計記事と組み合わせて二重の防御線を引くのが推奨構成です。

雲海設計の現場ではどう運用しているか？

当社が2025年から2026年にかけて構築した業務エージェント案件では、上記の設計をベースに以下の運用フローを標準化しています。

1. 初期構築フェーズ (2〜3週間): 評価軸定義 + 初期データセット150件 (正常90/境界40/異常20) を作成

2. PoCフェーズ (1ヶ月): CIにハーネス組み込み、PR単位で自動評価を回す

3. 本番フェーズ (継続): 本番ログの5%サンプリング、週次で評価データに昇格

4. 四半期レビュー: モデル更新・プロンプト棚卸し・閾値再校正

このフローを愚直に回している案件は、本番投入後12ヶ月時点でも初期品質を維持できています。逆に「初期にハーネスを作って満足した」案件は、3ヶ月で品質指標が15〜25%劣化しているのが実測値です。AI業務導入の設計支援はDXソリューション、技術選定の伴走はITコンサルティングで対応しています。

よくある質問

Q. ハーネス構築はどれくらいの工数を見込むべきですか？

A. 評価軸5個・データセット150件・CI連携までで、エンジニア1名×3週間が目安です。データセット作成が全体工数の約6割を占めるため、業務担当者の協力体制を初期に確保することが成否を分けます。

Q. 評価モデルにはSonnetとOpusのどちらを使うべきですか？

A. 軸ごとに分離します。安全性・正確性などの重要軸はOpus、完全性などの量的判定はSonnetが2026年5月時点のコスパ最適解です。詳細はSonnet/Opus評価精度比較記事を参照してください。

Q. データセットが社内に存在しない場合はどう作りますか？

A. 業務担当者へのヒアリングで「過去3ヶ月の代表ケース30件」をまず集め、そこからClaudeで派生ケースを生成して150件まで膨らませる手法が現実的です。生成データには必ず人間レビューを通します。

Q. ハーネスのスコアが急に下がった場合、まず何を疑いますか？

A. 順番に、(1) モデルバージョン更新、(2) プロンプト変更、(3) 上流データ分布変化、(4) 評価データセット側のドリフトを確認します。CIのGit履歴とAnthropic側のリリースノートを突き合わせれば、ほとんどの劣化は1日以内に原因特定できます。

Q. 中小企業でもこの設計は現実的ですか？

A. 現実的です。むしろリソースが限られる中小企業ほど、品質劣化を早期検知できるハーネスのROIは高くなります。当社では3名規模の開発チームでも回せる軽量版テンプレートを用意しています。

まとめ：claude ハーネス設計は「運用し続けられる型」が9割

claude ハーネス設計の本質は、立派な評価システムを作ることではなく、「半年後も運用が続いている設計にすること」です。評価軸を5つに絞り、データセットの比率を守り、CIで閾値ゲートを敷く——この3点を地味に続けられるかどうかが、本番AIの寿命を決めます。

「自社のClaude実装にハーネスを組み込みたい」「既存ハーネスが運用できなくなっている」というご相談は、お問い合わせフォームからお気軽にお寄せください。設計から運用伴走まで、技術部が現場目線でサポートします。