Harness Engineering ベストプラクティス 2026 — AI コーディングエージェントを安定稼働させる設計術
Claude Code や Codex といった AI コーディングエージェントを現場に投入する開発者が増えるなか、「ハーネスエンジニアリング」という新しい実践領域が注目を集めている。逆瀬川氏（@gyakuse）が公開したまとめ記事（読了 54 分）から、要点を紹介する。 そもそも「ハーネス」とは何か 「ハーネス（harness）」とは、もともと馬具の意味だ。馬の力を人間が制御して活かすための装具一式 — 手綱、鞍、轡（くつわ）などを指す。馬がどれだけ優秀でも、ハーネスなしでは暴走するだけで仕事にならない。 ソフトウェアの世界では「テストハーネス」という用語がすでにある。テスト対象のコードを「つなぎ止めて」、入力を与え、出力を検証する枠組みのことだ。テスト対象そのものではなく、テスト対象を正しく動かすための外側の仕組みを指す。 AI コーディングエージェントにおける「ハーネス」もこれと同じ発想だ。AI エージェント（= 馬）は強力だが、そのままでは暴走する。古いドキュメントを信じてしまう、リンターのルールを勝手に緩和する、前のセッションで何をしたか忘れる。エージェントを制御し、安定した成果を引き出すための外側の仕組み全体がハーネスであり、それを設計・構築する技術がハーネスエンジニアリングだ。 具体的にハーネスを構成する要素は、大きく 3 つの層に分けられる: 入力層 — エージェントに何を読ませ、何を読ませないかを制御する（AGENTS.md の設計、リポジトリの衛生管理、セッション間の状態引き継ぎ） 実行制御層 — エージェントの作業中にリアルタイムで品質を強制する（リンター・フォーマッターの自動実行、計画と実行の分離） 検証層 — エージェントの出力が正しいことを確認する（E2E テスト、プリコミットチェック） 核心的な洞察は「ハーネスがモデルより重要」という点だ。Morph の分析によると、同じモデルでもハーネスを変えると SWE-bench スコアが 22 ポイント変動するのに対し、モデルの交換では 1 ポイントしか変わらない。開発者の責任は「正しいコードを書く」から「エージェントが確実に正しいコードを生産する環境を設計する」へとシフトしている。 7 つの主要トピック 1. リポジトリ衛生 〈入力層〉 「衛生（hygiene）」は、ソフトウェア開発で「不要物や汚染を取り除き、健全な状態を保つ」という意味で使われる慣用表現だ（「コードハイジーン」「ブランチハイジーン」なども同様）。ここでは、リポジトリ内に古くなったドキュメントや不正確な情報が溜まらないよう清潔に保つことを指す。人間なら「このメモ、古そうだな」と判断できるが、エージェントは 3 ヶ月前のメモも最新のコードも同じ「事実」として読んでしまう。だから情報の鮮度管理が重要になる。 実行可能なアーティファクト（コード、テスト、設定）を優先する 説明的ドキュメントは腐敗しやすいため最小化する ADR（Architecture Decision Records）で決定履歴を保全する テストはドキュメントより腐敗に強い 最大の敵は「説明的ドキュメントの腐敗」だ。エージェントは「3 ヶ月前のメモ」と「現在の真実」を区別できないため、古い情報が存在するだけで性能が低下する。ハーネスの入力層として、エージェントが読む情報の鮮度と正確性を保つことが最初のステップになる。 2. 決定論的ツールで品質を強制する 〈実行制御層〉 「決定論的（deterministic）」とは、同じ入力に対して毎回必ず同じ結果を返すという意味だ。リンターやフォーマッターがその典型で、たとえば「未使用の変数がある」というコードを渡せば、何度実行しても必ず同じ警告を返す。気分や文脈によって判断が揺れることがない。 対照的に、LLM は非決定論的だ。同じコードを渡しても、実行するたびにチェックの粒度や指摘内容がブレる。「インデントを揃えて」と指示しても、ある時はスペース 2 つ、別の時はタブで揃えるかもしれない。 だからこそ、機械的に判定できるルール（構文エラー、未使用変数、フォーマット）は LLM に任せず、決定論的ツールに委ねるのが原則だ。 ここで重要なのが「ほぼ毎回」と「例外なく毎回」の差だ。CLAUDE.md に「リンターを実行せよ」と書くだけでは前者にとどまる。コンテキストウィンドウの消費が進むと、エージェントはリンターの存在を忘れてしまうからだ。Claude Code の Hook（特定のライフサイクルイベントで自動実行されるスクリプト）で強制すれば後者になる。 ...