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に固定する 失敗を制約に変換するまでが実装だ （ラチェット原則）
6. HARNESS ENGINEERING DESIGN CLAUDE.md 60 行が上限 情報量が増えるほど 遵守率は下がる CLAUDE.MD 守られる設計は 「短く・構造的」 であること 優先度順に並べる（重要なルールを上部に） 例外より原則を明示する 「してはいけないこと」より「すべきこと」を書く セクション分けで認知負荷を下げる 定期的に削除する（追記だけしない） 60行を超えると遵守率は急落する。 削除すること自体が重要な編集行為。
7. HARNESS ENGINEERING DESIGN EXTERNAL STATE コンテキストに状態を持たせない。 外部ファイルで忘却を設計的に防ぐ 設計の原則 ⚫ 状態をコンテキストに持たせない ⚫ 外部化で「忘却」を設計的に防ぐ ⚫ 状態は外に、文脈は中に ⚫ これがハーネス設計の基本構造 # Project: ••プロジェクト ## 現在の状態 - [x] Phase 1: Requirement Analysis & Framework Definition - [/] Phase 2: Content Generation (Slides 1-5 completed) - [ ] Phase 3: Technical Quality Check (slide-quality) - [ ] Phase 4: Final Reflect & Export ## 原則と制約 - Font: Minimum 12pt (Global Rule: slide-quality §1) - Template: Pollux-v2 (Implementation: slide-pollux) - KM Style: Declarative with te-form (Discipline: CLAUDE.md) ## 次のステップ 1. Generate Slide 6: "Ratchet Principle" logic. 2. Run `quality_check()` for P1-P6. 3. Fix potential False Positives in PH shapes (Pollux specific). MEMORY.md MEMORY.md の役割 ⚫ 状態・進捗・決定事項を記録する ⚫ セッション間のブリッジとして機能 ⚫ 「作業の地図」として迷子を防ぐ ⚫ 状態の完全な復元が可能になる
8. HARNESS ENGINEERING DESIGN 01 02 第1層 ファイルシステム制御 allowedDirectories 読み書き範囲を 物理的に限定する 第2層 コマンド制御 allowedCommands 実行可能コマンドを明示的に限定する 03 第3層 ネットワーク制御 allowedDomains 通信先ドメインを 物理的に制限する ルールに頼らない安全設計 settings.jsonが担う3層の物理的権限制御 「やってはいけない」と書くのではなく、「できない」構造にすることが安全設計 「やってはいけない」と書くのではなく、「できない」構造にすることが安全設計 { "agent": { "permissions": { // 第1層：ファイルシステム制御（読み書き範囲を限定） "allowedDirectories": [ "./src/slides", "./templates/pollux", "./output" ], // 第2層：コマンド制御（実行可能コマンドを厳選） "allowedCommands": [ "python3 scripts/generate_slide.py", "npm run quality-check", "git add", "git commit" ], // 第3層：ネットワーク制御（通信先をホワイトリスト化） "allowedDomains": [ "api.anthropic.com", "github.com", "internal-knowledge-base.local" ] } } settings.json
9. HARNESS ENGINEERING DESIGN OBSERVABILITY エージェントの内部挙動を可視化する 成功は静粛に、失敗は詳細に 01 成功は静粛に 非対称ログ設計 ⚫ 正常時はログを最小化する ⚫ ノイズを排除し信号を際立たせる ⚫ 「静粛」が信号の質を上げ ⚫ 本当の問題を浮かび上がらせる 02 失敗は詳細に エラー文脈の保全 ⚫ エラー時は文脈をすべて記録する ⚫ 再現性の高い調査が可能になる ⚫ エラーの文脈が再現性を生み ⚫ 調査コストを大幅に削減する 03 フックを活用 PreToolUse / PostToolUse ⚫ タイミング制御と実行への介入 ⚫ 非侵襲的な監視が実現できる ⚫ AIの挙動を外から可視化する ⚫ 規律監視に最も適した仕組み 04 状態を追跡 継続的品質改善 ⚫ 入力・出力・決定を記録する ⚫ ドリフトを早期に検知できる ⚫ 記録が問題の早期発見を可能にし ⚫ 品質の継続的な改善を支える // PreToolUse: 実行前に規律(CLAUDE.md)との適合性をチェック export function preToolUse(toolName, args) { if (toolName === "filesystem_write" && !args.path.endsWith(".md")) { console.warn(`[WATCHDOG] Discipline Violation: Writing to non-markdown file detected.`); return { abort: true, reason: "CLAUDE.md Section 3 restricts direct file writes to .md only." }; } return { abort: false }; } // PostToolUse: 失敗時にエラー文脈を詳細に記録（非対称ログ設計） export function postToolUse(toolName, result) { if (result.status === "error") { save_detailed_context({ tool: toolName, error: result.error, full_prompt_snapshot: getCurrentContext(), // エラー時の文脈をすべて記録 timestamp: Date.now() }); } } hooks/validation_gate.js "observability": { "logLevel": "error_detailed" // 成功は静粛に、失敗は詳細に } settings.json
10. HARNESS ENGINEERING DESIGN Generator WORKFLOW ハーネスを活用したHITLワークフローの例 1.Initialization 方針/環境定義 2.Planning 計画設定 3.Generation ガード下の自律生成 4.Evaluation 第三者の検証/品質保証 5.Finalization 最終判断とふりかえり HUMAN (ORCHESTRATOR) 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
11. HARNESS ENGINEERING DESIGN 1 3 AI時代における キャリアアップ の注力点 生きた経験を持つ唯一の存在 として独自の価値を発揮する 経験知の統合 最終的な責任を持つ リスクと不確実性を 人間が引き受ける A 価値定義 何が重要かを最初に決める AIは「何でも可能」だが 方向は人間が与える 「何のため」かを定義する ことがAIを活かす前提条件 最終判断 人間はAIが担えない領域に集中する 2 HUMAN IN THE LOOP
12. HARNESS ENGINEERING DESIGN