作成日: 2026-04-02 調査方法: WebSearch（Anthropic公式 / OpenAI / Martin Fowler / Google Cloud / HumanLayer / LangChain 他21ソース）+ 現行ハーネス分析 対象: AIエージェントの振る舞いを制御するシステム設計全般、特にClaude Code + 秘書体制
「ハーネスエンジニアリング」とは、AIエージェントに何をさせ、何をさせないかを決める設計技法のこと。 Claude Codeの文脈では CLAUDE.md / hooks / skills / memory / rules / plugins がハーネスに相当する。
馬に付ける「馬具（ハーネス）」のイメージ: 馬（AI）の力を活かしながら、暴走を防ぎ、意図した方向に進ませる仕組み。
| 世代 | 焦点 | 設計対象 | 時期 |
|---|---|---|---|
| プロンプトエンジニアリング | 何を聞くか | 命令文 | 2022-2024 |
| コンテキストエンジニアリング | 何を見せるか | 推論時のすべてのトークン | 2025 |
| ハーネスエンジニアリング | 環境をどう設計するか | 外部制約・フィードバック・インフラ | 2026 |
AIエージェント = モデル + ハーネス
「モデルはコモディティ（汎用品）。ハーネスがモート（競争優位の堀）だ」—— 同じモデルでも、ハーネスの差だけでタスク完了率60% vs 98%の開きが生まれる。
| 事例 | 介入内容 | 成果 |
|---|---|---|
| Vercel v0 | ツールを15→2に削減 | 精度80%→100%、トークン-37%、速度3.5倍 |
| LangChain Terminal Bench | ハーネス改善のみ（モデル変更なし） | 52.8%→66.5%（順位30位→5位） |
| OpenAI Codex（5ヶ月間） | 3〜7名でハーネス設計 | PRを1人あたり3.5本/日 |
| Hashline実験 | 行編集フォーマット変更のみ | Grok Code: 6.7%→68.3%（+10倍） |
| Manus | 6ヶ月でハーネスを5回書き直し | 信頼性の継続改善 |
出典: harness-engineering.ai, aakashgupta.medium.com, philschmid.de
ハーネスは1枚の巨大プロンプトではなく、役割の違う複数の層で構成する。
第1層: アイデンティティ層（誰として振る舞うか）
└── CLAUDE.md の基本原則、紅莉栖モード等
└── 更新頻度: 低（月単位）
第2層: ドメイン知識層（何を知っているか）
└── rules/（ファイルパターンで自動注入）、skills、memory
└── 更新頻度: 中（週単位）
第3層: 行動制約層（何をしてはいけないか）
└── hooks（PreToolUse/PostToolUse/Stop で自動チェック）
└── 更新頻度: 中（問題発生時）
第4層: ランタイム状態層（今何をしているか）
└── タスク管理、コンテキスト、進捗追跡
└── 更新頻度: 高（リアルタイム）
第5層: フィードバック層（何を学んだか）
└── memory更新、パターン蓄積
└── 更新頻度: セッション単位
なぜレイヤーに分けるか: 各層の更新頻度が異なるため。人格設定を毎セッション変える必要はないが、タスク状態はリアルタイムで変わる。層を分けることで、必要な部分だけを更新・注入できる。
完全制御 ←────────────────────────→ 完全自律
hookで 構造化 プロンプト 緩い 制約
強制的に テンプレート のルール ガイドライン なし
ブロック で形を固定 で指示 で方向性提示
ベストプラクティス: まず制御寄りで始めて、信頼性が確認できたら徐々に自律度を上げる。 秘書パターンでは、dispatch/検証は制御寄り、文脈収集は自律寄りが適切。
ハーネスに注入するトークンには全てコストがある:
| リソース | コスト | 最適化戦略 |
|---|---|---|
| 指示トークン | 作業に使えるコンテキストが減る | Progressive Disclosure（必要な時だけ詳細を読み込む） |
| メモリトークン | 指示と競合する | 原則を保存、手順は保存しない（手順はコードから再導出可能） |
| hookの実行時間 | ツール呼び出しごとに遅延 | hookはシンプルに。複雑なロジックは外部スクリプトに委譲 |
| サブエージェント | 別コンテキストを消費 | 調査はサブエージェントに、判断はメインコンテキストに |
弱い強制 ←──────────────────────→ 強い強制
自然言語の XML/JSONの hookによる 状態マシンに
お願い テンプレート チェック よる遷移管理
調査で判明した最大の知見: ハーネスの失敗のほとんどは、指示が間違っていたからではなく、強制力が弱すぎたから。「プロンプトに書いた」から「hookで強制する」への移行が、信頼性向上の最大のレバレッジポイント。
（参考: 秘書体制で実証済み。prompt.mdに「検証しろ」と書いても検証せず完了報告した事例 — 2026-03-31）
セッションN: エージェントがミスする
↓
人間が修正する
↓
memoryに修正を記録（理由=WHYと共に）
↓
セッションN+1: memory読み込み → 行動が変わる
↓
それでも失敗 → hookによる強制に昇格
↓
安定的に成功 → プロンプトのみに緩和を検討
失敗 → 学習 → 改善のサイクルを仕組みとして持つ。 個人の記憶力に依存しない。
フィードバックループの理論的背景として、OODA（Observe→Orient→Decide→Act）ループとReflexionフレームワーク（短期記憶＋長期記憶のデュアルアーキテクチャ）が参考になる。ただし「考えすぎ問題」（Overthinking）もあり、フィードバックの深さにはバランスが必要。
出典: tao-hpu.medium.com, humanlayer.dev/blog/skill-issue
エージェントがミスをするたびに、そのミスが二度と起きないようハーネスを改修する。「ミスを直す」のではなく「ミスが生まれない環境を設計する」。
現行の秘書体制では、これがmemory（feedback_*.md）として実装されている。さらに強化するなら、N回同じfeedbackが出たらrules/やhookに昇格させる仕組みが考えられる。
ハーネスはモデルの弱点への仮定を内包する。 モデルが改善されれば、ハーネスも軽量化できる。
設計原則: 削除しやすく設計する。各ハーネスコンポーネントに「なぜ必要か（どのモデルの弱点を補うか）」を記録しておけば、モデル更新時に削除判断ができる。
出典: aakashgupta.medium.com, philschmid.de
ユーザー → オーケストレーター（秘書）
├── Worker A（コーディングセッション）
├── Worker B（調査エージェント）
└── Verifier（オーケストレーター自身 or 別エージェント）
| 役割 | 責任 | やってはいけないこと |
|---|---|---|
| オーケストレーター | 計画、dispatch、検証、報告 | 自分で実作業をする（判断が鈍る） |
| Worker | 指示された作業の実行 | 指示の範囲を超える「改善」 |
| Verifier | 完了条件との照合 | 作業者の自己申告を鵜呑みにする |
メインコンテキスト（高価・有限）→ サブエージェント（安価・使い捨て）
- メインが保持: 判断、進捗、ユーザー嗜好
- サブが担当: 検索、分析、探索
- 戻り値: 圧縮されたサマリーのみ
| パターン | 概要 | 秘書体制との関連 |
|---|---|---|
| Single Agent | 単一エージェント+ツール | 各作業セッション |
| Sequential | A→B→C の順序実行 | dispatch→作業→検証 |
| Parallel | 複数エージェント並列、後で合成 | 複数セッション同時dispatch |
| Loop | 終了条件を満たすまで繰り返し | 検証→再送信ループ |
| Review & Critique | 生成+批評の分離 | Codexレビュー |
| Coordinator | 中央が分解・振り分け | 秘書の中核パターン |
| Human-in-the-Loop | 人間承認チェックポイント | WAIT状態 |
出典: docs.cloud.google.com/architecture
長時間アプリ向けに実証された3役割構成:
重要な洞察: GeneratorとEvaluatorを分離することで、「GAN（敵対的生成ネットワーク = 生成と批評を競わせる手法）的アプローチ」が実現する。Evaluatorを懐疑的にチューニングする方が、Generatorを自己批判的にするより遥かに容易。
秘書体制では: 秘書=Planner（意図整理+作業指示書）、作業セッション=Generator（実装）、秘書の検証フェーズ=Evaluator（完了条件照合）。さらにCodexがEvaluatorの一部を担っている。
出典: anthropic.com/engineering/harness-design-long-running-apps
| 段階 | 方式 | 強度 | 適用場面 |
|---|---|---|---|
| 自己検証 | 同じエージェントが自分の出力をチェック | 弱 | コスト最小だが見落としやすい |
| 交差検証 | 別エージェント/別モデルがチェック | 中 | Codexレビュー等 |
| 自動検証 | プログラムでチェック（テスト、lint） | 強 | 検査可能な条件に最適 |
秘書パターンの最大の失敗モードは 意図のドリフト（元のユーザー指示が委譲の過程で薄まる）。
対策:
ユーザー → 秘書: 高帯域（自然言語、全文脈）
秘書 → Worker: 中帯域（構造化指示）
Worker → 秘書: 低帯域（完了シグナル、簡潔な結果）
Worker → 秘書 の帯域が最も狭いため、秘書がproactiveに結果を確認しに行く必要がある（tmux capture-pane等）。
| 種類 | 内容 | 対策 |
|---|---|---|
| Silent completion | Workerが「完了」と言ったが実際はやっていない | 検証ステップ |
| Intent misinterpretation | Workerが違うことをした | 構造化作業指示書 |
| Partial completion | 70%しかできていない | 完了条件チェックリスト |
| Context loss | 秘書が元の意図を忘れた | 状態の永続化（DB） |
| Cascade failure | ステップ3のエラーが伝播 | チェックポイント/ロールバック |
| レイヤー | 実装 | 役割 |
|---|---|---|
| CLAUDE.md | /Users/aiharataketo/CLAUDE.md |
基本原則、ツール指定、TDD定義、コンテキスト管理 |
| Rules | .claude/rules/ に7ファイル |
ファイルパターン別の自動注入（TypeScript、Cloudflare、秘書、Remotion等） |
| Hooks | settings.json に多数定義 |
SessionStart（紅莉栖モード注入）、Pre/PostToolUse（変換・ブロック）、Stop、Notification（ntfy転送） |
| Skills | 50+スキル | パターンマッチでトリガー（plan-viewer、ffmpeg、TDD等） |
| Memory | 25+メモリファイル | ユーザー嗜好、フィードバック、プロジェクト情報、参照情報 |
| Plugins | 35+プラグイン | スキル/エージェント/フック/MCPの束（remotion-voicevox、codex、plugin-dev等） |
| Scripts | .claude/scripts/ |
自動変換（plan-viewer HTML化）、アイドル監視 |
レイヤード設計が自然に実現されている — CLAUDE.md（原則）→ rules（ドメイン知識）→ hooks（強制）→ memory（学習）の4層が機能している
フィードバックループが回っている — memoryに失敗事例と教訓が蓄積されている（25+件）。特に秘書関連のフィードバックメモリが充実（10件以上）
Progressive Disclosureが効いている — rules/のファイルパターンマッチにより、TypeScriptを触る時だけTypeScriptルールが注入される。全ルールを常時ロードしないのは正しい
3層防御が既に設計済み — secretary-orchestration-bestpractice.md で「構造化プロンプト → 報告テンプレート → hook強制」の設計が完了している
サブエージェント戦略が明確 — Sonnetデフォルト、Opus昇格の判断基準が文書化されている
現状: CLAUDE.mdは約100行で、基本原則からツール指定、TDD定義、外部ツール連携、リポジトリ作成時のルールまで混在している。
問題: 第1層（アイデンティティ）と第2層（ドメイン知識）が混在。「外部ツール連携」「plan-viewer」「リポジトリ作成時」はドメイン知識であり、基本原則と同じ層に置くとコンテキスト消費が増える。
改善案: rules/ へのプロモーション。ファイルパターンでトリガーできるものは rules/ に移す。
plan-viewer 関連 → rules/plan-viewer.md（plan-viewer ファイル操作時のみ注入）リポジトリ作成時 → rules/repo-init.md（.git初期化時のみ）リスク: 移しすぎるとCLAUDE.mdが薄くなり、基本的な振る舞いすら不安定になる可能性。移行は段階的に、1つずつ効果を確認しながら。
現状: 25+メモリファイルがフラットに配置。MEMORY.mdのインデックスは機能しているが、メモリの種類（user/feedback/project/reference）ごとの一覧性が弱い。
問題: メモリ数が増えるとインデックスが長くなり、200行上限に近づく。また、秘書関連のfeedbackメモリが10件以上あり、個別に読むコストが高い。
改善案:
feedback_secretary_consolidated.md）## カテゴリ セクション追加（user / feedback / project / reference）現状: hookは ~/.claude/settings.json に直書き + 各プラグインの hooks.json に分散。
問題:
改善案:
docs/hook-inventory.md を作成: 全hookの一覧表（イベント、条件、動作、解決する問題）現状: 50+スキルが存在し、各スキルのトリガーパターンが description に記載されている。
問題:
改善案:
現状: CLAUDE.md に「50%超えたらcompact提案」のルールがある。
問題: 現在のハーネス全体（CLAUDE.md + 注入されるrules + memory + hookのstdout）が消費するトークン数が可視化されていない。「ハーネスの固定コスト」が不明。
改善案:
/init 等で生成したCLAUDE.mdは有害。一行一行を意図を持って書く| 要素 | 内容 | 例 |
|---|---|---|
| WHAT | 技術スタック、プロジェクト構造 | 「Hono + Cloudflare Workers + D1」 |
| WHY | プロジェクトの目的、各コンポーネントの役割 | 「非エンジニアが電話リマインドを自動化するため」 |
| HOW | ビルド手順、テスト方法、検証フロー | 「tsc → biome → vitest の順で検証」 |
CLAUDE.mdにすべてを詰め込まない。別ファイルに分け、必要なときだけ参照させる:
agent_docs/building_the_project.mdagent_docs/running_tests.mdagent_docs/code_conventions.md出典: humanlayer.dev/blog/writing-a-good-claude-md, humanlayer.dev/blog/skill-issue
コンテキスト長が増えると性能が劣化する。質問とコンテキストの意味的類似度が低いほど劣化が急峻。ツール呼び出し・ファイル読み込み・中間結果の積み重ねが複合的にノイズを増やす。コンテキストウィンドウを大きくしても解決しない（haystack=干し草の山が大きくなるだけ）。
大きな結果をコンテキストに詰め込まず、write_file でセッション固有の一時ストレージにバッファリング。コンテキストにはポインタ（ファイルの場所と説明）のみ残す。
→ 秘書体制では、サブエージェントの結果を一時ファイルに書いてサマリーだけ返す設計に相当。
| 戦略 | 概要 | 秘書体制での対応 |
|---|---|---|
| コンテキストリセット | 新鮮なコンテキストで新エージェント起動。構造化引き継ぎ | session-bootstrapエージェント |
| コンパクション | 古い会話履歴を要約・圧縮 | 手動 /compact + Obsidian書き出し |
| 動的サブエージェント | タスクを独立スレッドに分離。要約のみ親に返す | サブエージェント委譲（Sonnetデフォルト） |
重要: Opus 4.5以降は「コンテキスト不安」の挙動が改善されている。ハーネスの複雑さはモデルの進化とともに軽減できる（原則7: Build to Delete）。
出典: anthropic.com/engineering/harness-design-long-running-apps, amplifypartners.com
最も重要な指摘: 「最もシンプルなアーキテクチャで目的を達成せよ」
OpenAIはCodexの運用を通じて「ハーネスエンジニアリング」を公式に提唱（2026年）。3〜7名のチームが5ヶ月でハーネス設計に集中し、1Mラインのコードを生成、PRを1人あたり3.5本/日のペースで処理。
「シッピングへのバイアス」原則: ハーネスの設定は、エージェントが実際に失敗したときにだけ行う。事前の理想設計はしない。
出典: openai.com/index/harness-engineering, martinfowler.com, anthropic.com/engineering, humanlayer.dev
| やること | 方法 | 目的 |
|---|---|---|
| ハーネス固定コストの計測 | 全注入テキストのトークン数を計算 | 「何%がハーネスに使われているか」の現状把握 |
| hookインベントリ作成 | settings.json + 全プラグインのhooks.json を一覧化 | 「何が何を防いでいるか」の可視化 |
| メモリ棚卸し | 全memoryファイルの最終更新日と内容をレビュー | 古い/重複/解決済みの特定 |
| やること | 方法 | 目的 |
|---|---|---|
| CLAUDE.mdのスリム化 | ドメイン知識をrules/に段階的にプロモーション | 第1層と第2層の分離 |
| メモリ統合 | 秘書feedbackメモリ10件→1-2件に統合 | インデックス圧縮 |
| トリガーパターン監査 | skill-evaluatorで全スキルのdescriptionを評価 | 誤トリガー防止 |
secretary-orchestration-bestpractice.md の Phase 1 が未実装なら、そこが最優先:
ハーネスエンジニアリングの核心は、以下の3つのバランスを取ること:
~/plans/secretary-orchestration-bestpractice.md — 秘書の検証フレームワーク設計（v3）~/plans/telegram-secretary-design.md — Telegram秘書アーキテクチャ設計