Harness Engineering 2026年4月12日

ハーネスエンジニアリング完全ガイド

AIエージェントに「秩序」を与えて出力品質を最大化するハーネスエンジニアリングを体系的に解説。省伍フレームワーク6層レイヤーと英語圏の最新定義を統合し、実装パターンからカリキュラムまで網羅します。

#harness-engineering #ai-agent #claude-code #agents-md #guardrails #ci-cd

ハーネスエンジニアリングとは

ハーネスエンジニアリングとは、AIエージェントに**「自由」ではなく「秩序」を与える**ことで、開発における出力品質・一貫性を最大化する手法です。

「ハーネス」の語源は馬具（手綱）のメタファーに由来します。馬の力を最大限に引き出しつつ、意図した方向に導くための仕組み。AIエージェントにとってのハーネスとは、モデル自身を除いたエージェントのすべて——ツール、ルール、ドキュメント、テスト、フィードバックループ——を指します。

Agent = Model + Harness

プロンプト・コンテキストエンジニアリングとの三層構造

レイヤースコープ主な関心事
プロンプトエンジニアリング1回のプロンプト「何をどう聞くか」
コンテキストエンジニアリングコンテキストウィンドウ全体「何を渡し、何を渡さないか」
ハーネスエンジニアリングエージェントの実行環境全体「どう制約し、どう検証し、どう改善するか」

プロンプトとコンテキストが「入力の設計」だとすれば、ハーネスは「エージェントが動く環境全体の設計」です。

なぜ今ハーネスエンジニアリングが必要か

AIエージェントが長時間自律稼働する時代

2026年、AIエージェントはもはや「1回の質問に答える」存在ではありません。Claude Code、GitHub Copilot Workspace、OpenAI Codexは、数時間にわたってコードを読み、書き、テストし、デプロイまで行います。

Anthropicの研究では、長時間実行エージェントの核心的な問題を「シフト制で働く設計士チーム」に例えています。各シフトのメンバーは前のシフトの記憶がない。この制約の中で一貫した成果を出すには、環境側の設計が不可欠です。

プロンプト・コンテキスト設計だけでは解決できない問題

  • エージェントがテストなしで機能完了を宣言する
  • 一度に複数の機能に手を出し、半実装の状態で放置する
  • プロジェクト全体の早期完了を誤宣言する
  • 起動方法の解析に無駄な時間を消費する

これらはプロンプトの書き方では解決できません。CI/CD、テスト戦略、進捗管理の仕組みなど、環境レベルの制御が必要です。

業界の動向

  • Mitchell Hashimoto（HashiCorp創業者）: 2026年2月、「エージェントが失敗するたびに、同じ失敗を二度としないよう設定を工夫する」というハーネスエンジニアリングの概念をブログで提唱
  • OpenAI: Codexエージェントで100万行以上のコードを人間の手書きゼロで出荷。厳格なハーネス設計により実現
  • Anthropic: 長時間実行エージェントのハーネス設計パターンを研究・公開
  • LangChain: ハーネス変更のみ（モデル変更なし）でTerminal Bench 2.0のスコアを52.8%から66.5%に向上

6層レイヤーフレームワーク（省伍定義）

AIエージェントのハーネスを6つの層で体系化したフレームワークです。

第1層: 基盤層（言語・フレームワーク・ライブラリ選定）

エージェントが作業する「素材」を定義する層です。技術スタックの選定がエージェントの出力品質に直結します。

チェックリスト:

  • プロジェクトで使用する言語・フレームワークが明確に定義されている
  • パッケージマネージャとバージョンが固定されている
  • 依存ライブラリの選定基準が文書化されている

第2層: 品質層（コーディング規約・命名規則・データモデリング）

コードの「見た目」と「構造」を統一する層です。ESLint、Prettier、型定義ファイルなどがここに該当します。

チェックリスト:

  • 命名規則が定義されている（camelCase / PascalCase / kebab-case）
  • コーディング規約がlinterで自動チェックされる
  • データモデル（DB設計、型定義）が集約管理されている

第3層: 設計層（アーキテクチャ設計）

CLAUDE.mdやAGENTS.mdで「このプロジェクトはこう設計されている」を伝える層です。エージェントがコードベースの全体像を把握するための地図です。

チェックリスト:

  • CLAUDE.md / AGENTS.mdにアーキテクチャの概要が記載されている
  • ディレクトリ構成の意図が説明されている
  • モジュール間の依存方向が定義されている

第4層: 共同層（TDD・Issue/PRテンプレート）

エージェントと人間が「どう協働するか」のプロトコルを定義する層です。

チェックリスト:

  • テストファーストのワークフローが定義されている
  • Issue / PRのテンプレートが整備されている
  • コミットメッセージの規約が明確

第5層: ガードレール層（CI/CD自動チェック・AIコードレビュー）

エージェントの出力を自動検証するフィードバックループの層です。Martin Fowlerの分類では「センサー（フィードバック）」に相当します。

チェックリスト:

  • 型チェック・ビルドがCIで自動実行される
  • テストカバレッジの閾値が設定されている
  • AIコードレビュー（またはlintルール）が有効

計算型センサー（決定論的・高速）:

  • リンター、フォーマッター
  • 型チェッカー
  • ユニットテスト

推論型センサー（非決定論的・セマンティック分析）:

  • AIコードレビュー
  • アーキテクチャ適合性チェック

第6層: 慣習層（Skills・ナレッジ共有）

チームの暗黙知を形式知化し、エージェントに伝達する層です。スキルファイル、ナレッジベース、ベストプラクティス集がここに該当します。

チェックリスト:

  • よく使うワークフローがスキルとして定義されている
  • 過去の失敗パターンがドキュメント化されている
  • チーム固有のベストプラクティスが共有可能な形式で存在する

英語圏の定義との統合・比較

OpenAI Codexチームのアプローチ

OpenAIは2026年初頭、Codexエージェントを使って100万行以上のコードを人間のコード記述ゼロで内部プロダクトを構築・出荷しました。その核心は厳格なハーネス設計にあります。

Anthropicのlong-running agentハーネス

Anthropicの研究が提案する二段階ソリューション:

  1. 初期化エージェント: 環境セットアップ専用。init.shスクリプト、claude-progress.txt（進捗ログ）、初期Gitコミットを生成
  2. コーディングエージェント: 各セッションで「単一機能のみ」に集中。セッション開始時にGitログと進捗ファイルを読み込み、セッション終了時に構造化された更新を記録

特筆すべき知見として、機能リストをJSON形式で管理することが推奨されています。「モデルはMarkdownと比較してJSONファイルを不適切に変更・上書きする可能性が低い」ためです。

Martin Fowlerの分類

Martin Fowlerのチームは、ハーネスを「フィードフォワード（予防的制御）」と「フィードバック（修正的制御）」に分類しています。

  • ガイド（フィードフォワード）: エージェントが行動する前に望ましくない出力を予防する仕組み。CLAUDE.md、ルールファイル、スキル等
  • センサー（フィードバック）: エージェントが行動した後に観察し、自己修正を支援する仕組み。テスト、型チェック、AIレビュー等

省伍フレームワークとの共通点・相違点

観点省伍フレームワーク英語圏の定義
構造6層レイヤーで体系化Agent = Model + Harness のシンプルな二分法
範囲技術選定からナレッジ共有まで包括主にツール・ルール・フィードバックに集中
共通点フィードバックループの重視フィードバックループの重視
共通点ドキュメントによる制約の形式知化AGENTS.md / CLAUDE.md による制約定義
特徴「慣習層」でチームの暗黙知を扱うETHチューリッヒ研究に基づく定量的な知見

実装パターン集

CLAUDE.md / AGENTS.md 設計

ETHチューリッヒの138エージェントファイル分析から得られたベストプラクティス:

  • 60行以下の簡潔な内容に保つ
  • 普遍的に適用可能な指示のみ記載（条件付きルールが多いと逆効果）
  • LLM生成ではなく人間が作成する（LLM生成はトークン消費が20%以上増加し性能低下）
  • 定期的に更新する（エージェントが失敗するたびに改善）
# プロジェクト規約
## 技術スタック
- Astro 6.x + React + TypeScript
- Vitest でテスト

## 開発コマンド
npm run dev / npm run build / npm run check

## アーキテクチャ
- src/content/ : コンテンツコレクション
- src/components/ : UIコンポーネント
- src/utils/ : ユーティリティ関数

## 規約
- Conventional Commits形式
- TDD必須
- 1ファイル1責務

Skills / Rulesファイル設計

スキルは「段階的知識開示」の仕組みです。常にコンテキストに載せるのではなく、必要な時だけ活性化します。

skills/
├── frontend-review/
│   ├── SKILL.md          # 主要な説明
│   └── checklist.md      # レビューチェックリスト
├── tdd-workflow/
│   ├── SKILL.md
│   └── test-patterns.md
└── deploy/
    ├── SKILL.md
    └── cloudflare-config.md

CI/CDガードレール構成

バックプレッシャーメカニズムの設計原則:

  • 成功は沈黙、失敗のみ出力: テストスイートの全出力をエージェントに渡すとコンテキストを圧迫する。エラーのみをサーフェスする
  • 段階的実行: コミット前は高速な計算型チェック（lint、型チェック）、統合前はより高度な検証
  • カバレッジ監視: テストカバレッジが低下した場合にエージェントに通知
# GitHub Actions例
- name: Type Check
  run: npm run check
- name: Unit Tests
  run: npm test -- --reporter=verbose 2>&1 | tail -50
- name: Build
  run: npm run build

長時間エージェント向けハーネス設計

Anthropicの研究に基づく、マルチセッション対応の設計:

  1. 進捗ファイル(claude-progress.txt): 各セッション終了時に構造化された更新を記録
  2. 機能リスト（JSON形式）: 全機能を列挙し、初期状態を「未完了」に設定
  3. 単一機能集中: 1セッション1機能。複数機能の並行実装を禁止
  4. セッション開始プロトコル: Gitログ読み込み → 進捗確認 → 次の機能選定 → 開発サーバー起動

カリキュラム構成案

初級（個人開発でAIを使い始めた人向け）

  1. CLAUDE.md / AGENTS.md の作成と基本構成
  2. コーディング規約のlinter設定
  3. テストファーストのワークフロー確立
  4. コミットメッセージ規約の導入

中級（チーム開発でAI導入する人向け）

  1. スキルファイルの設計と段階的知識開示
  2. CI/CDパイプラインでのガードレール構築
  3. PRテンプレートとコードレビュー自動化
  4. MCPサーバーの適切な選択と設定

上級（エージェントシステムを本番運用する人向け）

  1. マルチエージェントのコンテキスト分離設計
  2. 長時間実行エージェントのセッション管理
  3. フィードフォワード/フィードバックの二層設計
  4. ハーネステンプレートの標準化とチーム展開

導入チェックリスト

レイヤーチェック項目状態
基盤層言語・FWが明確に定義されている
基盤層パッケージバージョンが固定されている
品質層linter / formatter が設定されている
品質層型定義が集約管理されている
設計層CLAUDE.md / AGENTS.md が存在する
設計層ディレクトリ構成の意図が説明されている
共同層TDDワークフローが定義されている
共同層PR / Issueテンプレートが整備されている
ガードレール層CIで型チェック・テストが自動実行される
ガードレール層テストカバレッジの閾値が設定されている
慣習層スキルファイルが整備されている
慣習層失敗パターンがドキュメント化されている

参考リンク集