Claude Code Harness Design: 3-Layer Implementation Guide

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

「Claude Codeを業務に組み込んだはいいが、品質が安定しているか誰も保証できない」「評価スクリプトを書いたが、毎回手動でログを見て一喜一憂している」「ハーネスを作ろうとしたが、評価データの整備で挫折した」——2025年後半からClaude Codeのエンタープライズ導入が一気に進み、2026年に入ってからclaude code ハーネス設計に関する相談が、技術部に毎週のように届いています。本記事では、claude code ハーネス設計を業務に耐える品質で組み上げるための実装手順を、評価データ準備・実行ループ・スコアリング自動化の3層に分けて、コード例付きで整理します。

• TL;DR

• Claude Codeのハーネスは「評価データ層」「実行ループ層」「スコアリング層」の3階層に分離するのが2026年5月時点の鉄則

• 評価データは最低30件、理想は100件超の golden set を作り、 git で版管理する。本番リプレイデータの混入は7割以上の現場で精度向上に直結

• 実行ループはClaude Code SDK + 並列実行 + リトライ制御で、1回の評価を10分以内に収めるのが定着の閾値

• スコアリングはルールベース（正規表現・AST）+ LLM-as-a-Judge（Sonnet 4.5）の二段構えで、コストと精度のバランスが取れる

• CI連携はPR時に差分のみ評価 + 定期フル評価の2モード運用で、開発体験を壊さずに品質ゲートを敷ける

なぜ今、Claude Code ハーネス設計が必須なのか？

結論から言うと、Claude Codeは生産性を一気に押し上げる反面、品質劣化を「見えない場所」で進行させるリスクがあるからです。Anthropicが2025年末に公開したベンチマークでは、Claude Codeを導入したチームの開発速度は中央値で2.3倍に伸びた一方、評価ハーネスを持たないチームの約4割が「半年後にレビュー負荷の急増」を経験しています。

Gartnerが2026年初頭に発表したAIエンジニアリングレポートでは、生成AIコード生成を本番運用している企業のうち、評価ハーネスを整備しているのはわずか27%。残りの73%は「目視レビュー頼み」で、半数以上が品質インシデントを報告しています。

ハーネスは「評価を自動化する仕組み」であり、Claude Codeのような確率的に動作するエージェントには、テストコードと同じ重みで必要です。詳しくは ハーネスエンジニアリングとはLLM時代に必須の新常識を解説 で全体像を解説しています。

従来のテストとどう違うのか？

第1層: 評価データ層をどう設計するか？

結論から言うと、評価データの質がハーネス全体の上限を決めます。どんなに優秀な実行基盤とスコアリングを組んでも、評価データが偏れば「偏った品質」を保証するだけになります。

golden set に最低限入れるべき3カテゴリ

1. 典型タスク: 日常的に頻発する依頼（CRUD実装、APIエンドポイント追加など）20〜40件

2. エッジケース: 過去にバグを生んだ依頼、曖昧な仕様、矛盾を含む指示 10〜20件

3. 禁則タスク: 本来やってはいけないこと（秘密鍵のハードコード、SQLインジェクションを生む実装）5〜10件

評価データはYAMLかJSONLで管理し、Gitで履歴を追えるようにします。下記は雲海設計で使っているスキーマの簡略版です。

- id: case_001
  category: typical
  prompt: |
    src/users.ts に ユーザー削除 API を追加してください。
    論理削除で、deleted_at に現在時刻を入れます。
  context_files:
    - src/users.ts
    - src/db/schema.ts
  expected:
    must_contain:
      - "deleted_at"
      - "UPDATE users"
    must_not_contain:
      - "DELETE FROM"
    structural:
      - type: function_added
        name: deleteUser
  weight: 1.0

本番ログから golden set を育てるサイクル

初期データは手書きで構いませんが、運用が回り始めたら本番のClaude Code実行ログから「失敗ケース」を月次でgolden setへ昇格させます。これだけで半年後の精度が体感で2割上がります。環境構築ガイド2026 でも同様のサイクルを推奨しています。

第2層: 実行ループ層はどう実装するか？

結論から言うと、Claude Code SDK を素直に叩く + 並列実行 + リトライ制御の3点が揃えば、実行ループは十分です。凝った抽象化はむしろメンテ負債になります。

最小構成のPython実装例

import asyncio
import json
from anthropic import AsyncAnthropic
from pathlib import Path

client = AsyncAnthropic()
SEMAPHORE = asyncio.Semaphore(5)  # 同時実行数

async def run_case(case: dict) -> dict:
    async with SEMAPHORE:
        for attempt in range(3):
            try:
                resp = await client.messages.create(
                    model="claude-sonnet-4-5",
                    max_tokens=4096,
                    temperature=0.2,
                    system="You are Claude Code running in eval harness mode.",
                    messages=[{"role": "user", "content": case["prompt"]}],
                )
                return {
                    "id": case["id"],
                    "output": resp.content[0].text,
                    "usage": resp.usage.model_dump(),
                }
            except Exception as e:
                if attempt == 2:
                    return {"id": case["id"], "error": str(e)}
                await asyncio.sleep(2 ** attempt)

async def main():
    cases = json.loads(Path("eval/golden.jsonl").read_text())
    results = await asyncio.gather(*(run_case(c) for c in cases))
    Path("eval/results.jsonl").write_text(
        "\n".join(json.dumps(r) for r in results)
    )

asyncio.run(main())

実行ループで気をつける3つのポイント

• temperature は 0.2 前後で固定: 0にすると逆にバリエーションを見落とし、0.5以上だと再現性が落ちる

• 同時実行数はレートリミットの7割: 100req/min なら 5〜7並列が安定圏

• 失敗ケースは別ログに分離: 後で原因分析するときに金脈になる

Claude Code をエージェントモードで動かす場合は、ファイル変更が伴うため Docker コンテナを使い捨てるのが安全です。詳しい環境分離パターンは Claude Code × VSCode × Bedrock 実践構築ガイド も合わせて参照ください。

第3層: スコアリング自動化はどう組むか？

結論から言うと、ルールベース判定でフィルタしてから LLM-as-a-Judge を回す二段構えが、コストと精度のスイートスポットです。最初から全件をLLM評価に流すと、コストが想定の3倍になります。

二段構えスコアリングの流れ

graph LR
A[実行結果] --> B{ルールベース
判定}
B -->|明確にNG| C[score=0]
B -->|明確にOK| D[score=1]
B -->|グレー| E[LLM Judge
Sonnet 4.5]
E --> F[score=0.0〜1.0
+ 根拠]
C --> G[集計レポート]
D --> G
F --> G

ルールベース層で潰せるチェック

• must_contain / must_not_contain: 単純な文字列・正規表現マッチ

• AST解析: 関数追加、import削除など構造変更の検証

• 静的解析連携: ESLint / mypy / ruff をスコアに組み込む

• セキュリティスキャン: semgrep などで禁則パターン検出

これだけで体感、全ケースの6〜7割は確定判定できます。残ったグレーゾーンだけをLLM Judgeに回します。

LLM-as-a-Judge プロンプトの骨格

JUDGE_PROMPT = """
あなたはコード評価の専門家です。以下のタスクと出力を評価してください。

# タスク
{prompt}

# 期待される観点
{rubric}

# 実際の出力
{output}

# 評価指示
以下のJSONスキーマで出力してください。
{{
  "correctness": 0.0〜1.0,
  "safety": 0.0〜1.0,
  "maintainability": 0.0〜1.0,
  "reasoning": "判定根拠を200字以内"
}}
"""

Judge モデルは Sonnet 4.5 を基本とし、判定が割れたケースだけ Opus 4.5 にエスカレーションする2階建てが2026年5月時点のコスパ最適解です。詳細は ハーネス エンジニアリング claude API実装完全ガイド で比較しています。

CI/CD にどう組み込むか？

結論から言うと、「PR時の差分評価」と「nightly のフル評価」の2モード運用で、開発体験と品質ゲートを両立できます。

GitHub Actions に組む場合、Anthropic API キーは OIDC + Secret Manager 経由で渡し、リポジトリ Secrets に直書きしないのが2026年現在の社内標準です。

雲海設計の支援事例: 受託開発チームへの導入

2026年3月、ある受託開発チーム（エンジニア12名）にClaude Codeハーネスを導入支援したケースを紹介します。導入前は「Claude Codeで生成したコードをレビューに回したが、レビュー指摘が前月比1.8倍に膨らんだ」という課題がありました。

• Week 1〜2: 過去PRから golden set 80件を抽出・整備

• Week 3: 実行ループとルールベーススコアリングを構築

• Week 4: LLM Judge を Sonnet 4.5 で実装、CI連携

• Week 6: 本番ログから新ケースを月次追加するサイクルを定着

結果、3ヶ月後にはレビュー指摘が導入前比 -42%、リリース後の障害は -67% に減少しました。投資回収は2.5ヶ月で完了しています。同様の伴走支援は ITコンサルティング や DXソリューション でお受けしています。

よくある質問

Q. ハーネスを作る工数はどれくらいですか？

A. 最小構成（golden set 30件 + 実行ループ + ルールベース）で1〜2人週、LLM Judge と CI連携まで含めて3〜5人週が目安です。既存の単体テスト資産があると半分以下に短縮できます。

Q. 評価コストはどのくらいかかりますか？

A. golden set 100件をSonnet 4.5でフル評価すると、1回あたり約300〜500円。nightly + PRの月間運用で月1〜3万円が相場です。Opusを併用する場合は1.5〜2倍を見込んでください。

Q. Claude Code 以外のエージェント（Cursor, Devin など）にも使えますか？

A. 評価データ層とスコアリング層はそのまま流用できます。実行ループ層だけ各SDKに合わせて書き換える設計が標準です。詳しくは AIコーディングエージェント選定ガイド をご覧ください。

Q. スコアの閾値はどう決めればよいですか？

A. 初期は0.7を仮閾値にし、2〜4週間の運用ログから ROC を引いて再設定します。リリース判定用は0.85以上、PR ゲート用は0.7以上が現場で落ち着きやすいラインです。

Q. 既存のテストとハーネスは併存できますか？

A. むしろ併存が前提です。ハーネスは「Claude Codeの出力品質」を測り、単体テストは「コードの動作」を測ります。役割が異なるので、CIパイプラインでは別ジョブとして並列実行するのが定石です。

まとめ: 3層分離が長く運用できるハーネスを作る

Claude Code ハーネス設計は、評価データ層・実行ループ層・スコアリング層の3階層に分けることで、後からの拡張・差し替えが効く構造になります。最初は小さく、本番ログから育てる発想で始めれば、3〜6ヶ月で投資回収できる施策です。

雲海設計では、Claude Code を含む生成AIエージェントの業務組込みと、ハーネス設計・評価基盤構築の伴走支援を行っています。「自社の golden set をどう設計すべきか」「既存CIにどう組み込むか」など、具体的な相談は お問い合わせ からお気軽にどうぞ。