コーディングエージェントユーザー向けのハーネスエンジニアリング

「ハーネス」という用語は、AIエージェントにおけるモデル自体を除くすべてのものを指す略称として登場しました - Agent = Model + Harness。これは非常に広い定義であり、したがって一般的なエージェントのカテゴリに対して絞り込む価値があります。ここでは、コーディングエージェントを使用するという限定された文脈での意味を定義する自由を取ります。コーディングエージェントでは、ハーネスの一部はすでに組み込まれています（例: システムプロンプトを介して、または選択されたコード取得メカニズムを介して、または高度なオーケストレーションシステムさえも）。しかし、コーディングエージェントはまた、私たちユーザーに対して、ユースケースとシステムに特化した外側のハーネスを構築するための多くの機能を提供しています。

図1: 「ハーネス」という用語は、限定された文脈によって異なる意味を持ちます。

適切に構築された外側のハーネスは2つの目標を果たします：エージェントが最初から正しい結果を得る確率を高め、人間の目に入る前に可能な限り多くの問題を自己修正するフィードバックループを提供することです。最終的には、レビューの負担を軽減し、システムの品質を向上させると同時に、無駄なトークンを減らすという追加の利点も得られます。

フィードフォワードとフィードバック

コーディングエージェントをハーネスするためには、望ましくない出力を予測して防ぐことと、エージェントが自己修正できるようにセンサーを配置することの両方を行います：

• ガイド（フィードフォワード制御） - エージェントの動作を予測し、行動する前にそれを操縦することを目指します。ガイドは、エージェントが初回で良い結果を生み出す確率を高めます
• センサー（フィードバック制御） - エージェントが行動した後を観察し、自己修正を助けます。特にLLMの消費に最適化された信号を生成する場合に強力です。例えば、自己修正のための指示を含むカスタムリンターメッセージ - ポジティブな形のプロンプトインジェクションです。

別々に考えると、フィードバックのみの場合は同じ間違いを繰り返すエージェントになり、フィードフォワードのみの場合はルールをエンコードするがそれらが機能したかどうかを知らないエージェントになります。

計算的 vs 推論的

ガイドとセンサーには2つの実行タイプがあります：

• 計算的 - 決定論的で高速、CPUで実行されます。テスト、リンター、型チェッカー、構造解析。ミリ秒から数秒で実行され、結果は信頼性があります。
• 推論的 - 意味解析、AIコードレビュー、「LLMをジャッジとして」。通常GPUまたはNPUで実行されます。遅くて高価ですが、結果は非決定論的です。

計算的ガイドは、決定論的なツールで良い結果の確率を高めます。計算的センサーは安価で高速であるため、エージェントと並行してすべての変更に対して実行できます。もちろん推論的制御はより高価で非決定論的ですが、リッチなガイダンスを提供し、追加の意味的判断を加えることを可能にします。その非決定論にもかかわらず、推論的センサーは、強いモデル、またはむしろタスクに適したモデルと使用する場合に特に信頼を高めることができます。

例

	方向	計算的 / 推論的	実装例
コーディング規約	フィードフォワード	推論的	AGENTS.md、スキル
新規プロジェクトをブートストラップする方法の指示	フィードフォワード	両方	指示とブートストラップスクリプトを含むスキル
コードモッド	フィードフォワード	計算的	OpenRewriteレシピにアクセスできるツール
構造テスト	フィードバック	計算的	モジュール境界の違反をチェックするArchUnitテストを実行するpre-commit（またはコーディングエージェント）フック
レビューの方法の指示	フィードバック	推論的	スキル

操縦ループ

人間の役割は、ハーネスを反復することでエージェントを操縦することです。問題が複数回発生するたびに、将来の発生確率を下げたり、そもそも防いだりするために、フィードフォワードおよびフィードバック制御を改善する必要があります。

操縦ループでは、もちろんAIを使ってハーネスを改善することもできます。コーディングエージェントは、よりカスタムな制御やよりカスタムな静的解析を構築するコストを大幅に下げます。エージェントは構造テストの作成、観測されたパターンからのドラフトルールの生成、カスタムリンターのスキャフォールディング、またはコードベース考古学からのハウツーガイドの作成を支援できます。

タイミング：品質を左に保つ

継続的インテグレーションを行っているチームは、コスト、速度、重要性に応じて、テスト、チェック、人間によるレビューを開発タイムライン全体に分散するという課題に常に直面してきました。継続的デリバリーを目指す場合、理想的にはすべてのコミット状態がデプロイ可能であることが望まれます。問題を発見するのが早ければ早いほど修正コストが安くなるため、できるだけ本番環境へのパスで左側にチェックを配置したいのです。新しい推論的センサーを含むフィードバックセンサーは、ライフサイクル全体に適切に分散する必要があります。

変更ライフサイクルにおけるフィードフォワードとフィードバック

• 合理的に高速で、インテグレーション前、またはコミット作成前でも実行すべきものは何か？（例: リンター、高速テストスイート、基本的なコードレビューエージェント）
• より高価であるため、パイプライン内のインテグレーション後でのみ実行し、高速制御の繰り返しと併用すべきものは何か？（例: ミューテーションテスト、より広い文脈を考慮できるより広範なコードレビュー）

継続的なドリフトとヘルスセンサー

• 徐々に蓄積されるドリフトの種類で、変更ライフサイクルの外でコードベースに対して継続的に実行されるセンサーによって監視すべきものは何か？（例: デッドコード検出、テストカバレッジの品質分析、依存関係スキャナー）
• エージェントが監視できるランタイムフィードバックは何か？（例: SLOの劣化を探して改善方法を提案させたり、AIジャッジが継続的にレスポンス品質をサンプリングしてログの異常をフラグ付けしたり）

規制カテゴリ

エージェントハーネスはサイバネティクスのガバナーとして機能し、フィードフォワードとフィードバックを組み合わせて、コードベースを望ましい状態に向かって規制します。この望ましい状態の複数の次元を区別することは有用です。これはハーネスが規制すべきものによって分類されます。これらのカテゴリを区別することは、ハーネス可能性と複雑さがそれらによって異なるため、そして「ハーネス」という非常に一般的な用語に修飾を加えることで、より正確な言語を提供するためです。

現時点で有用と思われる3つのカテゴリは以下の通りです：

保守性ハーネス

この記事で挙げている例のほとんどは、内部コード品質と保守性を規制することに関するものです。これは現在最も簡単なタイプのハーネスです。既存のツールを多く活用できるためです。

これらの保守性ハーネスのアイデアがエージェントへの信頼をどれだけ高めるかを振り返るために、以前にカタログ化した一般的なコーディングエージェントの失敗モードに対してマッピングを行いました。

計算的センサーは構造的なものを確実にキャッチします：重複コード、循環的複雑度、テストカバレッジの欠如、アーキテクチャのドリフト、スタイル違反。これらは安価で、実績があり、決定論的です。

LLMは意味的判断を必要とする問題 - 意味的に重複したコード、冗長なテスト、力任せの修正、過剰にエンジニアリングされたソリューション - に部分的に対処できますが、高価で確率的です。すべてのコミットに対して行うわけではありません。

どちらも、一部の高い影響力の問題を確実にキャッチできません：問題の誤診、過剰エンジニアリングと不要な機能、指示の誤解。これらをキャッチすることもありますが、監督を減らせるほど確実ではありません。正確性は、人間が最初に何を望むかを明確に指定していない場合、どのセンサーの権限外にもなります。

アーキテクチャ適合性ハーネス

これはアプリケーションのアーキテクチャ特性を定義・チェックするガイドとセンサーをグループ化したものです。基本的に：適合性関数です。

例：

• パフォーマンス要件をフィードフォワードするスキル、およびパフォーマンステストが改善または劣化したかどうかをエージェントにフィードバックするスキル。
• より良い可観測性のためのコーディング規約（ログ基準など）を記述するスキル、および利用可能なログの品質についてエージェントに振り返らせるデバッグ指示。

振る舞いハーネス

これは部屋の中の象です - アプリケーションが機能的に必要な方法で振る舞うかどうかをどのようにガイドし、検知するのか？現時点では、コーディングエージェントに高い自律性を与えている人々のほとんどが次のようにしています：

• フィードフォワード：機能仕様（短いプロンプトから複数ファイルの記述まで、さまざまな詳細レベル）
• フィードバック：AI生成のテストスイートがグリーンかどうか、合理的に高いカバレッジがあるかどうかをチェックし、一部はミューテーションテストでその品質を監視するかもしれません。その後、手動テストと組み合わせます。

このアプローチはAI生成のテストに多くの信頼を置いていますが、まだ十分ではありません。一部の同僚は承認済みフィクスチャパターンで良い結果を得ていますが、適用しやすい領域とそうでない領域があります。彼らは適合する場所で選択的に使用しており、テスト品質問題に対する包括的な答えではありません。

したがって全体として、監督と手動テストを減らせるほどの信頼を高める機能的振る舞いのための良いハーネスをまだ多く解決する必要があります。

ハーネス可能性

すべてのコードベースがハーネスに対して等しく適しているわけではありません。強い型付け言語で書かれたコードベースには自然に型チェックがセンサーとして存在し、明確に定義可能なモジュール境界はアーキテクチャ制約ルールを可能にし、Springのようなフレームワークはエージェントが心配する必要のない詳細を抽象化するため、エージェントの成功確率を暗黙的に高めます。これらの特性がなければ、それらの制御は構築できません。

これはグリーンフィールドとレガシーで異なる形で現れます。グリーンフィールドチームは初日からハーネス可能性を組み込むことができます - 技術的決定とアーキテクチャ選択が、コードベースがどれだけ統制可能かを決定します。レガシーチーム、特に多くの技術的負債が蓄積したアプリケーションを持つチームは、より困難な問題に直面します：ハーネスが最も必要とされる場所で構築するのが最も難しいのです。

ハーネステンプレート

ほとんどの企業には、必要なものの80%をカバーするいくつかの一般的なサービスのトポロジーがあります - API経由でデータを公開するビジネスサービス；イベント処理サービス；データダッシュボード。多くの成熟したエンジニアリング組織では、これらのトポロジーはすでにサービステンプレートとしてコード化されています。これらは将来的にハーネステンプレートに進化するかもしれません：トポロジーの構造、規約、技術スタックにコーディングエージェントを縛り付けるガイドとセンサーのバンドル。チームは利用可能なハーネスに基づいて、技術スタックや構造を選択するようになるかもしれません。

もちろん、サービステンプレートと同様の課題に直面するでしょう。チームがそれらをインスタンス化するとすぐに、上流の改善と同期しなくなります。ハーネステンプレートも同じバージョン管理とコントリビューションの問題に直面するでしょう。おそらくテストがより困難な非決定論的ガイドとセンサーでは、さらに悪化するかもしれません。

人間の役割

人間の開発者として、私たちはすべてのコードベースにスキルと経験を暗黙のハーネスとして持ち込みます。規約と良いプラクティスを吸収し、複雑さの認知的苦痛を感じ、「ここではそうしない」という直感を持ち、コミットに名前を残しています。また、組織的な整合性 - チームが達成しようとしていること、ビジネス上の理由で許容される技術的負債、この特定の文脈で「良い」とはどのようなものか - も持ち合わせています。私たちは小さなステップで、人間のペースで進み、それが経験がトリガーされ、適用される思考空間を生み出します。

コーディングエージェントにはこれがありません：社会的説明責任、300行の関数の美的嫌悪感、「ここではそうしない」という直感、組織的記憶。どの規約が負荷を支えるもので、どれが単なる習慣なのか、または技術的に正しい解決策がチームが達成しようとしていることに適合するかどうかを知りません。

ハーネスは、人間の開発者経験がもたらすものを外部化し、明示的にしようとする試みですが、それには限界があります。ガイドとセンサー、自己修正ループのコヒーレントなシステムを構築するのは高価であるため、明確な目標を持って優先順位付けする必要があります：良いハーネスは必ずしも人間の入力を完全に排除することを目指すべきではなく、私たちの入力が最も重要な場所に向けることを目指すべきです。

出発点 - および未解決の問題

ここで提示したメンタルモデルは、すでに実践されている技術を説明し、私たちがまだ解決する必要があることについての議論を枠組み化するのに役立ちます。その目標は、会話のレベルを機能レベルから引き上げるものです - スキルやMCPサーバーから、エージェントが生成するものに対して本物の信頼を与える制御システムを戦略的に設計する方法へ。

現在の言説からのハーネス関連の例をいくつか挙げます：

• OpenAIのチームが彼らのハーネスがどのようなものかを文書化しました：カスタムリンターと構造テストによって強制されるレイヤードアーキテクチャ、そしてドリフトをスキャンしてエージェントに修正を提案させる定期的な「ガベージコレクション」。彼らの結論：「私たちの最も困難な課題は現在、環境、フィードバックループ、制御システムの設計に集中しています。」
• Stripeのミニオンに関する記事では、ヒューリスティックに基づいて関連するリンターを実行するpre-pushフックのようなものを説明し、「フィードバックを左にシフト」することの重要性を強調し、「ブループリント」がフィードバックセンサーをエージェントワークフローに統合する方法を示しています。
• ミューテーションおよび構造テストは、過去に十分に活用されていなかった計算的フィードバックセンサーの例ですが、現在再び注目されています。
• 開発者の間で、LSPとコードインテリジェンスのコーディングエージェントへの統合についての議論が増えています。これは計算的フィードフォワードガイドの例です。
• Thoughtworksのチームから、計算的および推論的センサーの両方でアーキテクチャドリフトに取り組んでいるという話を聞きます。例えば、エージェントとカスタムリンターの混合でAPI品質を向上させたり、「ジャニターアーミー」でコード品質を向上させたりしています。

まだ解決すべきことはたくさんあります。すでに述べた振る舞いハーネスだけでなく。ハーネスが成長するにつれて、ガイドとセンサーが同期し、互いに矛盾しないようにコヒーレンスを保つにはどうすればよいでしょうか？指示とフィードバッグ信号が異なる方向を指す場合、エージェントが賢明なトレードオフを行うことをどこまで信頼できるでしょうか？センサーが決して発火しない場合、それは高品質の兆候なのか、検出メカニズムの不備なのか？コードカバレッジとミューテーションテストがテストに対して行うのと同様に、ハーネスカバレッジと品質を評価する方法が必要です。フィードフォワードとフィードバック制御は現在、デリバリーステップ全体に散在しています。それらをシステムとして構成、同期、推論するのを助けるツールには真の可能性があります。この外側のハーネスの構築は、1回限りの設定ではなく、継続的なエンジニアリングプラクティスとして登場しています。

---