Claude Codeを"使う側"から"使いこなす側"へ — ハーネス設計者という新しい役割と12の実践技術

Last updated at 2026-10-05Posted at 2026-08-20

この記事について

Claude Codeを使ったAIエージェント開発の「ハーネス設計」を、初心者から実務エンジニアまで体系的に学べる記事です。Udemyコース「実践 Claude Code ハーネス設計完全ガイド」（全150レッスン、著者：Atsushi Ishida）の内容を実務応用視点で再構成しています。

📚 含まれる内容（全12セクション）

ハーネス設計の基礎: ハーネス設計者という役割・コードを書く時代からAIを導く時代へ
コンテキストエンジニアリング: Write / Select / Compress / Isolate の4戦略
Claude Code制御インターフェース: CLAUDE.md / Rules / Hooks / Skills / サブエージェント / MCP の6つ
Hooks実践: 確率的な指示から決定論的な制御へ・exit codeによるブロック設計
エージェント設計パターン: ルーティング / ACI設計 / 投票パターン
Generator-Evaluatorパターン: 生成と評価の分離・スプリントコントラクト・rubric設計
マルチエージェント設計: オーケストレーター / シーケンシャル / ファンアウトの3パターン
長時間エージェント管理: コンテキスト不安・構造化ハンドオフ・コンテキスト毒性対策
ツール設計の原則: 選択的実装・コンテキスト効率・エラーメッセージ設計
検証ループの体系化: ルールベース / ビジュアル / LLM-as-Judgeの3戦略
評価ハーネス設計: pass@k・pass^k・20タスクから始めるスモールスタート
実践ケーススタディ: フルスタック開発 / コンテンツ生成 / リサーチエージェントの3事例

🎯 対象読者

Claude Codeを使い始めたエンジニア
AIエージェントの品質が安定しないと感じているエンジニア
AWS・CI/CDなどの実務でAIを活用したいインフラ / バックエンドエンジニア
LLMを本番環境に組み込みたいSRE・DevOpsエンジニア

⏱️ 想定読了時間

通読: 30〜45分
実践込み: コードサンプルを手元で試しながら1〜2時間

💡 この記事の特徴

✅ コードサンプル付き: Hooksスクリプト・CLAUDE.md・rubricファイルなど実践的なサンプルを掲載
✅ 実務との接続: AWS IaC（Terraform）・CI/CD・マルチAIレビューなど実務ユースケースで解説
✅ 正確性を重視: 執筆後に公式ドキュメントおよびスライド資料で事実確認・修正済み
✅ 今日から使える: 末尾に「明日から始める3つのアクション」で実践導線あり

📖 読み方ガイド

Claude Code初心者: セクション1〜3から順番に読み進めてください
Hooks・設計パターンに興味がある方: セクション4〜7にジャンプしてください
品質・評価の仕組みを知りたい方: セクション10〜12を参照してください

はじめに
ハーネス設計者とは何か
コンテキストエンジニアリング4戦略
Claude Code固有の6つの制御インターフェース
Hooksの実践
エージェント設計3パターン
Generator-Evaluatorパターン
マルチエージェント設計
長時間エージェントの管理
ツール設計の原則
検証ループの体系化
評価ハーネス設計
実践ケーススタディ
まとめ

はじめに

「Claude Codeを使っているのに、なぜか成果がイマイチ…」と感じたことはないでしょうか。

実は、同じモデルを使っていても、成果が10倍変わることがあるとされています。その差を生み出すのが「ハーネス設計」という考え方です。

本記事は、Udemyコース「実践 Claude Code ハーネス設計完全ガイド」を受講し、AWS IaCやCI/CDパイプライン構築などの実務経験も交えながら、自分なりの解釈で再構成したものです。コースの忠実な要約ではなく、「実務でどう使えるか」という観点で読み解いています。

AIツールに触れてきたエンジニアなら誰でも読める内容にまとめています。

1. ハーネス設計者とは何か

コードを書く時代からAIを導く時代へ

エンジニアの役割が根本から変わりつつあります。

時代	エンジニアの仕事
従来	自分でコードを書くのが主な仕事
現在	AIエージェントを設計・制御し、AIがコードを生成する

求められるスキルも「実装力」から「設計力・制御力・評価力」へとシフトしています。

ハーネスとは？

ハーネス（harness）とは、AIエージェントの「制御構造」のことです。馬具のハーネスをイメージするとわかりやすく、AIという強力だが不安定な知性を、意図した方向へ安定して動かすための枠組みです。

スライドでは「スパイキーな知性（Spiky Intelligence）」という表現が使われています。AIはある領域では超人的な能力を発揮する一方、別の領域では初歩的なミスを犯す。この凸凹を補う環境を設計することが、ハーネス設計者の仕事です。

「使う側」と「使いこなす側」の決定的な違い

観点	使う側	使いこなす側
プロンプト	その場で考えて入力	事前に設計し再利用可能にする
品質管理	出力を目視で確認	自動評価ループで品質を保証
コンテキスト	必要な情報を都度伝える	構造化して自動注入する
エラー対応	問題が起きてから修正	事前に検証の仕組みを組み込む
スケール	1回の対話で完結	複数エージェントを協調させる

使いこなす側のキーワードは「事前設計・自動化・構造化・再利用」です。

2. コンテキストエンジニアリング4戦略 — AIが見る世界を設計する

AIエージェントの出力品質は、コンテキストウィンドウ（AIのワーキングメモリ）に何を入れるかで決まります。コンテキストウィンドウとはLLMが一度に参照できる情報の総量のこと。詰め込みすぎると注意力が分散し精度が下がるため、「最小限の高シグナルなトークンで最大の成果を引き出す」設計が重要です。

コースでは4つの戦略が提唱されています。

Write戦略：外部記憶に知識を書き出して永続化する

コンテキストウィンドウの外に情報を永続化し、セッションを超えて知識を引き継ぎます。エージェントに自分でメモを取らせることで長期記憶を実現するイメージです。

実践例： CLAUDE.md、進捗ファイル、TODOリスト、メモリファイルへの書き出し。

実務応用： 長時間のIaC生成タスクで、進捗ファイル（claude-progress.txt）にチェックポイントを書き出し、途中でセッションが切れてもリカバリできるようにする。

Select戦略：必要な情報だけをジャストインタイムで取り込む

事前に全部読み込まず、必要になった時に取り込む「プログレッシブ・ディスクロージャー」の考え方です。軽量な識別子（ファイルパス、URL）をエージェントに渡し、エージェント自らが探索します。

実務応用： Terraform設計ガイドを丸ごと渡すのではなく、現在作業中のリソース種別に関連するルールだけを都度読み込ませる。

Compress戦略：要約とトリミングで限られた窓を最大活用する

保持すべき情報	除去してよい情報
設計上の重要な判断	古いツール実行結果
未解決のバグ・課題	冗長な中間出力
ユーザーの要求事項	完了済みタスクの詳細

実務応用： CloudTrailのイベントログをそのまま渡すのではなく、Lambda関数で重要フィールドだけに絞ってからAIに渡す。

Isolate戦略：サブエージェントで文脈を分離し並列処理する

各サブエージェントが独立したコンテキストウィンドウを持ち、大量のトークンを消費する作業をメインから分離します。結果は1,000〜2,000トークンの要約としてメインに返すことで、メインのコンテキストを汚染しません。

実務応用（multi-ai-pr-review）： 「セキュリティ観点エージェント」「パフォーマンス観点エージェント」「コード品質エージェント」を分けて並列実行し、各エージェントの結果を集約する。

原則（スライドより）： 最も強力なモデルで最小限のプロンプトから始め、失敗を観察して段階的にコンテキストを追加する。

3. Claude Code固有の6つの制御インターフェース

4つの戦略をClaude Codeで実現するための専用インターフェースが6つあります。

インターフェース	戦略	使いどころ	読み込みタイミング
CLAUDE.md	Write	プロジェクト全体の規約・知識	常時
Rules	Select	ファイル種別ごとの指示	パターンマッチ時
Hooks	—	ツール実行の制御・検証	ツール呼び出し時
Skills	Select	タスク固有の手順書	明示的呼び出し時
サブエージェント	Isolate	並列調査・大規模分析	タスク委任時
MCPサーバー	Select	外部システム連携	ツール呼び出し時

① CLAUDE.md — プロジェクトの知識と規約を永続化する

CLAUDE.md = プロジェクトの取扱説明書。3つのスコープで柔軟に管理します。

スコープ	ファイル	用途	Git共有
個人	`~/.claude/CLAUDE.md`	個人の好み・スタイル	なし
プロジェクト	`プロジェクト/CLAUDE.md`	コーディング規約・構造	あり
ローカル	`.claude/CLAUDE.md`	個人×プロジェクト	なし

# プロジェクト規約

## コーディング規約
- Terraformリソース名はスネークケースを使用すること
  （理由: tflintのデフォルトルールと統一し、CIでの自動チェックを通すため）
- モジュールの分割単位はAWSサービスごと

## やってはいけないこと
- ハードコードされたAWSアカウントIDの使用
- `terraform destroy` の無断実行

ポイント（スライドより）： 単なるルール羅列ではなく、「なぜそのルールがあるのかの理由も記載」すると、AIの判断力が上がります。「Claudeが推測できない情報を、理由付きで、具体的に」記述することがAnthropicの推奨です。

② Rules — ファイル種別に応じた指示を自動適用する（Select戦略の実装）

CLAUDE.mdの「常時読み込み」に対して、Rulesは「条件付き読み込み」です。ファイルパスにマッチした時だけコンテキストに注入されます。

.claude/rules/
├── test-files.md     # **/*_test.go にマッチ
├── api-handlers.md   # src/api/**/*.ts にマッチ
└── migrations.md     # db/migrations/*.sql にマッチ

---
paths: ["**/*.tf"]
---
## Terraform作業時の規約
- plan結果を確認してからapplyすること（理由: 意図しない破壊的変更を防ぐため）
- state操作は必ずバックアップを取ること

③ Hooks — ツール実行の前後に検証処理を差し込む

AIの行動をリアルタイムに制御するミドルウェアパターン。これがハーネス設計の核心です。

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/validate-bash.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/lint-on-save.sh", "async": true }]
      }
    ]
  }
}

④ Skills — 必要な手順書をオンデマンドで読み込ませる（Select戦略の応用）

スラッシュコマンド（/deploy、/review-pr）で呼び出した時だけコンテキストに読み込まれる再利用可能な手順書です。複雑な手順を標準化し、何度でも同じ品質で実行できます。

---
name: deploy
description: ステージング環境へのデプロイ手順
---
## デプロイ手順
1. `terraform plan -var-file=stg.tfvars` で差分確認
2. レビュアーに確認を取る
3. `terraform apply -var-file=stg.tfvars` を実行
...

⑤ サブエージェント — 複雑なタスクを分離して並列実行する（Isolate戦略の直接実装）

独立したコンテキストウィンドウでメインの文脈を保護しながら、並列実行で処理時間を大幅短縮します。結果は要約として返却（1,000〜2,000トークン）します。

⑥ MCPサーバー — 外部システムとの接続を構造化する（Select戦略の拡張）

Model Context Protocol（MCP）= 外部システムとの標準化された接続。ツール定義に型情報と説明を含むため、AIが正しく使いこなせます。社内固有のシステムもMCPサーバーを作れば接続可能です。

4. Hooksの実践 — 確率的な指示から決定論的な制御へ

CLAUDE.md vs Hooks：確率的 vs 決定論的

# CLAUDE.md（確率的 = お願い）
# - rm -rf は絶対に使わないこと
# AIは高い確率で従うが、100%の保証はない

# Hooks（決定論的 = 強制）
if echo "$CMD" | grep -q "rm -rf"; then
  exit 2  # exit 2を返せば100%実行されない
fi

使い分け判断基準（スライドより）：

失敗が許されない操作 → Hooks（決定論的）
柔軟な判断が必要なもの → CLAUDE.md（確率的）

フックスクリプトのインターフェース仕様

Claude Codeがフックをパイプ経由でJSONを渡して呼び出します。

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /tmp"}}' | ./hook.sh

要素	動作	具体例
stdin	ツール名と引数のJSON	`jq -r '.tool_input.command'` で抽出
exit 0	許可 — ツール実行を続行	パターンに一致しない → 通過
exit 2	ブロック — 実行を阻止（決定論的）	`rm -rf` を検出 → 阻止
stdout	Claudeのコンテキストにフィードバック	`"BLOCKED: rm -rf"` → 代替案を検討
stderr	ユーザーの画面に直接表示	`"⚠ 危険なコマンドを検出"`

PreToolUse：危険な操作を実行前にブロックする

#!/bin/bash
# .claude/hooks/validate-bash.sh
CMD=$(jq -r '.tool_input.command' < /dev/stdin)

if echo "$CMD" | grep -qE 'rm -rf|terraform destroy|DROP TABLE'; then
  echo "⚠ 危険なコマンドを検出しました: $CMD" >&2   # stderrでユーザーへ表示
  echo "BLOCKED: $CMD"                              # stdoutでClaudeへフィードバック
  exit 2                                            # 決定論的にブロック
fi

exit 0

ポイント： exit 2でブロックする際、stdoutのフィードバックによってClaudeが代替案を検討します。パターンを追加するだけでガードレールを拡張できます。

PostToolUse：ツール実行後に品質チェックを自動実行する

PreToolUseとの違い：PreToolUseはブロック（実行させない）、PostToolUseは補正（実行結果を改善する）です。async: true で非同期実行にすることでエージェントの作業を止めません。

#!/bin/bash
# .claude/hooks/lint-on-save.sh
FILE=$(jq -r '.tool_input.path' < /dev/stdin)

case "$FILE" in
  *.tf)
    terraform validate . 2>&1
    tflint "$FILE" 2>&1
    ;;
  *.py)
    ruff check "$FILE" 2>&1
    ;;
esac
# stdoutに出力した結果はClaudeのコンテキストに入る → 問題があればClaudeが自分で修正

Notification：長時間タスクの完了を知らせる

#!/bin/bash
# .claude/hooks/notify-done.sh
# macOS デスクトップ通知
osascript -e 'display notification "Claude Codeのタスクが完了しました" with title "Claude Code"'
# ターミナルのベル音
echo -e "\a"
# Slack Webhook
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  --data '{"text": "✅ Claude Codeのタスクが完了しました"}'

5. エージェント設計3パターン

参考: anthropic.com/engineering/building-effective-agents

パターン1：ルーティング — 入力を分類して専門ハンドラに振り分ける

入力を最初に分類し、カテゴリごとに最適化された処理へ振り分けます。各ハンドラは専門のプロンプト・ツール・コンテキストを持ちます。

ユーザー入力
  ├─ Terraformコード → Terraform専門エージェント
  ├─ Pythonコード   → Python専門エージェント
  └─ セキュリティ質問 → セキュリティ専門エージェント

Claude CodeのRulesはファイルパスによるルーティングと見ることができます。入力の分類を人間が設計し、処理を自動化する仕組みです。

パターン2：ACI設計 — エージェントとツールの接点を最適化する

ACI = Agent-Computer Interface。人間向けにUI/UXを設計するのと同じように、AIエージェント向けにツールの使い勝手を設計します。

スライドより（Anthropicの報告）： 「SWE-benchの実装で、ツールの最適化がプロンプト全体の最適化より時間を要した」

ACI設計の4原則：

原則	内容	具体例
思考のための余裕	書き込み前に計画を立てるトークンを確保	「まず計画を出力せよ」と指示
自然な形式	インターネット上の自然な形式を採用	独自フォーマットより標準的なJSON・Markdown
オーバーヘッド排除	行数カウント等のフォーマット負荷を除去	「100行目から」→ 内容で指定
明確な命名	パラメータの名前と説明を明確に	`file` → `absolute_file_path`

ACI設計の実践例（スライドより）：

// ❌ 悪いACI設計（相対パス + 行番号指定）
{"tool": "edit_file", "params": {"file": "utils.ts", "line_start": 42, "line_end": 55}}

// ✅ 良いACI設計（絶対パス + 内容マッチング）
{"tool": "edit_file", "params": {"absolute_file_path": "/src/utils.ts", "old_content": "function calc() {", "new_content": "function calculate() {"}}

Anthropicの実績：相対パスを絶対パス必須に変えただけでファイル編集の精度が劇的に向上。

パターン3：投票 — 同一タスクの複数実行で品質の合意を形成する

同じタスクを複数回独立に実行し、多数決・加重平均・一致度チェックで合意を形成します。2つ以上のエージェントが指摘した問題を高確度の問題として優先対応します。

同一タスク（PRのコードレビュー）
  ├─ エージェントA（セキュリティ視点: 入力検証・認証・インジェクション）
  ├─ エージェントB（パフォーマンス視点: N+1クエリ・メモリ使用量）
  └─ エージェントC（保守性視点: 命名規則・関心の分離・テスト容易性）
         ↓
  2つ以上が指摘した問題 = 高確度の問題として優先対応

Anthropicの基本原則： 複雑さは実測で効果が証明された場合のみ追加する。まずシンプルなプロンプトで直接LLMを呼び出し、不十分なら段階的に複雑化する。

6. Generator-Evaluatorパターン — 生成と評価を分離する

なぜ自己評価は信頼できないのか

作業を生成したエージェントに評価させると、自信を持って成果を称賛します。品質が明らかに平凡でも起きる構造的な現象です（Anthropicの観察）。原因：生成時の文脈と思考パターンがそのまま評価をバイアスするためです。

GANに着想を得た分離アーキテクチャ

GAN（敵対的生成ネットワーク）と同じ発想で生成と評価を分離します。

Generator（生成者）→ 成果物 → Evaluator（評価者）
                              ↓（不合格 + フィードバック）
                    Generator ← フィードバック
                              ↓（合格）
                         最終成果物

スライドより： 独立した評価者を「懐疑的」にチューニングする方が、生成者に自己批判させるより遥かに簡単。

グレーダブル・クライテリア（採点可能な評価基準）

曖昧な指示を具体的な評価基準に変換します。

# specs/evaluation-rubric.md

## 評価基準（Anthropicの推奨: 損失関数のように設計する）

### セキュリティ（Low/High スコアの状態を具体的に定義）
| スコア | 状態 |
|---|---|
| 低 | IAMポリシーが * 権限を持つ / シークレットがハードコード |
| 高 | 最小権限が徹底 / Secrets Manager参照 / S3パブリックアクセスブロック済み |

### 可読性
| スコア | 状態 |
|---|---|
| 低 | マジックナンバー多用 / ネストが深い / コメントなし |
| 高 | 変数名が意図を表す / 「なぜ」を説明するコメント |

スプリントコントラクト — 生成者と評価者の事前合意

実装前にGeneratorとEvaluatorが完了基準を合意します。合意があるから、評価者が「そんなの聞いてない」と言いません。

# specs/sprint-contract.md

## 実装スコープ（このスプリントで何を作るか）
Terraformモジュール（RDS Aurora Multi-AZ構成）を作成する

## 完了基準（Evaluatorがチェックする検証可能な項目）
- [ ] terraform validateが通ること
- [ ] tflintエラーが0件
- [ ] evaluation-rubric.mdのセキュリティ・可読性が両方「高」スコア

## 検証方法
- terraform validate / tflint を自動実行
- evaluation-rubric.mdに基づきEvaluatorが採点

## スコープ外
- 既存モジュールの修正
- 本番環境へのapply

スプリントコントラクトの3つの必須セクション：

実装スコープ：何を作るか
完了基準：できた/できてないの二値判定
検証方法：どう確認するか

evaluation-rubric.md の「どの程度良いか（段階評価）」とは役割を分担します。

評価パイプライン：Playwrightによるライブ検証

コードレビューではなく実際にアプリケーションを操作して評価することが品質保証の要です。反復の目安：最初の2〜3回で最大の改善が起きます（収穫逓減の法則）。3回連続で改善なし、またはCritical項目が全合格したら停止します。

7. マルチエージェント設計 — 複雑なタスクを分割統治する

なぜ単一エージェントでは限界があるのか

限界	具体的な問題
コンテキスト容量	複雑なタスクでは参照すべき情報量がウィンドウを超える
専門性の希釈	多くの役割を同時に持たせると各領域の精度が低下
処理時間	全作業を直列に処理するため、完了までの時間が長い

スライドより（Anthropicの実測）： トークン使用量だけで性能の80%の分散を説明できる。つまりコンテキストの質と量が成果を直接決定する。

3つのパターン

オーケストレーター・ワーカーパターン

オーケストレーターが全体戦略を策定し、タスクを動的に分解して専門ワーカーに委任します。結果をオーケストレーターが統合して最終成果物を完成させます。適用場面：複数ファイルにまたがる変更、大規模リファクタリング。

オーケストレーター（リードエージェント）
  ├─ ワーカーA（フロントエンド: React/Vite）
  ├─ ワーカーB（バックエンド: FastAPI）
  └─ ワーカーC（テスト作成）
         ↓
    統合された最終成果

シーケンシャルパイプラインパターン

各エージェントがパイプラインの1工程を担当し、前工程の出力が次工程の入力になります（リレー方式）。各工程が独自のコンテキストで動作するため専門性が高く、前工程の「汚染」が引き継がれません。

Planner（仕様書作成）→ Generator（実装）→ Evaluator（評価）
                        ↑_______不合格_______|

ファンアウト・ギャザーパターン

独立した複数タスクを同時に並列実行し、各エージェントが結果を固有のキーに書き込みます（競合防止）。

スライドより（Anthropicの実績）： 並列実行でリサーチ時間を最大90%短縮。

メインエージェント
  ├─ セキュリティ分析エージェント → レポート
  ├─ パフォーマンス分析エージェント → レポート
  └─ コード品質分析エージェント → レポート
         ↓ 結果を統合
    総合レビューレポート

パターン選択の判断基準

判断基準	オーケストレーター	シーケンシャル	ファンアウト
タスクの関係	相互依存あり	前後依存あり	独立
動的分解	必要	不要（工程固定）	不要（並列分割）
速度重視	中程度	遅い	最速
典型例	大規模リファクタリング	コンテンツ生成	コードレビュー

スライドより（Anthropicの知見）： 「プロンプトエンジニアリングが主要なレバー」— 複雑な制御構造より、適切なプロンプト設計が効果的。

8. 長時間エージェントの管理 — コンテキストの壁を越える

コンテキスト不安とは

コンテキストウィンドウの容量が埋まってくると発生する現象です。モデルが残り容量を「察して」作業を早期に切り上げようとし、品質の手抜き、重要な手順のスキップ、楽観的な完了宣言が起きます。

スライドより（Anthropicの報告）： 「コンテキストの限界に近づくと、モデルは作業を早めに完了させようとする」

解決策：全リセット＋構造化ハンドオフ

コンパクション（会話を要約して圧縮）は、要約時に重要な情報が欠落するリスクがあります。Anthropicの推奨は全リセット＋構造化ハンドオフです。

# claude-progress.txt（進捗ファイルの例）

## 完了した作業
- [x] VPCモジュール作成（ap-northeast-1、10.0.0.0/16）
- [x] ECSクラスター定義（Fargate）

## 現在の状態
- RDSモジュール作成中（50%完了）
  - 完了: variables.tf
  - 未完了: main.tfのリソース定義
  - テスト結果: terraform validate → OK

## 次のアクション（優先順）
1. rds/main.tfのaws_rds_clusterリソース定義
2. MultiAZ設定の追加
3. CloudWatchアラーム設定

## 重要な決定事項
- RDSはMulti-AZ構成を採用（可用性優先、コスト二次）
- DBサブネットグループは既存のものを参照（db_subnet_group_name）

スライドより（比喩）： 「交代勤務のエンジニアが、前の勤務者から完璧な引き継ぎノートを受け取る」イメージ。

フィーチャーリストでテスト項目をロックする

エージェントはテストを削除すれば「全合格」にできてしまいます。passes フィールドの変更のみ許可し、テスト項目の削除・編集を禁止することで防ぎます（Anthropicの推奨）。

// feature_list.json
{
  "features": [
    {
      "category": "RDS Aurora",
      "description": "Multi-AZ構成で起動できること",
      "verification_steps": ["terraform plan で aws_rds_cluster が表示されること"],
      "passes": null
    }
  ]
}

Initializerエージェントと後続エージェントの役割分担

初回セッション：Initializerエージェントが開発環境構築・フィーチャーリスト作成・進捗ファイル初期化を行い、CLAUDE.mdにスタートアップ手順を組み込みます。

# CLAUDE.mdのスタートアップ指示（全セッション共通）

## セッション開始時の手順（毎回必ず実行）
1. `pwd` で作業ディレクトリを確認
2. `git log --oneline -20` で最近の変更を確認
3. `claude-progress.txt` を読んで現状を把握
4. `feature_list.json` から次の優先タスクを選択
5. `bash init.sh` でアプリを起動し現在の状態を確認

⚠ この手順をスキップしてはいけない。

コンテキスト毒性に注意

エージェントの幻覚（ハルシネーション）がコンテキストに残留すると、以降の推論が汚染された前提に基づいて進みます（コンテキスト毒性）。

対策	方法
定期的な全リセット	汚染が蓄積する前にコンテキストをクリア
外部検証の組み込み	テスト実行やlintで客観的に幻覚を検出
構造化ノート	検証済みの事実だけを外部ファイルに記録

9. ツール設計の原則 — 少ないツールが成果を上げる

なぜツール設計はプロンプトより重要なのか

ツールはエージェントが「何ができるか」を知覚するアフォーダンスを形成します。

スライドより（Anthropicの発見）： SWE-benchでプロンプト最適化よりツール最適化に多くの時間を費やし、より大きな成果を得た。

選択的実装：すべてのAPIをラップしない

アプローチ	ツール設計	結果
❌ 全エンドポイントラップ	`list_users`, `get_user`, `create_event`… (15ツール)	選択肢が多すぎて誤選択が頻発
✅ 選択的実装	`schedule_event`, `search_contacts`, `manage_calendar` (3ツール)	タスク指向で直感的

原則：「このツールがなくてもエージェントはタスクを完了できるか？」→ Yesなら不要。

コンテキスト効率の設計

# ❌ 全フィールドを返す（トークン無駄遣い）
def get_ec2_instance(instance_id):
    return boto3.client('ec2').describe_instances(InstanceIds=[instance_id])

# ✅ アクションに関連する情報のみ返す
def get_ec2_instance(instance_id):
    resp = boto3.client('ec2').describe_instances(InstanceIds=[instance_id])
    inst = resp['Reservations'][0]['Instances'][0]
    return {
        "id": inst['InstanceId'],
        "state": inst['State']['Name'],
        "type": inst['InstanceType'],
        "private_ip": inst.get('PrivateIpAddress')
    }

ネームスペーシング：エージェントの認知負荷を減らす

命名規則：{サービス}_{リソース}_{操作} の3層構造。

❌ search  → 何を検索？
❌ create  → 何を作成？
✅ github_issues_search
✅ slack_messages_send
✅ aws_ec2_describe

エラーメッセージ：次のアクションを示す

# ❌ 従来のエラーメッセージ
raise Exception("400 Bad Request")

# ✅ エージェント向けエラーメッセージ
raise Exception(
    "invalid_date_format: 日付はYYYY-MM-DD形式で指定してください。"
    "例: 2024-01-15"
)

Vercelの事例（スライドより正確な内容）

スライドより：

Vercelのd0チームはツールの80%を削減した結果、成果が向上した（元記事の実績）

Vercelの事例から、コースでは次のように一般化されています。

選択のパラドックス：選択肢が増えるほど判断の質が低下する

実践ガイドライン：3〜5ツールから始め、評価で必要性が示されたときだけ追加する

3フェーズ開発プロセス

フェーズ	内容	ポイント
1. プロトタイプ	LLMフレンドリーなドキュメント付きでツールを構築	説明文は「ジュニア開発者向け」の粒度
2. 評価	複数ツール呼び出しを含む現実的なシナリオでテスト	単一ツールのテストでは不十分
3. 協働改善	エージェントの実行ログを読んで行動を観察・改善	トランスクリプトを読むことが鍵

10. 検証ループの体系化 — 3つの戦略で品質を2〜3倍改善する

単発生成ではなく、生成→検証→修正のループを設計することが重要です。

スライドより（Anthropicの報告）： 核心：価値を生むのは特定の検証手法ではなく、フィードバックループという構造そのもの。

戦略1：ルールベースフィードバック

決定論的で高速。ESLint・TypeScriptコンパイラ・Pytest・Playwrightテストなどのツールで形式的に定義可能なものを確実にキャッチします。PostToolUseフックと統合して自動品質ゲートとして機能させます。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "write_to_file",
      "hooks": [{
        "type": "command",
        "command": "npx eslint --no-warn $CLAUDE_FILE_PATH 2>&1 || true"
      }]
    }]
  }
}

限界： 構文エラー・型の不整合・テスト失敗はチェックできるが、UIの見た目・コードの読みやすさはチェックできない。

戦略2：ビジュアルフィードバック

生成されたUIのスクリーンショットを撮影し、マルチモーダルモデルで視覚的に品質を判定します。コードでは表現できない品質（美しさ、視覚的ヒエラルキー、余白のバランス）を捉えます。

// Playwrightでスクリーンショット取得
const { chromium } = require('playwright');
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('http://localhost:3000');
await page.screenshot({ path: 'screenshot.png', fullPage: true });
// → このスクリーンショットをマルチモーダルモデルに渡して評価

スライドより（Anthropicの報告）： ビジュアルフィードバックはフロントエンドタスクで特に効果的。「ボタンは機能するか？」（機能テスト）＋「ボタンは見やすいか？」（ビジュアルテスト）= 包括的な品質保証。

戦略3：LLM-as-Judge

別のLLMを評価者として使い、ルールでもビジュアルでも捉えられない主観的品質を採点します。独立したコンテキストで評価することでGenerator-Evaluatorの原理を踏襲します。

スライドより： 次セクションの評価ハーネス設計で扱うModel-based Graderと同じ手法。

3戦略の使い分け

成果物 → ルールベース（高速ゲート）
             ↓ 合格
         ビジュアル / LLM-as-Judge（深い評価）
             ↓ 合格
         最終成果物

Anthropicの原則： まずルールベースで始め、ルールで表現できない基準がある場合のみ他の戦略を追加する。

11. 評価ハーネス設計 — 改善し続ける仕組みを作る

エージェントハーネスと評価ハーネスの違い

比較軸	エージェントハーネス	評価ハーネス
目的	タスクを実行する	ハーネスの性能を計測する
役割	実行系	計測系
構成要素	CLAUDE.md・Hooks・Tools	テストタスク・採点関数・ログ

評価ハーネスを持つことで、「ハーネスを改善したときに本当に良くなったか」を数値で確認できます。

評価の5つの構成要素

Tasks：解くべき具体的な問題（参照解答付き）
Trials：同じタスクを複数回実行（エージェントは非決定的）
Graders：成果物を採点する関数（自動 or 人手）
Transcripts：エージェントの全行動・推論のログ
Outcomes：タスク横断・試行横断の集計スコア

3種のGrader

種類	特徴	長所	短所	用途
Code-based	`assert output == expected`	高速・決定的・再現性あり	柔軟性が低い	構造化出力・テスト結果
Model-based	LLMが基準に基づき採点	曖昧な基準にも対応	非決定的・コスト発生	文章品質・UX評価
Human	人間が最終判断	最高精度（ゴールド標準）	高コスト・スケールしない	キャリブレーション

Model-based Graderのスコアドリフト対策（Few-Shotキャリブレーション）：

良い例・普通の例・悪い例にそれぞれ具体的な判定理由を付与してスコアの基準を固定します。各参照例に具体的な判定理由を付与することで採点行動が「アンカリング」され、同じ品質の成果物を繰り返し採点しても一貫した結果が得られます。

Capability Evals と Regression Evals

比較軸	Capability Evals	Regression Evals
目的	「何ができるか」を探る	「品質退行を防ぐ」
合格率の目安	30〜50%が健全	ほぼ100%であるべき
役割	フロンティアテスト	ハーネス変更時のセーフティネット

pass@k と pass^k

pass@k：k回中1回でも成功すれば合格（能力の上限を測る）
pass^k：k回すべて成功しなければ合格（信頼性を測る）

例: 1回の成功率が60%のタスクを5回試行した場合
  pass@5  = 1 - (0.4)^5 = 99.0%（5回中1回は成功する）
  pass^5  = (0.6)^5     =  7.8%（5回全て成功は稀）

用途	重視する指標	理由
ユーザー対話型	pass^k	毎回の応答品質が重要
バッチ処理	pass@k	失敗してもリトライ可能

Swiss Cheese Model：多層評価で見落としを防ぐ

どの評価手法にも「穴」（盲点）があります。複数の手法を重ねることで穴が一直線に並ばず、見落としを最小化できます。

層	得意な検出	盲点
Code-based	構造・フォーマット・テスト結果	品質・創造性
Model-based	文脈理解・主観的品質	一貫性・再現性
Human	全般的な判断	スケール・コスト
Transcript	推論過程・非効率な手順	最終成果物の品質

まず20タスクから始める

タスク収集の構成例（合計20タスク）:
  - 最近発生したバグに基づくタスク: 5〜7個
  - よくあるユーザーリクエスト: 5〜7個
  - エッジケース・境界条件: 5〜7個
  - 複合的な難題（Capability Eval用）: 2〜3個

スライドより（Anthropicの知見）： 「評価インフラへの投資は複利のリターンをもたらす」— 最初の20タスクが将来の改善を加速させる。

12. 実践ケーススタディ — 3つの事例

事例1：フルスタックアプリ開発ハーネス（3エージェント構成）

ユーザーの1〜4文の指示
  → Planner（包括的仕様書に展開）
  → Generator・Evaluator がスプリントコントラクトを交渉
  → Generator（React + Vite + FastAPI + SQLiteで実装）
  → Evaluator（Playwrightでライブ検証）
     → 不合格なら次のスプリントへ
     → 合格でスプリント完了

コスト比較（スライドより）：

指標	単独エージェント	ハーネス構成
所要時間	20分	6時間
コスト	$9	$200（22倍）
コア機能	破綻	動作
UI品質	基本的	洗練
総合品質	不十分	実用レベル

22倍のコストで壊れた成果物が実用レベルに改善。低コストで壊れたものを作るか、適正コストで動くものを作るかというトレードオフです。

事例2：コンテンツ生成パイプライン

カリキュラム設計
  → Generator（全コンテンツ一括生成）
  → Evaluator（3観点で並列評価）
     → スコア90点以上 かつ Critical項目全合格 → 完了
     → 未達かつ3回目未満 → 改善指示をフィードバック → Generator再実行
     → 3回目到達 → 最終成果物（警告付き）

Critical項目（技術的正確性、構造整合性）は最優先で修正。各イテレーションの評価結果をファイルに記録し、改善の進捗を追跡します。

事例3：リサーチエージェント

複雑な質問
  → リードエージェント（戦略策定）
  → サブエージェントを並列起動（Web検索・ドキュメント分析・コード調査）
  → 各エージェントが要約を返却
  → 新たな発見に基づき追加調査（動的多段検索）
  → 包括的なリサーチレポート生成

従来のRAG（1回の検索で回答）との決定的な違いは、発見に基づいて戦略を適応的に変更する点です。

スライドより： 単一エージェント比で90.2%の性能向上を達成。

3事例に共通するハーネス設計の原則

原則	事例1	事例2	事例3
生成と評価の分離	G-Eパターン	並列評価	リード+サブ
構造化された成果物	Sprint Contract	フィードバックMD	要約レポート
反復による改善	Sprint繰り返し	最大3イテレーション	多段検索
コスト意識	22x vs 品質	回数上限あり	複雑さでスケール

ハーネス設計の本質（スライドより）

"Every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing"
— Anthropic Engineering Blog

事例1 Evaluator → モデルは自分のコードの品質を判断できない
事例2 イテレーション上限 → 一発で高品質なコンテンツを生成できない
事例3 サブエージェント分離 → 複雑な調査を1つのモデルで処理しきれない

モデルは進化する → 前提が今も正しいか定期的に見直し、不要になった部品は取り除いてシンプルにします。

まとめ — 明日から始める3つのアクション

本記事で紹介した12の技術をすべて一度に実装しようとすると挫折します。コースが推奨する3つのアクションから始めましょう。

アクション1：CLAUDE.mdを作成する（今日）

まだ持っていないなら今日作る。完璧を目指さず、まず10行から始めます。

# プロジェクト規約

## 禁止事項
- terraform destroy の無断実行
- ハードコードされたAWSアカウントID

## コーディング規約（理由付き）
- Terraformリソース名はスネークケース（理由: tflintルールとの統一）

アクション2：Generator-Evaluatorを試す（今週）

生成後に別セッションで評価させ、自己評価との品質差を体感します。

アクション3：ハーネスの仮説を検証する（今月）

「AIがXを自力でできないはず」と仮説を立て、補助を入れて検証します。正しければ組み込み、間違いなら取り除きます。これがハーネス設計の継続的改善サイクルです。

さいごに

AIエージェントの能力は既に十分に高い。足りないのは「導き方」の設計。— コースより

ハーネス設計は特別なスキルではなく、仮説を立て、検証し、改善するサイクルです。設計原則（Write/Select/Compress/Isolate）はモデルに依存しない普遍的な考え方であり、モデルが進化してもそれに適応していくための「メタスキル」です。

コースURL：https://www.udemy.com/course/microlearning-claude-code-harness-design-for-ai-agents/

参考リンク

コースで紹介されているAnthropicの公式リソース（スライドより）

Building Effective Agents（エージェント設計の基礎）
Effective Harnesses for Long-Running Agents（長時間ハーネスの実践）
Effective Context Engineering for AI Agents（コンテキスト設計）
How We Built Our Multi-Agent Research System（マルチエージェント実装）
Writing Tools for Agents（ツール設計）
Demystifying Evals for AI Agents（評価ハーネス設計）

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