Claude Code Harness Design - AIエージェントを制御し続けるための実践ガイド

「指示する前に、動かざるを得ない環境を設計する」

AIエージェントの本番導入において、多くのプロジェクトが直面する「コンテキストの汚染」「出力の不安定化」「作業の巻き戻し」。その原因はモデルの性能不足ではなく、AIを取り囲む「ハーネス（環境制御）」の欠陥にあります。

本資料では、Claude CodeをはじめとするAIエージェントを実務で安定稼働させるための「ハーネスエンジニアリング」の設計思想と具体手法を体系化しました。プロンプトを書き足すだけのアプローチから脱却し、構造的にAIを制御するための実践的なガイドです。

Transcript

1. HARNESS ENGINEERING DESIGN AIエージェントを制御し続けるための実践ガイド 国家資格キャリアコンサルタント 為安 圭介 Claude Code Harness Design
2. HARNESS ENGINEERING DESIGN 01 — 環境設計 DESIGN 指示する前に、動かざるを得ない環境を設計する 従来アプローチ 詳細プロンプト + 事後チェック ⚫ ルールを書き足す ⚫ AIが読み飛ばすリスクが常にある ⚫ 問題が起きてから対応する反応型設計 ⚫ 毎回微調整 現在 ハーネス設計（環境制御） ⚫ settings.jsonで物理的な権限を制御する ⚫ SKILL.mdでエージェントの行動を構造化 ⚫ CLAUDE.mdで文脈・規律をセッションを超えて固定 02 / 12 ⚫ コスト増・品質不安定・再現性ゼロ
3. HARNESS ENGINEERING DESIGN 01 03 02 Schema Misalignment State Degradation Context Drift 状態が管理されず 作業が巻き戻る 状態をコンテキスト外で管理しない限り 完了タスクが再実行される 期待する出力形式と AIの理解がずれる 明示的なスキーマ指定を行わない限り パース不能な応答 指示内容が会話の中で 少しずつ変質する 長いセッションほど深刻化し 設計的な固定がない限り 情報は必ず流れる 88%が本番フェーズで失敗する。 その原因はモデルではなくハーネスの欠陥にある コンテキスト汚染 スキーマ不整合 状態劣化
4. HARNESS ENGINEERING DESIGN ⚫ タスクを分解し優先順位を決める ⚫ 「何を・どの順で」を設計する ⚫ Generatorへ明確な指示を生成する Planner ⚫ Plannerの指示のみ実行し生成に専念 ⚫ 自己評価・修正は行わない ⚫ 「生成のみ」への集中が品質を安定 Generator ⚫ 生成結果の品質を独立して検証する ⚫ 合否判定と改善提案を行う ⚫ 独立評価が客観性を保証する Evaluator 生成と評価を同じエージェントに 担わせると 品質劣化は構造的に起きる
5. HARNESS ENGINEERING DESIGN 01 02 03 STEP 1 失敗を検知する ⚫ 制約を恒久化する ⚫ 次のセッションへ ⚫ 自動で引き継がれる ⚫ ラチェットが後退を防ぐ ⚫ ログとフックで ⚫ 異常を捕捉する ⚫ エラーパターンを ⚫ 記録・分類する ⚫ 再発防止ルールを ⚫ 定義する ⚫ settings.jsonに ⚫ 物理的に反映する STEP 2 制約に変換する STEP 3 skill.mdに固定する 失敗を制約に変換するまでが実装だ ラチェット原則の3ステップ
6. HARNESS ENGINEERING DESIGN CLAUDE.md 60 行が上限 情報量が増えるほど 遵守率は下がる CLAUDE.MD 守られる設計は 「短く・構造的」 であること 優先度順に並べる（重要なルールを上部に） 例外より「原則」を明示する 「してはいけないこと」より「すべきこと」を書く セクション分けで認知負荷を下げる 定期的に削除する（追記だけしない） 60行を超えると遵守率は急落する。 削除することが、最も重要な編集行為。
7. HARNESS ENGINEERING DESIGN EXTERNAL STATE コンテキストに状態を持たせない。 外部ファイルで忘却を設計的に防ぐ todo.md の役割 状態・進捗管理 ⚫ 状態・進捗・決定事項を記録する ⚫ セッション間のブリッジとして機能 ⚫ 「作業の地図」として迷子を防ぐ ⚫ 状態の完全な復元が可能になる 実装パターン 運用ルール ⚫ セッション冒頭に必ず読み込む ⚫ 完了タスクは即チェックで整合性を保つ ⚫ セッション再開時に状態を即座に復元 ⚫ 書き込みルールを明文化しておく コンテキスト圧縮対処 忘却設計 ⚫ 圧縮されても外部ファイルは残る ⚫ 再起動時に状態を完全に復元できる ⚫ 外部化が忘却を防ぐ唯一の設計手段 ⚫ 内部記憶には頼らない設計原則 設計の原則 基本構造 ⚫ 状態をコンテキストに持たせない ⚫ 外部化で「忘却」を設計的に防ぐ ⚫ 状態は外に、文脈は中に ⚫ これがハーネス設計の基本構造
8. HARNESS ENGINEERING DESIGN SETTINGS ルールに頼らない安全設計 3層の物理的権限制御 「やってはいけない」と書くのではなく、「できない」構造にすることが安全設計 01 LAYER 01 ファイルシステム制御 allowedDirectories 読み書き範囲を 物理的に限定する 02 LAYER 02 コマンド制御 allowedCommands 実行可能コマンドを 明示的に限定する 03 LAYER 03 ネットワーク制御 allowedDomains 通信先ドメインを 物理的に制限する 04 PRINCIPLE 最小権限の原則 最小権限で 構造的に制御する ルールより構造が 確実に安全 05 APPLY settings.jsonへ記述 再起動で即座に有効化 3層すべてを設定して 物理的安全が実現する 3層を設定して初めて「物理的な安全」が実現する 08 / 12
9. HARNESS ENGINEERING DESIGN 01 02 第1層 ファイルシステム制御 allowedDirectories 読み書き範囲を 物理的に限定する 第2層 コマンド制御 allowedCommands 実行可能コマンドを明示的に限定する 03 04 第3層 ネットワーク制御 allowedDomains 通信先ドメインを 物理的に制限する 設計原則 最小権限の原則で 構造的に制御する ルールより構造が確実に安全 05 適用方法 settings.jsonに 明示的に記述する ルールに頼らない安全設計 settings.jsonが担う3層の物理的権限制御 「やってはいけない」と書くのではなく、「できない」構造にすることが安全設計 「やってはいけない」と書くのではなく、「できない」構造にすることが安全設計 3層を設定して初めて「物理的な安全」が実現する
10. HARNESS ENGINEERING DESIGN OBSERVABILITY エージェントの内部挙動を可視化する 成功は静粛に、失敗は詳細に 01 成功は静粛に 非対称ログ設計 ⚫ 正常時はログを最小化する ⚫ ノイズを排除し信号を際立たせる ⚫ 「静粛」が信号の質を上げ ⚫ 本当の問題を浮かび上がらせる 02 失敗は詳細に エラー文脈の保全 ⚫ エラー時は文脈をすべて記録する ⚫ 再現性の高い調査が可能になる ⚫ エラーの文脈が再現性を生み ⚫ 調査コストを大幅に削減する 03 フックを活用 PreToolUse / PostToolUse ⚫ タイミング制御と実行への介入が可能 ⚫ 非侵襲的な監視が実現できる ⚫ AIの挙動を外から可視化する ⚫ 規律監視に最も適した仕組み 04 状態を追跡 継続的品質改善 ⚫ 入力・出力・決定を記録する ⚫ ドリフトを早期に検知できる ⚫ 記録が問題の早期発見を可能にし ⚫ 品質の継続的な改善を支える
11. HARNESS ENGINEERING DESIGN 1 3 AI時代の 人間の価値 文脈と過去を織り込む AIは過去の学習に限定される 生きた経験を持つ唯一の存在 として独自の価値を発揮する 経験知の統合 最終的な責任を持つ リスクと不確実性を 人間が引き受ける AIに委ねられない意思決定が 必ず存在する 価値定義 何が重要かを最初に決める AIは「何でも可能」だが 方向は人間が与える 「何のため」かを定義する ことがAIを活かす前提条件 最終判断 AIが担えない3つの領域 価値定義・経験・最終判断に 人間が集中する根拠 2 HUMAN IN THE LOOP
12. HARNESS ENGINEERING DESIGN Generator WORKFLOW ハーネスを活用したHITLワークフローの例 1.Initialization 方針/環境定義 2.Planning 計画設定 3.Generation ガード下の自律生成 4.Evaluation 第三者の検証/品質保証 5.Finalization 最終判断とふりかえり HUMAN (ORCHESTRAT OR) Environment Skills AI (ENGINE) HARNESS 規律読込 （CLAUDE.md） 動作境界定義 (setting.json) ⚫ 目的(Goal) ⚫ 背景(Context） ⚫ 制約(Constraints) ⚫ 目標と完了条件 (Acceptance Criteria) 動的文脈記憶 （MEMORY.md) Hooks (計画チェック) Hooks (自動テスト) /compact (メモリ要約圧縮) Planner Evaluator MEMORY.md （メモリ更新） Hooks (フィードバック) 最終判断 介入ポイント 規律更新（ラチェット原則） Skills (生成スキル) MCP (外部ツール) Skills (計画スキル) Skills (検証スキル) 成果物 CLAUDE.md （規律更新） ヘルプリクエスト （基準を超える場合） 規律制御 (コンテキスト内) Approval
13. HARNESS ENGINEERING DESIGN