【Claude Code】Harness最適化完全ガイド — AIコーディングエージェントの性能を7軸で引き上げる

Posted at 2026-03-29

はじめに

Claude Code をはじめとするAIコーディングエージェントの出力品質を決めるのは、プロダクトコードではなく、エージェントを取り巻く「Harness（ハーネス）」の構成です。

Harness とは、エージェントが動作する環境全体 — Skills、Hooks、Commands、Agents、Rules、MCP設定 — を指します。これらを体系的に最適化することで、コード品質・コスト・セキュリティ・信頼性を大幅に向上させることができます。

本記事では、GitHub で 60,000+ Stars を獲得した OSS プロジェクト everything-claude-code（ECC） が提唱する Harness Audit の 7 カテゴリに沿って、具体的な最適化手法を解説します。

本記事は ECC v1.9.0（2026年3月時点）の公開情報に基づいています。

Harness とは何か？
Harness Audit — 7カテゴリ評価フレームワーク
Category 1: Tool Coverage（ツール網羅性）
Category 2: Context Efficiency（コンテキスト効率）
Category 3: Quality Gates（品質ゲート）
Category 4: Memory Persistence（メモリ永続化）
Category 5: Eval Coverage（評価カバレッジ）
Category 6: Security Guardrails（セキュリティガードレール）
Category 7: Cost Efficiency（コスト効率）
Hooks 設計パターン
Harness Optimizer — 自動最適化エージェント
実践：自分のプロジェクトで始める
まとめ

Harness とは何か？

AIコーディングエージェント（Claude Code, Cursor, Codex, OpenCode など）を動かすとき、プロンプトやコードだけでなく、周辺環境全体が出力品質に影響します。この周辺環境を「Harness（ハーネス）」と呼びます。

Harness構成	要素1	要素2	要素3
上位レイヤー	Skills ワークフロー	Hooks 自動化	Commands /コマンド
中位レイヤー	Agents サブエージェント	Rules ルール	MCP 外部接続
中心	AI Agent (Claude) プロダクトコード生成

Harness 最適化の哲学は明確です。

「エージェントの完了品質を向上させるには、プロダクトコードではなくHarness設定を改善する」
— harness-optimizer agent

Harness Audit — 7カテゴリ評価フレームワーク

ECC は Harness の品質を 7つのカテゴリ で 決定論的に（再現可能に） 評価するスクリプト harness-audit.js を提供しています。各カテゴリは 0〜10 のスコアに正規化され、合計 70 点満点で採点されます。

# Harness Audit の実行
node scripts/harness-audit.js           # 全体評価（テキスト出力）
node scripts/harness-audit.js --format json  # JSON 出力（CI/CD 統合用）
node scripts/harness-audit.js hooks     # Hooks のみ評価

7カテゴリ一覧

#	カテゴリ	評価対象	配点
1	Tool Coverage	Hooks、Agents、Skills、Commands の数と整合性	10pt
2	Context Efficiency	コンテキストウィンドウの効率的な利用	10pt
3	Quality Gates	テスト・検証パイプラインの充実度	10pt
4	Memory Persistence	セッション間のメモリ永続化	10pt
5	Eval Coverage	評価フレームワークの整備度	10pt
6	Security Guardrails	セキュリティチェック機構	10pt
7	Cost Efficiency	コスト最適化の仕組み	10pt

出力例

Harness Audit (repo): 66/70

- Tool Coverage:       10/10 (10/10 pts)
- Context Efficiency:   9/10 ( 9/10 pts)
- Quality Gates:       10/10 (10/10 pts)
- Memory Persistence:  10/10 (10/10 pts)
- Eval Coverage:       10/10 (10/10 pts)
- Security Guardrails:  9/10 ( 9/10 pts)
- Cost Efficiency:      8/10 ( 8/10 pts)

Top 3 Actions:
1) [Security Guardrails] Add prompt/tool preflight security guards ...
2) [Tool Coverage] Sync harness-audit.md across platforms ...
3) [Eval Coverage] Increase test coverage across scripts/ ...

Category 1: Tool Coverage（ツール網羅性）

概要

エージェントが利用できるツール群（Hooks、Agents、Skills、Commands）が十分に揃っているかを評価します。

チェック項目

チェック	基準	配点
Hook設定ファイルの存在	`hooks/hooks.json` が存在する	2pt
Hook実装スクリプト数	`scripts/hooks/` に 8 個以上の `.js`	2pt
Agent定義数	`agents/` に 10 個以上の `.md`	2pt
Skill定義数	`skills/` に 20 個以上の `SKILL.md`	2pt
コマンドの整合性	プラットフォーム間でコマンド定義が一致	2pt

ECC が提供するツール群の規模

agents/    → 30 定義（言語レビュアー、ビルドリゾルバー、ワークフロー専門など）
skills/    → 135 定義（言語パターン、テスト戦略、AI/MLワークフローなど）
commands/  → 60 定義（/tdd, /plan, /code-review, /build-fix など）

実践ポイント

# Agent 定義の例（Markdown + YAML frontmatter 形式）
# agents/code-reviewer.md

---
name: code-reviewer
description: Quality and security review for code changes
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
---

You are the code reviewer.
Focus on: correctness, security, performance, maintainability.

Agent の設計原則：

スコープを限定する — 許可するツールを最小限に
適切なモデルを選択 — 探索系は haiku、コードレビューは opus、設計は opus
前提条件を明記 — Agent が何をすべきか明確に記述

Category 2: Context Efficiency（コンテキスト効率）

概要

200K トークンのコンテキストウィンドウをいかに効率的に利用するかを評価します。コンテキストの浪費は、応答品質の低下とコスト増加の両方を招きます。

チェック項目

チェック	基準	配点
戦略的コンパクション	`skills/strategic-compact/SKILL.md` の存在	3pt
コンパクション提案Hook	`scripts/hooks/suggest-compact.js` の存在	3pt
モデルルーティングコマンド	`commands/model-route.md` の存在	2pt
トークン最適化ドキュメント	`docs/token-optimization.md` の存在	2pt

推奨設定

~/.claude/settings.json に以下を追加します：

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

設定	デフォルト	推奨値	効果
`model`	opus	sonnet	日常タスクの ~80% をカバー。コスト ~60% 削減
`MAX_THINKING_TOKENS`	31,999	10,000	内部推論トークンを制限。隠れコスト ~70% 削減
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	95	50	自動コンパクションの閾値。95% では手遅れ
`CLAUDE_CODE_SUBAGENT_MODEL`	(継承)	haiku	サブエージェントを安価なモデルで実行

戦略的コンパクション

自動コンパクション（デフォルト95%）に頼ると、タスクの途中で重要なコンテキストが失われるリスクがあります。代わりに、論理的な区切りで手動 /compact を実行する戦略が推奨されます。

コンパクションの判断ガイド：

フェーズ遷移	コンパクト？	理由
調査 → 計画	✅ する	調査コンテキストは嵩張る。計画が蒸留結果
計画 → 実装	✅ する	計画はファイルに記録済み。コンテキストを解放
実装 → テスト	⚠️ 場合による	テストが直近コードを参照するなら保持
デバッグ → 次機能	✅ する	デバッグトレースが次の作業を汚染
実装の途中	❌ しない	変数名・ファイルパス・部分状態を失うコストが高い

MCP サーバーの管理

⚠️ MCP サーバーは「有効化するだけ」でコンテキストを消費する

200K コンテキストウィンドウが、MCP ツール定義だけで 70K に縮小する場合がある

推奨ルール:
  • 設定には 20-30 個の MCP を登録してよい
  • 同時に有効化するのは 10 個以下 / アクティブツール 80 個以下
  • 使わない MCP は disabledMcpServers で無効化
  • CLI ツールで代替可能なら MCP よりCLI を使う（gh > GitHub MCP）

Category 3: Quality Gates（品質ゲート）

概要

エージェントの出力を自動的に検証するパイプラインの充実度を評価します。

チェック項目

チェック	基準	配点
テストランナー	`tests/run-all.js` の存在	3pt
CI検証チェーン	`package.json` の test スクリプトにバリデーター含む	3pt
Hook テスト	`tests/hooks/hooks.test.js` の存在	2pt
Doctor スクリプト	`scripts/doctor.js` の存在	2pt

PostToolUse Hooks による自動品質チェック

ECC は、エージェントがファイルを編集するたびに自動的に品質チェックを実行する Hook を実装しています。

{
  "PostToolUse": [
    {
      "matcher": "Edit|Write|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "node scripts/hooks/quality-gate.js",
        "async": true,
        "timeout": 30
      }],
      "description": "ファイル編集後に品質ゲートチェックを実行"
    },
    {
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "node scripts/hooks/post-edit-format.js"
      }],
      "description": "JS/TS ファイル編集後に自動フォーマット（Biome/Prettier）"
    },
    {
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "node scripts/hooks/post-edit-typecheck.js"
      }],
      "description": ".ts/.tsx 編集後に TypeScript チェック"
    }
  ]
}

これにより、エージェントが壊れたコードをコミットするリスクを大幅に低減できます。

Category 4: Memory Persistence（メモリ永続化）

概要

セッション間で学習した知識やコンテキストを永続化する仕組みの有無を評価します。

チェック項目

チェック	基準	配点
メモリ永続化Hooksディレクトリ	`hooks/memory-persistence/` の存在	4pt
セッション開始/終了スクリプト	`session-start.js` と `session-end.js` の両方	4pt
継続学習スキル	`skills/continuous-learning-v2/SKILL.md` の存在	2pt

セッションライフサイクル

継続学習 v2

ECC の continuous-learning-v2 スキルは、セッション中のツール使用パターンをリアルタイムで観察し、終了時に学びを抽出する仕組みです。

{
  "PreToolUse": [{
    "matcher": "*",
    "hooks": [{
      "type": "command",
      "command": "bash skills/continuous-learning-v2/hooks/observe.sh",
      "async": true,
      "timeout": 10
    }],
    "description": "ツール使用を観察して継続学習データを蓄積"
  }]
}

コンパクション後も生き残るもの

永続化される	失われる
CLAUDE.md の指示	中間的な推論・分析
TodoWrite タスクリスト	過去に読んだファイル内容
メモリファイル (`~/.claude/memory/`)	複数ステップの会話コンテキスト
Git 状態（コミット、ブランチ）	ツール呼び出し履歴
ディスク上のファイル	口頭で伝えたユーザー好み

Category 5: Eval Coverage（評価カバレッジ）

概要

エージェントの出力を体系的に評価する Eval-Driven Development（EDD） の仕組みが整備されているかを評価します。

チェック項目

チェック	基準	配点
Eval Harness スキル	`skills/eval-harness/SKILL.md` の存在	4pt
Eval/検証コマンド	`eval.md`, `verify.md`, `checkpoint.md` の全存在	4pt
テストファイル数	`tests/` に 10 個以上の `.test.js`	2pt

Eval-Driven Development（EDD）

EDD は「Eval を AI 開発の Unit Test として扱う」思想です。

pass@k メトリクス

メトリクス	意味	推奨閾値
pass@1	1回目の試行で成功する確率	—
pass@3	3回の試行で少なくとも1回成功する確率	≥ 90%
pass^3	3回連続で全て成功する確率	= 100%（リリースクリティカル）

Grader（評価者）の種類

# 1. Code-Based Grader（決定論的）
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"

# 2. Model-Based Grader（LLM-as-Judge）
# Claude にコード品質を 1-5 で採点させる

# 3. Human Grader（人間レビュー）
# セキュリティ関連は必ず人間が最終確認

Eval アンチパターン

❌ 既知の Eval 例にプロンプトを過学習させる
❌ ハッピーパスの出力だけを計測する
❌ パス率を追いかけてコスト・レイテンシの劣化を無視する
❌ リリースゲートに不安定な Grader を使う

Category 6: Security Guardrails（セキュリティガードレール）

概要

エージェントが危険な操作を行うことを防ぐセキュリティ機構の充実度を評価します。

チェック項目

チェック	基準	配点
セキュリティレビュースキル	`skills/security-review/SKILL.md` の存在	3pt
セキュリティレビューAgent	`agents/security-reviewer.md` の存在	3pt
プロンプト/ツール事前検証Hook	hooks.json に `beforeSubmitPrompt` or `PreToolUse`	2pt
セキュリティスキャンコマンド	`commands/security-scan.md` の存在	2pt

PreToolUse セキュリティ Hooks

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "npx block-no-verify@1.1.2"
      }],
      "description": "git hook バイパスフラグ（--no-verify）をブロック"
    },
    {
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "node scripts/hooks/pre-bash-commit-quality.js"
      }],
      "description": "コミット前品質チェック: lint、コミットメッセージ形式、\nconsole.log/debugger/secrets の検出"
    },
    {
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "node scripts/hooks/config-protection.js",
        "timeout": 5
      }],
      "description": "Linter/Formatter 設定ファイルの変更をブロック\n→ 設定を弱めるのではなくコードを修正させる"
    }
  ]
}

多層防御の設計

レイヤー	構成要素	役割
Layer 1	PreToolUse Hooks	危険コマンドの事前ブロック、シークレット漏洩の検出、設定ファイル保護
Layer 2	Security Review Agent	脆弱性分析の自動委譲、セキュリティチェックリストの適用
Layer 3	Governance Capture	ポリシー違反の記録、承認リクエストのログ
Layer 4	Human Review	セキュリティ関連を最終判断

Category 7: Cost Efficiency（コスト効率）

概要

LLM API コストを意識した設計がされているかを評価します。

チェック項目

チェック	基準	配点
コスト意識スキル	`skills/cost-aware-llm-pipeline/SKILL.md` の存在	4pt
コスト最適化ドキュメント	`docs/token-optimization.md` の存在	3pt
モデルルーティングコマンド	`commands/model-route.md` の存在	3pt

モデルルーティング戦略

タスクの複雑さに応じて最適なモデルを自動選択します：

def select_model(text_length, item_count, force_model=None):
    """タスク複雑度に基づくモデル選択"""
    if force_model is not None:
        return force_model
    if text_length >= 10_000 or item_count >= 30:
        return "claude-sonnet-4-6"     # 複雑なタスク
    return "claude-haiku-4-5"          # 単純なタスク（3-4倍安い）

モデル別コスト比較

モデル	入力 ($/1M tokens)	出力 ($/1M tokens)	相対コスト	適用場面
Haiku 4.5	$0.80	$4.00	1x	サブエージェント探索、ファイル読み取り
Sonnet 4.6	$3.00	$15.00	~4x	日常コーディング、レビュー、テスト
Opus 4.5	$15.00	$75.00	~19x	複雑な設計、マルチステップ推論

コスト追跡 Hook

ECC は Stop イベントで自動的にトークン使用量とコストを記録します：

{
  "Stop": [{
    "matcher": "*",
    "hooks": [{
      "type": "command",
      "command": "node scripts/hooks/cost-tracker.js",
      "async": true,
      "timeout": 10
    }],
    "description": "セッションごとのトークンとコストメトリクスを追跡"
  }]
}

プロンプトキャッシュ

長いシステムプロンプトを毎回送り直すのではなく、キャッシュ制御を使ってコストとレイテンシを削減します：

messages = [{
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": system_prompt,
            "cache_control": {"type": "ephemeral"}  # ← これをキャッシュ
        },
        {
            "type": "text",
            "text": user_input  # 可変部分
        }
    ]
}]

Hooks 設計パターン

ECC の Hooks システムは、8 つのライフサイクルイベントにフックを設定できます。

ライフサイクルイベント一覧

イベント	タイミング	用途
SessionStart	セッション開始時	コンテキスト復元、環境検出
PreToolUse	ツール実行前	バリデーション、リマインダー、ブロック
PostToolUse	ツール実行後	フォーマット、品質チェック、フィードバック
UserPromptSubmit	ユーザープロンプト送信時	入力バリデーション、プロンプト加工
PreCompact	コンパクション前	状態保存
Stop	Claude 応答完了時	セッション保存、学習、コスト追跡
Notification	通知発生時	デスクトップ通知、外部連携
SessionEnd	セッション終了時	ライフサイクルマーカー

ECC の Hook 実装一覧（抜粋）

イベント	Hook	役割
PreToolUse (12 hooks)	block-no-verify	git hook バイパスをブロック
PreToolUse (12 hooks)	auto-tmux-dev	tmux で dev サーバー自動起動
PreToolUse (12 hooks)	tmux-reminder	長時間コマンドに tmux を推奨
PreToolUse (12 hooks)	git-push-reminder	push 前にレビューを促す
PreToolUse (12 hooks)	commit-quality	コミット品質チェック
PreToolUse (12 hooks)	doc-file-warning	非標準ドキュメントファイルの警告
PreToolUse (12 hooks)	suggest-compact	戦略的コンパクション提案
PreToolUse (12 hooks)	observe (continuous)	継続学習データ蓄積
PreToolUse (12 hooks)	insaits-security	AI セキュリティモニター
PreToolUse (12 hooks)	governance-capture	ガバナンスイベント記録
PreToolUse (12 hooks)	config-protection	設定ファイル変更ブロック
PreToolUse (12 hooks)	mcp-health-check	MCP サーバー健全性チェック
PostToolUse (7 hooks)	pr-created	PR URL をログ、レビューコマンド提示
PostToolUse (7 hooks)	build-complete	ビルド分析（非同期）
PostToolUse (7 hooks)	quality-gate	品質ゲートチェック
PostToolUse (7 hooks)	post-edit-format	自動フォーマット
PostToolUse (7 hooks)	post-edit-typecheck	TypeScript チェック
PostToolUse (7 hooks)	console-warn	console.log の警告
PostToolUse (7 hooks)	observe (continuous)	継続学習データ蓄積
Stop (5 hooks)	check-console-log	変更ファイル内の console.log 検出
Stop (5 hooks)	session-end	セッション状態保存
Stop (5 hooks)	evaluate-session	パターン抽出
Stop (5 hooks)	cost-tracker	コストメトリクス記録
Stop (5 hooks)	desktop-notify	macOS デスクトップ通知

Hook Profile（フラグシステム）

ECC は Hook の有効/無効を Profile フラグ で制御します：

Profile	レベル	有効な Hook
`minimal`	最小限	session-start, session-end, cost-tracker
`standard`	標準	minimal + suggest-compact, doc-file-warning, console-warn
`strict`	厳格	standard + format, typecheck, commit-quality, git-push-reminder

// run-with-flags.js — Profile に基づいて Hook の実行を制御
// 実行例: node run-with-flags.js "pre:bash:tmux-reminder" 
//            "scripts/hooks/pre-bash-tmux-reminder.js" "strict"

Harness Optimizer — 自動最適化エージェント

ECC には Harness を自動的に改善する 専用エージェント が用意されています。

ワークフロー

制約条件

小さな変更で測定可能な効果 を優先
クロスプラットフォーム動作を保持
脆弱なシェルクォーティングを避ける
Claude Code、Cursor、OpenCode、Codex 全てとの互換性を維持

実践：自分のプロジェクトで始める

Step 1: ECC のインストール

# 方法A: プラグインとしてインストール（推奨）
# Claude Code CLI で以下を実行：
/plugin add everything-claude-code@everything-claude-code

# 方法B: シェルスクリプトでインストール
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
./install.sh --profile core   # Core プロファイル（最小構成）
# ./install.sh --profile full  # Full プロファイル（全機能）

# Core に含まれるもの:
# - 主要エージェント（code-reviewer, planner, tdd-guide, security-reviewer）
# - 必須スキル（tdd-workflow, coding-standards, security-review）
# - 主要コマンド（/tdd, /plan, /code-review, /build-fix）

Step 2: トークン最適化設定

// ~/.claude/settings.json
{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

Step 3: Harness Audit の実行

# 現在のスコアを確認
node scripts/harness-audit.js

# JSON で出力して CI に組み込む
node scripts/harness-audit.js --format json

Step 4: Top Actions に従って改善

Audit が示す Top 3 Actions を順番に実施し、スコアを段階的に向上させます。

Step 5: 定期的な監査

コミットごと、またはスプリントごとに Harness Audit を実行し、スコアの回帰を防止します。

まとめ

最適化の柱	キーアクション	期待効果
Tool Coverage	Agent/Skill/Hook を体系的に整備	対応可能なタスク範囲の拡大
Context Efficiency	戦略的コンパクション + モデルルーティング	応答品質の維持、コスト削減
Quality Gates	PostToolUse Hook で自動検証	バグの早期発見、コード品質向上
Memory Persistence	Session Hook でコンテキスト永続化	セッション間の学習蓄積
Eval Coverage	EDD（Eval-Driven Development）の導入	出力の信頼性を定量化
Security Guardrails	PreToolUse Hook で多層防御	危険操作の未然防止
Cost Efficiency	タスク複雑度ベースのモデル選択	API コスト最大 80% 削減

Harness 最適化の本質は、「エージェントに何をさせるか」ではなく、「エージェントがどのような環境で動作するか」を設計することです。

7 つのカテゴリを体系的に改善することで、同じ AI モデルでも劇的に異なる出力品質を実現できます。

参考リンク

everything-claude-code (GitHub) — 本記事の主要参照元
The Shortform Guide — ECC の概要ガイド
Token Optimization Guide — トークン最適化の詳細
Claude Code Hooks Documentation — 公式 Hooks ドキュメント
Claude Code Plugins Reference — 公式プラグインリファレンス

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

【Claude Code】Harness最適化 完全ガイド — AIコーディングエージェントの性能を7軸で引き上げる

はじめに

目次

Harness とは何か？

Harness Audit — 7カテゴリ評価フレームワーク

7カテゴリ一覧

出力例

Category 1: Tool Coverage（ツール網羅性）

概要

チェック項目

ECC が提供するツール群の規模

実践ポイント

Category 2: Context Efficiency（コンテキスト効率）

概要

チェック項目

推奨設定

戦略的コンパクション

MCP サーバーの管理

Category 3: Quality Gates（品質ゲート）

概要

チェック項目

PostToolUse Hooks による自動品質チェック

Category 4: Memory Persistence（メモリ永続化）

概要

チェック項目

セッションライフサイクル

継続学習 v2

コンパクション後も生き残るもの

Category 5: Eval Coverage（評価カバレッジ）

概要

チェック項目

Eval-Driven Development（EDD）

pass@k メトリクス

Grader（評価者）の種類

Eval アンチパターン

Category 6: Security Guardrails（セキュリティガードレール）

概要

チェック項目

PreToolUse セキュリティ Hooks

多層防御の設計

Category 7: Cost Efficiency（コスト効率）

概要

チェック項目

モデルルーティング戦略

モデル別コスト比較

コスト追跡 Hook

プロンプトキャッシュ

Hooks 設計パターン

ライフサイクルイベント一覧

ECC の Hook 実装一覧（抜粋）

Hook Profile（フラグシステム）

Harness Optimizer — 自動最適化エージェント

ワークフロー

制約条件

実践：自分のプロジェクトで始める

Step 1: ECC のインストール

Step 2: トークン最適化設定

Step 3: Harness Audit の実行

Step 4: Top Actions に従って改善

Step 5: 定期的な監査

まとめ

参考リンク

【Claude Code】Harness最適化完全ガイド — AIコーディングエージェントの性能を7軸で引き上げる