Claude Code や Codex といった AI コーディングエージェントを現場に投入する開発者が増えるなか、「ハーネスエンジニアリング」という新しい実践領域が注目を集めている。逆瀬川氏（@gyakuse）が公開したまとめ記事から、要点を紹介する。
そもそも「ハーネス」とは何か
「ハーネス（harness）」とは、もともと馬具の意味だ。馬の力を人間が制御して活かすための装具一式 — 手綱、鞍、轡（くつわ）などを指す。馬がどれだけ優秀でも、ハーネスなしでは暴走するだけで仕事にならない。
ソフトウェアの世界では「テストハーネス」という用語がすでにある。テスト対象のコードを「つなぎ止めて」、入力を与え、出力を検証する枠組みのことだ。テスト対象そのものではなく、テスト対象を正しく動かすための外側の仕組みを指す。
AI コーディングエージェントにおける「ハーネス」もこれと同じ発想だ。AI エージェント（= 馬）は強力だが、そのままでは暴走する。古いドキュメントを信じてしまう、リンターのルールを勝手に緩和する、前のセッションで何をしたか忘れる。エージェントを制御し、安定した成果を引き出すための外側の仕組み全体がハーネスであり、それを設計・構築する技術がハーネスエンジニアリングだ。
具体的にハーネスを構成する要素は、大きく 3 つの層に分けられる:
- 入力層 — エージェントに何を読ませ、何を読ませないかを制御する（AGENTS.md の設計、リポジトリの衛生管理、セッション間の状態引き継ぎ）
- 実行制御層 — エージェントの作業中にリアルタイムで品質を強制する（リンター・フォーマッターの自動実行、計画と実行の分離）
- 検証層 — エージェントの出力が正しいことを確認する（E2E テスト、プリコミットチェック）
核心的な洞察は「ハーネスがモデルより重要」という点だ。同じモデルでもハーネスを改善すれば出力品質が劇的に向上する。開発者の責任は「正しいコードを書く」から「エージェントが確実に正しいコードを生産する環境を設計する」へとシフトしている。
7 つの主要トピック
1. リポジトリ衛生 〈入力層〉
「衛生（hygiene）」は、ソフトウェア開発で「不要物や汚染を取り除き、健全な状態を保つ」という意味で使われる慣用表現だ（「コードハイジーン」「ブランチハイジーン」なども同様）。ここでは、リポジトリ内に古くなったドキュメントや不正確な情報が溜まらないよう清潔に保つことを指す。人間なら「このメモ、古そうだな」と判断できるが、エージェントは 3 ヶ月前のメモも最新のコードも同じ「事実」として読んでしまう。だから情報の鮮度管理が重要になる。
- 実行可能なアーティファクト（コード、テスト、設定）を優先する
- 説明的ドキュメントは腐敗しやすいため最小化する
- ADR（Architecture Decision Records）で決定履歴を保全する
- テストはドキュメントより腐敗に強い
最大の敵は「説明的ドキュメントの腐敗」だ。エージェントは「3 ヶ月前のメモ」と「現在の真実」を区別できないため、古い情報が存在するだけで性能が低下する。ハーネスの入力層として、エージェントが読む情報の鮮度と正確性を保つことが最初のステップになる。
2. 決定論的ツールで品質を強制する 〈実行制御層〉
「決定論的（deterministic）」とは、同じ入力に対して毎回必ず同じ結果を返すという意味だ。リンターやフォーマッターがその典型で、たとえば「未使用の変数がある」というコードを渡せば、何度実行しても必ず同じ警告を返す。気分や文脈によって判断が揺れることがない。
対照的に、LLM は非決定論的だ。同じコードを渡しても、実行するたびにチェックの粒度や指摘内容がブレる。「インデントを揃えて」と指示しても、ある時はスペース 2 つ、別の時はタブで揃えるかもしれない。
だからこそ、機械的に判定できるルール（構文エラー、未使用変数、フォーマット）は LLM に任せず、決定論的ツールに委ねるのが原則だ。PostToolUse Hook でファイル編集のたびにリンターを自動実行し、エラーをエージェントに即時フィードバックする。
言語別の推奨スタック:
| 言語 | PostToolUse | プリコミット | カスタムルール |
|---|---|---|---|
| TypeScript | Biome + Oxlint | tsc + ESLint | eslint-plugin-local-rules |
| Python | Ruff check/format | Ruff + mypy | ast-grep |
| Go | gofumpt + golangci-lint | 同左 | ast-grep |
リンター設定の保護も重要だ。エージェントがルールを勝手に緩和・改ざんするのを防ぐ仕組みが必要になる。これはまさに「手綱」の役割 — エージェントが暴走しないよう、作業のたびに自動で引き戻す仕組みだ。
3. AGENTS.md / CLAUDE.md は「道しるべ」に徹する 〈入力層〉
AGENTS.md や CLAUDE.md は、エージェント起動時に最初に読み込まれる指示書だ。ここに詳細な説明を長々と書きたくなるが、それは逆効果になる。情報が多すぎるとエージェントのコンテキストを圧迫し、肝心の作業に使える余裕が減る。
原文ではこれをポインタ設計と呼んでいる。指示書自体に内容を書くのではなく、「詳しくはこのファイルを見よ」と参照先だけを示す設計だ。C 言語のポインタが値そのものではなくアドレスを持つのと同じ発想で、指示書は情報の「置き場所」を指し示す道しるべに徹する。
- 50 行以下を目標にする
- 詳細は別ファイルに分離し、参照のみ記述する
- 記述的説明ではなくルーティング指示（「○○については
docs/xx.mdを参照」）に集中する
4. 計画と実行の分離 〈実行制御層〉
- 計画段階を人間がレビューする
- 一度に複数機能に取り組まない
- テストで完了を検証する
エージェントにいきなりコードを書かせず、まず計画を出力させて人間が確認する。馬に走り出す前に行き先を確認させるようなものだ。
5. E2E テスト戦略 〈検証層〉
各領域ごとの推奨ツール:
- Web: アクセシビリティツリー（Playwright CLI / agent-browser）
- Mobile: mobile-mcp、XcodeBuildMCP
- CLI: bats-core、expect
- API: Hurl、Pact
- Infrastructure: terraform test、conftest
- AI/ML: lm-evaluation-harness、DeepEval、RAGAS
ユニバーサル原則は「構造化テキストで検証し、決定論的に実行可能にする」こと。
6. セッション間の状態管理 〈入力層〉
- 起動ルーティンを標準化する
- Git ログとコミットメッセージで前回状態を記録する
- 進捗は JSON で機械的に解析可能な形式にする
エージェントは毎回新しいセッションで起動するため、前回の作業内容を「覚えていない」。入力層として、前回の状態を確実に引き継ぐ仕組みが必要になる。
7. Codex vs Claude Code 〈全層〉
- Claude Code: Hooks で毎回のツール実行を介入可能（品質重視）
- Codex: クラウドサンドボックスで非同期並列実行（スループット重視）
- 実装パターンによってはハイブリッド構成も有効
プラットフォームごとにハーネスの実装手段が異なる。Claude Code は Hooks による実行制御層が強く、Codex はサンドボックスによる検証層が強い。どちらを使うかで、ハーネスの設計方針が変わる。
MVH（Minimum Viable Harness）ロードマップ
段階的に導入するためのロードマップ:
- Week 1: AGENTS.md 作成、プリコミットフック導入、PostToolUse Hook 設定
- Week 2-4: テスト追加、計画→実行ワークフロー確立、E2E テスト導入
- Month 2-3: カスタムリンター構築、記述ドキュメント削減
- Month 3+: 高度なフィードバックループ、複数エージェント管理
まとめ
「コンテキスト内で発見できないものは存在しないのと同じ」であり、「リポジトリ内で発見できる古い情報は最新の真実と区別不可能」。このジレンマを理解した上で、実行可能なアーティファクトと決定論的ツールを中心にハーネスを設計することが、AI コーディングエージェント時代の開発者に求められるスキルだ。
参考
- Harness Engineering ベストプラクティス 2026年版 — 逆瀬川氏による原文
- 元ツイート