学べる内容

このガイドでは、第一原理から実践的な実装まで、ハーネスエンジニアリング（harness engineering）について解説します。ハーネスエンジニアリングとは何か、なぜ OpenAI が社内最大のプロジェクトをこれに賭けたのか、それを機能させる具体的なアーキテクチャパターン、そして Codex、Claude Code、OpenCode、あるいはその他の agent システムを使用しているかに関わらず、これらの原則を自身の AI agent ワークフローにどのように適用すべきかを理解することができます。

ハーネスエンジニアリング：2026年における AI agent 開発の完全ガイド

2025年が AI agents がコードを書けることを証明した年であったなら、2026年は、困難なのは agent そのものではなく、ハーネス（harness）であるということを学んだ年です。

OpenAI の Codex チームは 2026年 2月、人間の手によるコードが一行も書かれていない、約 100万行のコードを含むプロダクションアプリケーションをどのように構築したかを説明する画期的なブログ記事を公開しました。その秘訣は、より優れたモデルでも、よりスマートなプロンプトでもありませんでした。それは、agent の周囲に構築したシステム、すなわち「ハーネス」でした。Source

このガイドでは、その実験から得られたあらゆる原則、パターン、実践的なテクニック、そしてそこから生まれた広範なハーネスエンジニアリングの動向を分解して解説します。

パート 1：ハーネスエンジニアリングとは何か？

定義

ハーネスエンジニアリングとは、AI coding agents が最小限の人間の介入で、大規模かつ信頼性の高い高品質な作業を行えるようにするための環境全体（スキャフォールディング、フィードバックループ、ドキュメント、アーキテクチャ上の制約、およびマシン読み取り可能なアーティファクト）を設計する規律のことです。

「ハーネス（harness）」という言葉は、馬具（手綱、鞍、ビットなど）に由来します。これは、強力だが予測不可能な動物を正しい方向に導くための装備一式を指します。制御されていない馬は危険ですが、ハーネスを装着した馬は文明を築きました。同じことが AI agents にも当てはまります。Source

なぜ今登場したのか

プロンプトエンジニアリングからハーネスエンジニアリングへの移行は、AI 開発環境の成熟を反映しています。

Source

この移行を促した重要な洞察は、agents が十分に有能になったことで、ボトルネックがモデルの品質から環境の品質へと移ったことです。構造化が不十分なリポジトリで動作する最先端モデルは、適切にハーネスされた環境で動作する並のモデルよりも悪い結果をもたらします。

パート 2：OpenAI Codex の実験

スケール

5ヶ月間にわたる社内実験において、OpenAI のエンジニアは約 100万行のコードを含むベータ製品を構築し、リリースしました。リポジトリは、アプリケーションロジック、インフラストラクチャ、ツーリング、ドキュメント、および社内開発者用ユーティリティに及びます。システムを固定するための、人間が書いた既存のコードは一切存在しませんでした。Source

チーム

プロジェクトは、Codex を動かすわずか 3人のエンジニアから始まりました。5ヶ月間で約 1,500 の pull requests が作成され、マージされました。チームが 7人のエンジニアに増えるにつれて、スループットが向上しました。これは、個人のスキルではなく、ハーネス自体が主要な生産性倍増装置であったことを示唆する、直感に反する結果でした。

OpenAI は、手書きでコードを書く場合と比較して、約 10分の 1の時間でシステムを構築したと推定しています。Source

初期のスキャフォールド

プロジェクトは、GPT-5 を使用して初期のスキャフォールドを生成する Codex CLI から始まり、少数の既存テンプレートに従って進められました。

• リポジトリ構造とディレクトリの規約
• CI/CD 設定
• コードフォーマットとリンティングルール
• パッケージマネージャーのセットアップ
• アプリケーションフレームワークのボイラープレート

この種火から、それ以外のすべてが agent 主導の開発を通じて成長していきました。

金曜日の問題

実験の初期段階で、チームは重大な問題を発見しました。彼らは毎週金曜日、つまりエンジニアリング時間の 20% を、「AI slop（AI による質の低い成果物）」と呼ぶものの片付けに費やしていました。これには、一貫性のないパターン、重複したロジック、誤った変数名、アーキテクチャの逸脱が含まれていました。

これではスケールしません。解決策は、自分たちの基準をハーネス自体にエンコードして agents が最初からクリーンな出力を生成するようにすること、そして残留した逸脱のための自動クリーンアップシステムを構築することでした。

パート 3：5つの核心原則

原則 1：リポジトリ優先の知識

agent の視点からは、実行中にコンテキスト内でアクセスできないものは、事実上存在しません。Google Docs、チャットのスレッド、Slack のメッセージ、あるいは人々の頭の中にある知識は、システムからは見えません。

これは、すべての知識がリポジトリ内のローカルでバージョン管理されたアーティファクトとして存在しなければならないことを意味します。

• コード — 主要なアーティファクト
• Markdown ドキュメント — アーキテクチャの決定、規約、オンボーディングガイド
• スキーマ — API コントラクト、データベーススキーマ、型定義
• 実行可能な計画 — agent が従うことができるステップバイステップのタスク分解
• 設定 — リンタールール、CI パイプライン、フォーマット基準

チームは、時間の経過とともにより多くのコンテキストをリポジトリに投入する必要があることを学びました。agent がコンテキスト不足でミスをするたびに、その修正はより良いプロンプトではなく、リポジトリへのコンテキストの追加でした。Source

実践的な実装例：

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

原則 2：ゴールデン・プリンシパル（黄金原則）

ゴールデン・プリンシパルとは、将来の agent の実行においてコードベースの可読性と一貫性を保つために、リポジトリに直接エンコードされた、意見が反映された機械的なルールです。これらは単なる努力目標ではなく、強制される制約です。

OpenAI の実験からの例：

1. 手作りのヘルパーよりも共有ユーティリティパッケージを優先する — 不変条件を中央集約化し、動作を変更する必要があるときに 1箇所で変更できるようにします。
2. YOLO（行き当たりばったり）なデータ探索をしない — 境界を検証するか、型定義された SDK に依存することで、agents が推測されたデータの形状に基づいて誤って構築することを防ぎます。
3. 1つのコンセプトに 1つのファイル — 各ファイルは単一のコンセプトを表すべきであり、これにより agents が適切な場所を見つけ、修正することが容易になります。
4. 暗示的ではなく明示的に — agent が理解するために部族的な知識（暗黙知）を必要とするような、マジック的な挙動を避けます。

Source

これらの原則は単なるドキュメントではありません。以下によって強制されます。

• リンタールール — 違反をフラグ立てするカスタムリンター（これら自体も Codex によって生成されます）。
• 構造テスト — アーキテクチャの準拠を検証するテスト。
• CI ゲート — ゴールデン・プリンシパルに違反する pull requests は自動的に拒否されます。

原則 3：機械的な強制力を伴うレイヤードアーキテクチャ

OpenAI プロジェクトの各ビジネスドメインは、厳密に検証された依存方向を持つ、固定されたレイヤーセットに分割されています。

Types → Config → Repo → Service → Runtime → UI

依存関係は一方向にのみ流れます。UI コンポーネントは Runtime や Service に依存してもよいですが、Service が UI からインポートすることは決してありません。Repo は Config や Types に依存してもよいですが、Service に依存することはありません。Source

これらの制約は機械的に強制されます。

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

構造テストはコンプライアンスを検証し、モジュール型レイヤーの違反を防ぎます。これは単なる提案ではなく、CI によって強制されます。人間が作成したか agent が作成したかに関わらず、すべての pull request はこれらのテストに合格する必要があります。

原則 4：自動ガベージコレクション

ゴールデン・プリンシパルや構造的な強制があっても、agent が生成したコードは時間の経過とともに逸脱していきます。OpenAI チームは、自動ガベージコレクションを実装することでこれを解決しました。これは、以下のことを行う定期的なバックグラウンドタスクです。

1. コードベース全体をスキャンし、ゴールデン・プリンシパルからの逸脱を検出する。
2. 準拠スコアに基づいて、各モジュールの品質グレードを更新する。
3. 特定のカテゴリーの逸脱を修正する、ターゲットを絞ったリファクタリング用 pull requests を作成する。

これにより、手動の「金曜日の片付け」が継続的に実行されるシステムに置き換わりました。ガベージコレクター自体も Codex agents によって動かされており、自己メンテナンスのループが構築されています。Source

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

原則 5：実行可能な計画

agents がコードを書く前に、彼らは計画を書きます。これらの計画は非公式なメモではなく、以下を指定する構造化された実行可能なドキュメントです。

• 目的（Objective）: タスクが何を達成するか
• 修正するファイル（Files to modify）: agent が手を加えるファイルの明示的なリスト
• 依存関係（Dependencies）: この作業が依存する他のタスクやモジュール
• 受け入れ基準（Acceptance criteria）: 作業が完了したことを確認する方法
• 制約（Constraints）: 違反してはならないアーキテクチャ上のルール

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

計画は Markdown ファイルとしてリポジトリに保存され、バージョン管理され、実行前にレビューすることができます。これにより、人間が意図と実装の間にチェックポイントを設けることができます。

パート 4：Codex agent ループ

ハーネス内で Codex agent ループがどのように動作するかを理解することは、効果的なハーネスエンジニアリングに不可欠です。

ループアーキテクチャ

OpenAI は、関連記事 "Unrolling the Codex agent loop" で Codex agent ループの詳細な内訳を公開しました。Source ループはこのサイクルに従います。

Read Context → Plan → Execute → Validate → Commit (or Retry)

各反復において：

1. Read Context: agent は、リポジトリから関連するファイル、ドキュメント、スキーマ、およびタスク計画を読み取ります。
2. Plan: コンテキストに基づいて、agent はどのような変更を行うかを決定します。
3. Execute: agent はコードを書くか修正します。
4. Validate: ハーネスは、変更に対してテスト、リンター、および構造チェックを実行します。
5. Commit or Retry: 検証が通れば、agent はコミットします。失敗した場合、agent はエラー出力を読み取り、再試行します。

ハーネスの役割は、ステップ 1 と 4 を可能な限り情報豊富にすることです。agent が読み取るコンテキストが多いほど、計画は良くなります。検証フィードバックが具体的なほど、実用的なソリューションに早く収束します。

App Server ハーネス

OpenAI は記事 "Unlocking the Codex harness: how we built the App Server" において、agent ループを支える具体的なインフラストラクチャについて説明しています。Source App Server は以下を提供します。

• 各 agent タスクのための サンドボックス実行環境
• 事前設定されたツールアクセス (ファイルシステム、ターミナル、ブラウザ)
• リポジトリのアーティファクトからの 自動コンテキスト注入
• agents がテストの失敗をリアルタイムで確認できる ストリーミング検証フィードバック

パート 5：チームへのハーネスエンジニアリングの適用

始め方：最小実行可能ハーネス (Minimum Viable Harness)

ハーネスエンジニアリングの恩恵を受けるために、OpenAI のインフラ全体を複製する必要はありません。まずは以下の基礎的な要素から始めてください。

ステップ 1：ARCHITECTURE.md を作成する

プロジェクトのアーキテクチャルールを、マシン読み取り可能な形式でリポジトリのルートにドキュメント化します。以下を含めてください。

• モジュールの境界と許可された依存関係
• 命名規則
• ファイル構成のルール
• テスト要件

この 1つのファイルがあるだけで、agents が変更を加える前にそれを読み取るため、agent の出力品質が劇的に向上します。

ステップ 2：構造テストを追加する

アーキテクチャルールを検証するテストを書きます。これらのテストはビジネスロジックをチェックするのではなく、コードが正しく構成されているかをチェックします。

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

ステップ 3：CI 検証を設定する

CI パイプラインが、agent によって作成されたものを含むすべての pull request に対して、構造テスト、リンター、および型チェックを実行するようにします。agent は、人間の開発者が見るのと同じ検証出力を確認できる必要があります。

ステップ 4：agent 実行前にタスク計画を書く

agent に機能の実装を依頼する前に、修正するファイル、従うべき制約、受け入れ基準を指定した構造化された計画ドキュメントを作成します。これらの計画をリポジトリに保存します。

ステップ 5：自動クリーンアップをセットアップする

週次または夜次の CI ジョブを実装し、ドキュメント化された基準からの逸脱をスキャンして、焦点を絞ったリファクタリング PR を作成するようにします。

agent システムの選択

どの agent を使用するかに関わらず、ハーネスエンジニアリングの原則は適用されます。

ハーネスは agent の中ではなく、リポジトリの中に存在します。つまり、ハーネスへの投資を失うことなく agent を切り替えることができます。

1 つの agent から多数の agent へのスケーリング

OpenAI の実験は、ハーネスエンジニアリングが並列 agent 実行を可能にすることを証明しました。ハーネスがアーキテクチャの境界を強制するため、複数の agents が競合を引き起こすことなく、コードベースの異なる部分で同時に作業できます。

並列 agent 実行のための主な要件：

1. 明確なモジュールの所有権 — 各 agent は定義された境界内で作業します。
2. モジュール間の型定義されたインターフェース — agents は実装の詳細を知らなくてもインターフェースに対してコードを書くことができます。
3. マージ競合の防止 — ファイルの重複を最小限に抑えるようタスクの範囲が設定されます。
4. 中央集約型の検証 — すべての agents は同じ CI パイプラインに送信します。

パート 6：よくある落とし穴とアンチパターン

アンチパターン 1：agent をハーネスとして扱う

agent はハーネスではありません。ハーネスは agent が動作する環境です。構造が不十分なリポジトリを補うためによりスマートなモデルを求めるのは、間違ったアプローチです。プロンプトではなく、環境を修正してください。

アンチパターン 2：間違った場所にあるドキュメント

アーキテクチャの決定事項が Confluence、Notion、または Google Docs にある場合、agents はそれを見ることができません。修正は簡単ですが規律が必要です。開発に関連するすべてのドキュメントをリポジトリに移動してください。

アンチパターン 3：自動化された強制ではなく手動のクリーンアップ

agent が生成したコードのクリーンアップにかなりの時間を費やしているなら、必要なのはさらなるクリーンアップ作業ではなく、より強力な強制力です。繰り返されるクリーンアップタスクは、リンタールール、構造テスト、または自動リファクタリングジョブのいずれかに変換されるべきです。

アンチパターン 4：過剰な制約

ハーネスが厳格すぎると、agents が創造的な解決策を見つけるのを妨げます。目標は実装ではなく、アーキテクチャを制約することです。どのモジュールを修正できるか、どの依存関係が許可されているかを agents に伝えますが、その境界内でのロジックの実装方法は agents に任せてください。

アンチパターン 5：agent のフィードバックの無視

agent が特定のタスクで繰り返し失敗する場合、その失敗は通常、agent の限界ではなくハーネスの欠落を示しています。失敗のパターンを追跡し、ドキュメント、構造テスト、またはアーキテクチャ上の制約を改善するために使用してください。

パート 7：ハーネスエンジニアリングの未来

Martin Fowler の視点

Martin Fowler は自身のブログでハーネスエンジニアリングの分析を公開し、それがソフトウェアチームの運営における根本的なシフトを象徴していると述べています。この規律は、継続的インテグレーション、アーキテクチャ決定記録、依存性の注入といった数十年にわたるソフトウェアエンジニアリングのベストプラクティスを借りつつ、それらを agent 主導の世界に合わせて再利用したものです。Source

HumanLayer フレームワーク

HumanLayer のチームは、ハーネスエンジニアリングを「スキル問題（skill issue）」と呼ぶ分析を公開しました。効果的なハーネスを設計する能力が、高いパフォーマンスを発揮するチームと苦戦するエンジニアリングチームの主要な差別化要因になると主張しています。Source

開発者にとっての意味

ハーネスエンジニアリングは開発者のスキルを置き換えるものではなく、その方向を変えるものです。シニアエンジニアは、自らコードを書く代わりに、agents がコードをうまく書けるようにするためのシステムを設計します。重要なスキルは実装からアーキテクチャへ、コーディングからシステム設計へ、テストの作成からテストフレームワークの設計へとシフトします。

アプリケーションを構築するチームにとって、ZBuild のようなプラットフォームは、すでにハーネスエンジニアリングの原則をアプリビルダーのワークフローに取り入れています。開発者がゼロから独自のハーネスを設計することを求めるのではなく、ZBuild は事前設定されたアーキテクチャパターン、依存関係管理、および検証システムを提供し、AI agents を高品質な出力へと導きます。これにより、開発者はインフラではなく製品の決定に集中できるようになります。

3 つの地平線

今後、ハーネスエンジニアリングは 3つのフェーズを経て進化する可能性が高いでしょう。

1. 短期 (2026年): チームはリポジトリ優先のドキュメント、構造テスト、およびゴールデン・プリンシパルを採用します。適切にハーネスされたプロジェクトでは、agent 支援開発が標準的な慣行となります。

2. 中期 (2027年): ハーネスの生成自体が agent 主導になります。agents は既存のコードベースを分析し、観察されたパターンに基づいて、リンタールール、構造テスト、依存関係の境界などのハーネス設定を提案します。

3. 長期 (2028年以降): ハーネスは適応型になります。静的なルールの代わりに、agent が生成したコードの結果に基づいて進化し、エラーが頻発する領域では制約を自動的に厳しくし、一貫して成功する領域では制約を緩和するようになります。

パート 8：実践チェックリスト

このチェックリストを使用して、チームのハーネスエンジニアリングの成熟度を評価してください。

基礎 (ここから開始)

• ARCHITECTURE.md がリポジトリのルートに存在する
• コードフォーマットが自動化されている (Prettier, Black, gofmt)
• すべての pull request でリンティングが実行される
• 型チェックが強制されている (TypeScript strict, mypy など)

中級

• 構造テストが依存関係の境界を検証している
• ゴールデン・プリンシパルが文書化され、機械的に強制可能である
• agent 実行前にタスク計画が作成されている
• agent が生成した PR が、人間が作成した PR と同じ CI を通過している

上級

• 自動ガベージコレクションが定期的に実行されている
• 複数の agents が競合することなく並列で作業できる
• agent の失敗パターンが追跡され、ハーネスの改善に使用されている
• ハーネス自体がコードと同様にバージョン管理され、レビューされている

エキスパート

• agents がハーネスの一部（リンタールール、構造テスト）を生成している
• 各モジュールに品質グレードが自動的に割り当てられている
• agent の成功率に基づいたデータ駆動型のハーネス改善が行われている
• agents 導入前よりもエンジニア 1人あたりの週間コード出荷量が増えている

結論

ハーネスエンジニアリングは一時的な流行ではありません。それは、AI agents がプロダクションコードを書くのに十分な能力を持ちつつも、それをうまく行うために構造化された環境を必要とする時代における、ソフトウェアエンジニアリングの自然な進化です。OpenAI の 100万行の実験は、そのコンセプトが大規模に通用することを証明しました。彼らが明示した原則 — リポジトリ優先の知識、ゴールデン・プリンシパル、レイヤードアーキテクチャ、自動ガベージコレクション、実行可能な計画 — は、あらゆる規模のチームに適用可能です。

2026年にハーネスエンジニアリングを習得したチームは、AI agents を単なる高度なオートコンプリートとして扱っているチームよりも、より速く出荷し、より高いコード品質を維持し、より効果的にスケールするでしょう。agent は馬です。ハーネスこそが、それを役立たせるものなのです。

参考文献

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote