すべての言語
共有
Harness を理解すれば、AI エージェントが実際に機能し始めるでしょう
金色财经_Wendy128日前
著者: @rohit4verse
正しいモデルが見つからなかったため、間違ったモデルを使用しているわけではありません。 AI。
正しい環境を構築していないため、AI の使用方法は間違っていました。 AI。
3 人のエンジニアで数百万行のコードを納品したチームもあれば、パイプラインで安定したリファクタリングさえ達成できないチームもあります。 エージェント ——その理由は、 GPT-5 または Claude Opus の違いではありません 設定または最大トークンは、プロンプトワードさえ含まれていません。ただし、人々はプロンプトワードについて議論するのに数え切れないほどの年月を費やしてきました。
違いは ハーネスです。
この記事で説明するのは、この言葉が技術レベルおよび概念レベルで何を意味するかということです。——業界全体に、この言葉を不用意に使用するという悪い習慣が身に付いているためです。
ハーネス はシステム プロンプト ワードではなく、 API 呼び出しのパッケージでもありません。評価フレームワーク、プロンプト ワード テンプレート、またはメモリ機能を備えたチャットボットでもありません。
ハーネス は、言語モデルが動作する完全な設計環境です。履歴は圧縮されて管理され、エラーが連鎖する前にエラーを検出するガードレール、そして一貫性を失うことなく将来の自己に作業を引き渡すことを可能にする足場が備わっています。
人間的な クロード コード を実際に機能させるために構築されたものを見ると、 NLP グループは、 エージェント - コンピュータ インターフェイス SWE エージェント を見ると、この分野に真剣に取り組んでいるすべてのチームから同様のパターンが現れ始めていることがわかります。
モデルはほとんど無関係です。 ハーネス がすべてです。
このコンセプトが 2025 年から 2026 年にかけてどのように実現したかを簡単に紹介します。 lang="EN-US"> AI エンジニアリングのコアとなる洞察の詳細な技術分析。関連する研究、現実世界の実装例、設計上の決定を促進する障害モード、およびプログラミング エージェントの構築、エージェントの研究、または長期にわたる自律型ソフトウェア エンジニアであるかどうかに関係なく、何度も登場するパターンを取り上げます。
読むと、 ハーネス ハーネスが何であるかだけでなく、ハーネスを正しく構築する理由も理解できるようになります。 ハーネス今日の業界において最も貴重なエンジニアリングスキル。
パート 1: 誰も語らない問題
2024 年 年の半ば、AI ベンチマークの分野で奇妙なことが起こりました。研究者たちは、タスクの提示方法や利用可能なツールに応じて、まったく同じプログラミング タスクに対して、同じ最先端のモデルでもまったく異なる結果が得られる可能性があることに気づき始めました。モデルも基盤となるインテリジェンスも変更されておらず、インターフェースのみが変更されています。
これは驚くべきことではありません。私たちは、適切なツールがエンジニアの生産性を向上させることができることを何十年も前から知っていました。最新の IDE、デバッガー、バージョン管理、CI/CD パイプラインを備えたソフトウェア開発者は、テキスト エディターだけを備えた純粋なターミナルで作業する同じ人よりも生産性が桁違いに高くなります。 IDE は開発者を賢くするものではありません。摩擦を軽減し、適切なタイミングで情報を提供し、エラーを早期に発見し、作業をナビゲート可能な単位に整理します。
言語モデルについても同じことが当てはまります。これらは、無限の内部知識ベースから推論する汎用推論エンジンではなく、コンテキスト ウィンドウ内のトークンに対して動作する高度なパターン マッチング エンジンです。特定の瞬間に知っていることはすべて、コンテキスト ウィンドウの内容によって決まります。彼らが生み出すものはすべて、そのコンテキストの構造に依存します。入力の形式は装飾ではなく、エージェントの認知アーキテクチャです
インターフェイスは便利なレイヤーではありません。言語モデル エージェント の場合、インターフェースは心そのものです。
こちらプリンストンです NLP グループ 2024 SWE-agent この論文の中核となる提案は精査に耐えることができます。このペーパーでは、エージェント -コンピュータ インターフェイス (ACI) の概念を紹介し、適切に設計された ACI を示します。 64% の相対的な改善です。。
同じモデル、同じタスク、同じ計算量。唯一の変数はインターフェイスです。
この数値をしばらく待ってください。 64% は限界利益ではなく、効果的なツールと非効果的なツールの差です。そして、それは完全に環境の設計から来ており、基礎となるモデルの改善からではありません。
AI エージェントの単純な認知モデルは、コンテキスト ウィンドウをメモリとして扱います。データをロードし、モデルがそれを処理して、出力を取得します。コンテキストが多いほどパフォーマンスが向上し、プロンプトが長いほど理解が深まります。このメンタル モデルは間違っており、間違ったアプローチをとれば、そのモデルに基づいて構築したエージェントが破壊されてしまいます。
コンテキスト ウィンドウは、実際には、 エージェント の特定のセッションにおける全体的な作業認識に近いものです。ウィンドウ内の各 トークン には計算コストがかかります。無関係な情報はすべて、注意を引くために関連情報と競合します。このモデルには、ノイズを完全に無視できる選択的注意メカニズムがありません。——ノイズの存在は推論に影響を与えます。
2 つの機能を確認したい場合。 エージェント 使用する cat ファイル全体をダンプしたとき、消防ホースを渡しました。コップ一杯の水が必要でした。
SWE-agent の研究者は、これらの障害モードを詳細に文書化しました。標準の bash インターフェイスでは、 エージェント が繰り返しのトラバーサルでスタックする可能性があります。エージェントは grep を発行します。 コマンドを実行すると、何を探しているのかわからなくなり、さらに grep コマンドを発行すると、徐々にコンテキストがノイズで満たされ、最終的には間違った答えを返すか、進行が完全に停止してしまいます。
問題はモデル インテリジェンスではなく、エージェント それ自体が圧倒されるのを防ぐメカニズムがインターフェイスにないことです。
この設計上の決定は、振り返ってみると笑えるほど単純に思えますが、この文書全体の中で最も活用された変更の 1 つです。これにより、コンテキストの圧倒による失敗パターンが自然な洗練サイクルに変わります。
パート 2:SWE エージェント 用紙と ACI の誕生
エージェント -コンピュータ インターフェイスとは正確には何ですか
ACI は、 SWE エージェントの言語モデルにある文書で定義されています エージェント とコンピュータ環境の間の抽象化層。人間とコンピュータのインターフェイス (HCI) との類似性は意図的なものです。 HCI 研究では、人間の認知アーキテクチャに適合するインターフェイスを設計する方法が求められているのと同様に、ACI 研究では、言語モデルの認知アーキテクチャに適合するインターフェイスを設計する方法が求められています。
人間の認知構造には、視覚的パターン認識、空間記憶、画面間での並行注意、流し読みして選択的に集中する能力が含まれます。
言語モデルの認知アーキテクチャは根本的に異なります。——順序が関係します。 トークン 処理、文脈上の順序と形式に対する敏感性、限定された作業が含まれます。記憶、そしてキューワードの最も顕著な情報に固定される傾向があります。優れた ACI を設計するということは、これらの制約を理解し、制約に対抗するのではなく、制約を回避して構築することを意味します。
4 つの主要コンポーネントがあり、それぞれが raw コンピューターにアクセスする際に言語モデルがどのように失敗するかについての具体的な洞察を反映しています。検索コンポーネントは、標準の grep および find コマンドを置き換えます:
クエリがこの制限を超えると、ツールは結果が多すぎることを示すメッセージを返し、 エージェント に検索を絞り込むよう求めます。これは些細なことのように聞こえますが、実際にはこの論文の中で最も影響力のある決定の 1 つです。
これが重要なのは、 エージェント 認知負荷を受けた人間と同様に、不安を感じたときにその行動を続ける傾向があるためです。大規模なコードベースで道に迷った場合、より広範囲を検索することになり、ますます多くのノイズが発生します。上限付き検索ツールは、強制機能を作成することでこのパラダイムを破壊します。曖昧では前進できず、正確でなければなりません。これにより、エージェント
ファイル ビューアは、コグニティブ アーキテクチャに関する論文の洞察を最も具体的に示したものです。研究者らはさまざまなビューア構成をテストし、ディスプレイあたり 100 行がちょうどよい数であることを発見しました。行数が少ないと ( 30 行をテストしました) エージェント 周囲のコードのコンテキストが失われ、編集エラーが発生する可能性があります。行数が増えると (またはファイル全体が表示されると)、エージェントが混乱して重要な詳細を見逃す可能性があります。
ビューアはステートフルであり、対話間でファイル内の位置を維持します。さらに重要なのは、表示されている各行の先頭に明示的な行番号が付加されていることです。この最後の詳細はまったく表面的なものに見えるかもしれませんが、そうではありません。
リンティング機能付きファイル エディタ リンティング機能付き
ファイル エディターの中核となる革新は、ガードレールによる即時フィードバックです。
これにより、ナイーブなエージェントの実装でカスケード障害を引き起こすフィードバック ループが閉じられます。 リンター 、エージェント がない場合、構文エラーが発生し、テスト スイートを実行すると、一見無関係に見えるエラーが表示され (実際のエラーは別の場所にあるため)、複数の費用がかかる可能性があります。間違った問題を追跡するステップが増え、最終的にはゴーストを追跡するコンテキスト ウィンドウが使い果たされてしまいます。
リンター リンター をエディタに直接統合します。構文エラーは導入された瞬間に検出でき、修正はローカライズされ、問題が伝播することはありません。
オリジナルの bash ツールの使用の比較: sed または出力リダイレクトを使用する場合、統合されたフィードバックはありません。編集はサイレントに実行され、複数行の変更には複雑なパラメータの書式設定が必要になるため、非常にエラーが発生しやすくなります。 エージェント はコマンドを正常に実行できますが、 リンターが発生し、捕捉された可能性のある微妙なフォーマット エラーが発生し、次の 10 ステップでテストが失敗した理由を考えます。
この履歴はすべてコンテキスト ウィンドウのスペースを占めており、古い情報を提供することでエージェントに誤解を招く可能性があります。
ACI のコンテキスト管理システムは以前の観察を記録します——最後の 5 ラウンド前のコンテンツ——
エージェント これまでに実行したすべてのコマンドの完全な非圧縮履歴に圧倒されることなく、最近行ったことや現在のステータスをいつでも確認できます。
SWE エージェント 論文はSWE ベンチ データセット ACI は、一般的な Python コード ベースからの実際の GitHub の問題を含むデータセットに対してベンチマークが行われました。タスクは、自然言語のバグレポートを受け取り、それを解決するコードパッチを作成することです。これは、なじみのないコード ベースをナビゲートし、エラー メッセージを理解し、正しいコードを記述し、修正を検証する必要がある、難しい実践的なタスクです。
使用 GPT-4 標準の bash シェルインターフェースを使用すると、システムは問題を解決しました。、システムは 12.47% の問題を解決しました。これは前述の 64% の相対的な改善であり、これは完全にインターフェース設計によるものです。
研究者らは、アブレーション研究も実施し、コンポーネントを一度に 1 つずつ除去して、各設計上の決定の影響を分離しました。 リンター 統合は常に最も活用されるコンポーネントの 1 つです。制限された検索は、コンテキストのフラッディングを防ぐために重要です。行番号付きのステートフル ファイル ビューアは、元の cat cat コマンドとよりシンプルなビューア設計よりも大幅に優れています。
パフォーマンスの違いはモデルのインテリジェンスとは関係がなく、すべては認知負荷管理に関係しています。 ACI は、モデルが状態を追跡するために必要な作業量を削減し、本当に重要な作業のためのスペースを解放します。
これらの発見は、プログラミングの枠をはるかに超えています。 エージェント 。長期にわたるエージェントのタスクには、同じ基本的な課題が伴います。それは、大規模な情報空間のナビゲート、複数のステップにわたる一貫した状態の維持、エラーの捕捉と回復、コンテキスト ウィンドウの注意という限られたリソースの管理です。 ACI の設計原則は一般化可能です。特定のツールは変わりますが、根本的な問題構造は変わりません。
パート 3:人類 の ハーネス プロジェクト (長期にわたる エージェント 問題)
SWE エージェント この文書は、単一の エージェント セッションのインターフェイスを設計する方法の問題を解決します。 Anthropic のエンジニアリング チームは、 Claude Agent SDK を開発中です。 および Claude コードの作成中 で、別の問題が発生しました。タスクが大きすぎて 1 つのコンテキスト ウィンドウ内で完了できない場合はどうすればよいでしょうか。
これは特殊な特殊ケースではありません。実際のソフトウェア プロジェクトのほとんどは、コンテキスト ウィンドウに収まらないほど大きすぎます。運用グレードの Web アプリケーションには、数百のファイル、数千の関数、テスト スイート、構成、ドキュメント、依存関係が含まれています。
たとえ 20 100 万 トークン コンテキスト ウィンドウを頭の中に保持することはできません。同じ時間です。人間のエンジニアは、外部メモリ、ドキュメント、バージョン管理、および数週間から数か月にわたってコード ベースに蓄積された理解を介して、この問題を解決します。そして、新しいセッションを開くエージェントには何もありません。
単純な解決策は圧縮 (圧縮) であり、これはある程度までは機能します。 Claude Agent SDK には、ウィンドウがいっぱいになったときに古いコンテキストを要約できる圧縮機能が組み込まれています。しかし、圧縮だけでは十分ではありません。
Anthropic の内部実験によると、 Opus 4.5 のような圧縮メカニズムを使用しても、このような最先端のプログラミング モデルは、複数のコンテキスト間でループすると引き続き失敗することがわかりました。 Windows では、高レベルのプロンプトのみに基づいて運用品質の Web アプリケーションを構築することが不可能になります。
失敗には 2 つのパターンがあり、どちらも有益です。
最初の失敗モードは、一度にたくさんのことをやろうとすることです。 "をビルドする claude.ai クローン"このようなプロンプトの言葉を使用すると、エージェント はアプリケーション全体を一度に完了しようとします。
次から次へと機能を実装し続けますが、それぞれの機能が完了またはテストされていないため、実装プロセスのコンテキスト ウィンドウが使い果たされ、中途半端なアプリケーションで次のセッションが終了します。—何が完了したかについての文書も、コードの現在の状態についての明確な説明もありません。
次の エージェント インスタンスは、先に進むのではなく、混乱を理解するためにコンテキスト バジェットのほとんどを費やします。
2 番目の障害モードは、プロジェクトの後半で発生します。いくつかの機能が構築されると、エージェントの後続のインスタンスは周りを見て、進捗状況を確認し、作業が完了したと結論付けます。"の結論。アプリケーションが半分しか完成していない場合、勝利を宣言し、動作を停止します。
これは愚かなことではなく、不完全な情報からの合理的な推論です。 エージェント このプロジェクトについて学ぶ体系的な方法はありません"完了"正確にはどういう意味ですか。
どちらの障害にも共通の原因があります。エージェントは、プロジェクトの状態を永続的に構造化して理解していないため、コンテキスト ウィンドウの境界を越えて後続のセッションに指示を与えることができません。
Anthropic のソリューションは 2 部構成のアーキテクチャであり、その後、長期的な エージェント的な作業に真剣に取り組むチームのテンプレートとなりました。
初始化 Agent 产出三个关键输出。
首先，它创建一个能够可靠启动开发环境的init.sh 脚本。这听起来平淡无奇，但具有显著的杠杆效益。
后续每一个编程agent 会话都可以通过运行 init.sh 来开始，而不必花费 token 去摸索如何启动服务器、配置数据库、将应用调整到可测试状态。在每次会话中节省的这部分开销，积累起来不容忽视。
其次，初始化 Agent 创建一个全面的功能列表文件。在 Anthropic 内部运行的 claude.ai 克隆实验中，这意味着超过 200 条具体的端到端功能描述，例如"用户可以打开一个新对话，输入查询，按下回车，并看到 AI 的回复"。每个功能最初都被标记为失败。
这个文件是项目的基准事实。一个开启新会话的编程agent 读取这个文件，就能立刻确定无疑地知道哪些东西已经构建完成、哪些尚未完成。它无法环顾四周，看到一些代码，就得出工作已完成的结论——功能列表会告诉它真相。
第三，初始化 Agent 创建一个 claude-progress.txt 文件并进行初始的 git 提交。进度文件是一个人类可读的日志，agent 在每次会话结束时更新它，记录自己处理了什么、完成了什么、以及将事情留在了什么状态。结合 git 历史记录，每一个后续编程 agent 都能快速定向，而无需将上下文预算耗费在考古工作上。
第二部分是编程 Agent。 初始化之后的每次会话使用不同的提示词：一次只处理一个功能，将环境留在干净的状态，并在会话结束前更新进度文件和 git 历史。增量推进，记录状态，干净交接。
功能列表作为认知锚点
功能列表值得特别关注，因为它解决了一个容易被低估的问题。没有它，在复杂代码库中运作的 agent 必须从代码本身推断项目的完成度。这种推断是不可靠的。
代码可能存在但并不可用；功能可能存在但并不完整。一个阅读代码并推断完成情况的 agent，会频繁得出错误答案，严重到足以构成问题。
功能列表使完成度变得明确无歧义。每个功能都有一个passes 字段，值为 true 或 false。 Agent 要么在端到端验证某功能可用后更新这个字段，要么不更新。没有歧义，不需要推断，基准事实就在文件里。
Anthropic 有意将这个列表存储为 JSON 而非 Markdown。原因是行为层面的。从经验来看，模型对 JSON 文件的不当修改或覆写概率，低于对 Markdown 文件的概率。
JSON 具有抵制随意编辑的刚性结构。这是一个细节，但后果真实存在：你希望功能列表是agent 谨慎更新的东西，而不是它心血来潮随意改写的东西。
{"category": "functional",
"description": "新建对话按钮创建一个全新的会话",
"steps": ["导航到主界面",
"点击"新建对话"按钮",
"验证新会话已创建",
"检查对话区域显示欢迎状态",
"验证对话出现在侧边栏中"],
"passes": false}
伴随此格式的指令是明确的：删除或编辑测试是不可接受的，因为这可能导致功能缺失或存在缺陷。你提示模型将这个文件视为不可侵犯的。 JSON 结构在架构层面强化了这一指令。
增量推进与干净状态要求
多会话 agentic 工作中最困难的问题之一，是确保每次会话结束时都处于一个下一次会话可以安全地在其上构建的状态。
若无明确的执行机制，agent 倾向于将工作留在上下文窗口填满时碰巧所处的状态：半成品功能、破损的测试、未记录的变更。下一个 agent 继承的是这团乱麻。
Anthropic 的解决方案是将干净状态作为一等要求，而非可有可无的附加项。每次编程 agent 会话以一次 git 提交（附有描述性信息）、对进度文件的更新以及在必要时回退到可工作状态为结尾。
他们所说的"干净状态"，意味着代码适合合并到主分支：没有重大缺陷、有良好文档、处于一个开发者可以合理地开始新功能而无需先解开他人半成品工作的状态。
git 提交不只是一个检查点，它是一个恢复机制。当 agent 做出破坏某些东西的变更时，它可以用 git 回退到最后已知的良好状态并重试。这正是人类工程师的工作方式，事实证明对 agent 同样是正确的纪律。版本控制是认知脚手架，而不仅仅是源代码管理。
测试：无人愿意谈论的失败模式
Anthropic 记录了一种几乎在每个认真的 agentic 编程项目中都会出现的失败模式：agent 在没有端到端验证的情况下将功能标记为完成。
Agent 会做出代码变更，对开发服务器运行单元测试或 curl 命令，看到通过结果，然后将功能标记为已完成。但当以用户方式通过浏览器测试时，该功能实际上并不可用。
单元测试成功与端到端功能可用之间的差距，是人类工程师通过切换上下文来跨越的——运行应用并尝试使用它。一个没有明确浏览器测试能力的 agent 无法完成这种切换。
它只能观察其工具所允许观察的内容，如果这些工具不包括浏览器自动化，它就会持续遗漏一类只在真实用户流程中显现的缺陷。
解决方案是为 agent 提供访问 Puppeteer MCP 服务器的能力——一个浏览器自动化工具，允许 Claude 实际导航应用、点击按钮、填写表单，并验证功能端到端可用。
性能提升是显著的。仅从代码中不可见的缺陷，当 agent 能够看到用户所见的内容时，变得一目了然。
这是一个通用原则的具体例证：agent 工作的质量受限于其反馈回路的质量。如果你的 agent 无法在真正重要的领域中观察到其行为的后果，它就会对代理指标进行优化，而这些指标可能与实际正确性并不相关。
启动流程：快速进入状态
Anthropic harness 中每次编程 agent 会话都以一套标准化的启动流程开始，其目的是在不浪费 token 的前提下尽快为 agent 定向。该流程如下：
运行pwd 确认工作目录；读取进度文件和 git log 以了解近期工作；读取功能列表并选择优先级最高的未完成功能；运行init.sh 脚本启动开发环境；运行基本的端到端测试以验证应用处于可工作状态。
只有完成所有这些步骤之后，agent 才会开始处理新功能。如果启动测试显示应用已损坏，agent 会在触碰任何新内容之前先修复已有问题。这防止了一种复合问题：agent 在破损的基础上开始新功能，使底层问题更难被隔离和修复。
启动流程还以一种具体的方式节省了 token：因为 init.sh 脚本精确记录了如何启动开发环境，agent 不需要从头摸索。每次会话在环境配置上节省的 token，在一个漫长项目中积累起来相当可观。
[助手] 我将首先确认方向，了解项目的当前状态。
[工具调用]
[工具调用]
[工具调用]
[助手] 让我检查 git log 以查看近期工作。
[工具调用]
[助手] 现在让我检查是否有 init.sh 脚本来重启服务器。
<启动开发服务器>
[助手] 很好！现在让我导航到应用，验证一些基本功能仍然正常运行。
<测试基本功能>
第四部分：OpenAI 的 Harness 工程（零行手写代码）
这场实验
2025 年 8 月下旬，OpenAI 的Codex 团队以一个唯一的约束条件创建了一个 git 代码库：无人工编写代码。代码库中的每一行代码——包括应用逻辑、测试、CI 配置、文档、可观测性工具和内部开发者实用工具——都将由 Codex agent 编写。人类负责引导，agent 负责执行。
五个月后，该代码库在上述所有类别中共包含约一百万行代码。大约 1500 个 PR 已被提交并合并。一个由三名工程师组成的小团队推动了其中大部分工作，平均每名工程师每天提交 3.5 个 PR。
随着团队扩充至七名工程师，每名工程师的吞吐量实际上还有所提升。该产品拥有数百名每日活跃的内部用户和外部 alpha 测试者。
这不是演示，而是一个完全通过 agent 生成代码构建和交付的真实内部产品。团队于 2026 年 2 月撰文描述了这段经历，其核心信息与 SWE-agent 论文一致：瓶颈从来不在模型能力，瓶颈始终在于环境设计。
工程工作的重新定义
OpenAI harness 工程文章中最重要的观察，是关于工程工作本身的变化。当你的主要工作不再是编写代码，你在做什么？
你在设计环境。你在明确意图。你在构建反馈回路。你在持续追问的不是"我如何修复这个缺陷？"而是"环境中缺少什么能力，导致这个缺陷反复出现？"
当某些东西失败时，修复方案几乎从来不是"更努力尝试"，而几乎总是"环境中缺少或配置错误了什么结构性要素，导致 agent 在这里失败？"这是工程思维的深刻转变：你不再调试代码，你开始调试产生代码的系统。
工程团队的首要工作变成了使 agent 能够完成有用的工作，而不是亲自完成这些工作。
在实践中，这意味着：将宏大目标分解为更小的构建模块，构建使这些模块可实现的工具和抽象，以及将失败作为信号，了解环境需要在哪些方面提供更好的支持。
人类工程师采用深度优先的工作方式：当 agent 卡住时，他们不会试图亲自编写代码，而是追问缺少什么，将其构建进环境，然后让agent 再次尝试。
代码库知识作为系统记录
OpenAI harness 中最重要的架构决策之一，是将代码库本身作为 agent 所需了解的一切内容的唯一真实来源。其洞察简单却意义深远：
从agent 的视角来看，任何它在运行时无法在上下文中访问的内容，实际上都不存在。存在于 Google 文档、Slack 消息线程或某人脑海中的知识，对系统而言是不可见的。
在项目早期，团队尝试了"一个大 AGENTS.md"的方案——一个单一的大型指令文件，包含 agent 需要了解的关于项目、架构、规范和约束的一切。它以可以预见的方式失败了，且以四种值得理解的方式失败。
第一，上下文是稀缺资源。一个庞大的指令文件挤占了任务、代码和相关文档的空间。 Agent 要么遗漏关键约束，要么开始为错误的目标优化。
第二，过多的指导变成了无指导。当一切都被标记为重要，就什么都不重要了。 Agent 开始局部模式匹配，而不是有意识地导航。
第三，它会瞬间腐化。随着代码库的演进，一体化手册变成了过时规则的坟场。
第四，它难以验证。一个单一的文本块不适合进行覆盖率检查、新鲜度追踪或交叉链接，漂移是不可避免的。
解决方案是一个被视为系统记录的结构化docs/ 目录，配合一个简短的 AGENTS.md 文件（约 100 行）作为地图，指向其他地方更深层的真实来源。
设计文档经过了分类和索引；架构文档提供了领域和包层次的顶层地图；计划被视为第一等制品，其进度和决策日志被提交进代码库。
这实现了团队所称的渐进式披露：agent 从一个小而稳定的入口点出发，被引导去知晓下一步该看哪里，而不是一开始就被淹没。结果是 agent 能够直接从代码库推断整个业务领域，无需访问可能不可用或可能已过时的外部上下文。
应用可读性：让系统对 Agent 可见
随着代码生成吞吐量的增加，瓶颈从生成转移到了验证。团队生成代码的速度超过了人工 QA 的验证能力。解决方案是通过让应用对 Codex 直接可读，使更多的验证工作成为 agent 能够自行完成的事情。
这涉及若干具体投入。他们使应用能够按 git worktree 启动，让 Codex 能够为它正在处理的每个变更启动并驱动一个应用的独立实例。
他们将 Chrome DevTools Protocol 接入 agent 运行时，并创建了处理 DOM 快照、截图和浏览器导航的工具。这使 Codex 能够直接复现缺陷、验证修复，并对 UI 行为进行推理，而不需要人类与应用交互。
他们构建了一套完整的本地可观测性技术栈：通过 LogQL、PromQL 和TraceQL 向 Codex 暴露日志、指标和追踪。
每个agent 任务都运行在一个完全隔离的、拥有独立可观测性数据的应用版本上，任务完成后即被销毁。这意味着agent 可以使用真实的可观测性工具调试类生产环境问题——与人类工程师使用的工具相同——而不必仅凭代码推断行为。
这里的原则与 SWE-agent 论文所论证的相同：agent 工作的质量受限于其反馈回路的质量。如果 agent 能看到用户所见的内容，并能观察到人类工程师所观察的相同指标和日志，它就能捕获并修复比仅能操作代码的 agent 宽得多的一类问题。
在不微观管理的情况下执行架构
在一个完全由 agent 生成的代码库中，随着时间推移维护架构一致性是最有趣的挑战之一。 Codex 会复制代码库中已存在的模式，包括不均匀或次优的模式。
久而久之，这会导致漂移：糟糕的模式扩散，不一致性积累，代码库对未来的 agent 运行变得更难正确导航。
OpenAI 的解决方案是机械化地执行不变量，而非依赖人工代码审查。应用围绕一个刚性的架构模型构建：每个业务领域划分为固定的层次集合，具有经过严格验证的依赖方向和有限的允许边界集合。
这些约束由自定义 linter（自然是由 Codex 编写的）和结构测试来执行。
核心洞察是执行边界，同时允许边界内的充分自由。 Linter 检查代码是否沿正确方向流经层次结构，但不规定边界内特定功能如何实现。这与平台团队在规模化时保持有效性的原则相同：执行基础，在其上允许自主。
这些 linter 是专门为 agent 生成有用错误消息而定制编写的。当 linter 捕获到一个违规时，错误消息包含格式化为可注入 agent 上下文的修复指令。这形成了闭环：被违反的约束、被违反的规则，以及修复步骤，全部在单一的可操作反馈消息中一并传递。
他们还将所谓的"黄金原则"直接编码进代码库：有主见的、机械化的规则，使代码库对未来的 agent 运行保持可读性和一致性。优先使用共享工具包而非手写辅助函数，在边界处验证数据形状。
这些原则通过周期性运行的后台清理任务来执行——扫描偏差、更新质量评级、提交针对性的重构 PR。其中大多数可在一分钟内完成审查并自动合并。
吞吐量改变了合并哲学
当 agent 吞吐量大幅超过人类注意力容量时，传统工程规范会变得适得其反。等待审查的PR 阻塞了 agent 的工作；逐一调查的测试偶发性失败消耗了本可用于更高杠杆任务的人类注意力。
OpenAI 的团队做出了一个有意为之的决定：以最小的阻塞合并门控来运作。 PR 保持短生命周期，测试偶发性失败通过重新运行来处理，而非无限期阻塞进度。
当agent 吞吐量远超人类注意力时，纠错是廉价的，等待是昂贵的。这个权衡在低吞吐量环境中看起来不负责任，在高吞吐量环境中则显而易见。
这对向 agent 驱动开发转型的团队而言是一个真正重要的洞察。当人类工程师亲自编写每一行代码时合理的合并哲学，在 agent 每名工程师每天生成 3.5 个 PR 时并不自动适用。瓶颈发生了转移，流程也需要随之转移。
第五部分：Awesome Agent Harness 分类体系
生态系统图谱
由 GitHub 上AutoJunjie 项目维护的 Awesome Agent Harness 代码库，试图绘制 harness 工程工具链这一新兴生态系统的全景图。在深入分类体系之前，有必要先明确其核心论点：AI 编写代码的能力实际上已经是一种商品。
基础模型可以生成可运行的代码，这不再是差异化能力。真正的差异化能力在于协调机制与环境设计。
该代码库将一个严肃的 agent harness 生态系统所需的完整技术栈划分为七个不同层次。理解这些层次，有助于解释为何"构建一个 AI 编程助手"实际上是许多相互独立的工程问题，而非一个单一问题。
第一层：人类监督
位于最顶层的是人类监督层，由人类负责审批提案、审查 PR、设定优先级。这在传统意义上并非一个技术层，而是人类判断与 agent 执行之间的接口。
此处的核心设计原则是：工程师应当负责设计环境、审查产出，而非直接编写代码。他们的杠杆来自于引导，而非执行。
第二层：规划与需求（Spec 工具）
这一层将人类的想法转化为结构化规格说明和任务 DAG（有向无环图），供 agent 可靠地消费执行。
其底层洞察在于：agent 是盲目执行的。如果规格说明模糊或存在歧义，agent 会按其自身的理解来产出结果，而这往往与人类的真实意图相悖。 Spec 工具在代码编写之前的需求阶段强制要求精确性。
该领域中的一个项目 Chorus，试图解决代码库所称的"反向对话缺口"。它并非让人类来撰写详细的规格工单（这是一个重大故障点，因为人类在 agent 所需的精确程度上并不擅长），而是让 AI 来提出任务 DAG 并细化需求，人类则在执行开始前扮演严格的验证与审批角色。
AI 从局部意图生成完整规格说明的能力，强于人类从零开始撰写的能力。
第三层：全生命周期平台
这类工具管理从初始需求到最终交付的端到端流程，将 AI 提案与人类验证关卡及子 agent 编排整合为一体。它们是规格层与执行层之间的粘合剂，负责处理整个开发生命周期中的状态管理。
第四层：任务运行器（Task Runners）
任务运行器弥合了问题追踪系统（GitHub Issues、Linear）与编程 agent 之间的鸿沟。其工作流如下：
由人类或 PM agent 创建 Issue，任务运行器生成工作空间，agent 交付 PR，人类进行审查。
这一类别中的工具包括：持续轮询任务队列、决定何时启动 agent、以及在无需人工介入执行循环的情况下完成工作交付的各类系统。
第五层：Agent 编排器
编排器通过在独立的 git worktree 中隔离各 agent 的工作，实现多 agent 并行执行，从而解决吞吐量问题。
这一点至关重要——如果多个 agent 并行工作时共享同一工作空间，彼此之间必然会产生冲突。 Git worktree 隔离为每个 agent 提供了独立的沙箱，使多个 agent 能够同时工作而互不干扰。
Vibe Kanban、Emdash、Composio 等工具均实现了这一模式。每个 agent 任务拥有独立的 git worktree，变更在隔离环境中得到验证后方可合并。
CI 反馈、合并冲突以及 agent 间的协调，均由编排层统一处理，无需人工干预。
第六层：Agent Harness 框架与运行时
框架提供用于构建自定义环境的可组合原语：渐进式披露机制、子 agent 生成、结构化上下文分发。运行时则提供持久化基础设施：长期记忆、定时执行、会话间多通道通信。
框架与运行时的区别至关重要。 框架是你在其上构建的东西，运行时是持续运行的东西。
Claude Agent SDK 主要是一个框架。而一个按 cron 计划运行 agent、跨会话维护持久记忆、处理 agent 实例间多通道协调的系统，则是一个运行时。两者对于严肃的长期 agentic 工作而言缺一不可。
第七层：编程 Agent
位于最底层的是执行层：Claude Code、Codex 及类似系统，负责编写、测试和调试代码。代码库的核心洞察在于：这一层是商品化的。 Agent 的有效性主要由技术栈中其上方的所有层级决定，而非 agent 本身。
这一颇具挑战性的论断有充分的证据支撑。 SWE-agent 论文通过实验验证了这一点：相同的模型，仅凭界面设计改进便带来了 64% 的性能提升。
OpenAI 的Codex 团队从实际操作层面验证了这一点：真正重要的工程工作是环境设计，而非执行本身。 Anthropic 的 harness 工程实践从实操层面验证了这一点：初始化 agent 的配置决定了编程 agent 能否顺利推进工作。
第六部分：反复出现的设计模式
纵观所有这些系统和组织，若干设计模式反复出现。这并非巧合，而是在尝试大规模可靠部署agent 时涌现出的问题所对应的工程解决方案。
模式一：渐进式披露（Progressive Disclosure）
不要预先将 agent 可能需要的所有信息一次性提供。给它定向所需的最小信息量，并提供必要时获取更多信息的指引。这一模式在以下场景中均有体现：
SWE-agent 的搜索结果上限（不返回全部结果，迫使 agent 进行精炼）、OpenAI 的 docs/ 架构（简短的地图指向更深层的内容）、Anthropic 的启动流程（先读进度文件，再读功能列表），以及实现结构化上下文分层的harness 框架。
采用这一模式的认知原因在于：上下文是有限资源，agent 的注意力并非均匀分布其间。位于提示词开头的信息具有不成比例的影响力。一个简短、聚焦的入口点，指向更丰富的上下文，比稀释注意力的大而全的信息堆砌更为有效。
实践原因在于可维护性。一个作为更深层文档地图的简短入口点，是可以保持准确的；而一个包罗万象的单体文档则会迅速变得陈旧，并产生反效果。
模式二：Git Worktree 隔离
一个 agent，一个worktree。这一模式出现在每一个严肃的编排系统中。其逻辑是直接的：当多个 agent 并行工作（或单个 agent 按序执行任务）时，需要在工作流之间保持隔离。若无隔离，并行 agent 会相互覆盖彼此的变更。
即便是顺序执行的 agent，也需要能够在隔离环境中验证变更，再将其影响扩散到主代码库。
Git worktree 在文件系统层面提供这种隔离。每个 agent 拥有独立的工作目录、独立的分支和独立的环境。
变更在隔离环境中产生、在隔离环境中测试，仅在通过验证后才被合并。这正是现代 CI/CD 系统为人类工程师所采用的模式，同时也被证明是 agent 编排的正确模型。
模式三：规格优先，代码库作为系统记录
Agent 对非正式知识是盲目的。任何存在于 Slack 消息、Google 文档或某人脑海中的信息，对 agent 而言都是不可见的。 Agent 能够处理的只有其上下文窗口中的内容，而该上下文的唯一可靠来源就是代码库。
这一模式体现为：Anthropic harness 中的功能列表文件、OpenAI 系统中结构化的 docs/ 目录、各开源框架中的 AGENTS.md 文件，以及 awesome-agent-harness 分类体系中的 spec 工具层。
共同主线是：规格说明、需求、架构决策和约束条件，必须在执行开始前编码为代码库中的机器可读文件。 如果 agent 无法从代码库中读取，它便不存在。
这对工程团队的文档工作方式具有重要含义。文档不再仅仅是为人类读者服务。它是人类意图对agent 可见的机制。模糊、陈旧或存储在代码库之外的文档，是积极损害 agent 性能的文档。
模式四：机械化架构执行
人工代码审查无法扩展到 agent 驱动的开发场景。当 agent 每名工程师每天能够提交 3.5 个 PR 时，审查不能成为维护代码质量和架构完整性的主要机制。解决方案是将架构约束编码为自动运行的机械化检查。
自定义 linter、结构测试和 CI流水线，取代了人工驱动开发中代码审查所承担的大部分功能。
机械化检查的优势在于：一致性强、速度快，并能在违规发生点提供即时反馈。一个捕捉到架构违规并在错误信息中返回修复指令的 linter，比三天后在 PR 评论中才捕捉到同一问题的代码审查者更为有效。
核心设计原则是执行不变量，而非实现细节。你深切关注的是依赖方向、边界跨越、接口处的数据校验以及命名与结构的一致性。
而 agent 使用哪个具体库、如何分解某个函数，只要满足行为契约，你并不在意。这在定义良好的结构内给予了 agent 充分的自主空间。
模式五：闭合的反馈回路
所有高性能的 harness 架构都将反馈回路收紧到极致。 linter 在编辑时捕获语法错误；运行时错误通过 agent 可查询的可观测性工具浮现；UI 缺陷通过 agent 可驱动的浏览器自动化工具发现；测试失败则附带上下文信息，说明哪里出了问题。
与之相对的另一种方式——agent 编写代码，在外部进行测试，在后续会话中才获得失败反馈——速度更慢、token 消耗更多，也更容易产生级联失败。反馈回路中每一个能够缩短行动与结果之间间隔的节点，都是可以提升 agent 性能的节点。
这是 harness 对于经典软件工程原则"尽早捕获错误"的具体演绎。错误发现得越早，修复成本越低。对 agent 而言，这一原则更具强制性——未被即时捕获的错误会在上下文中累积，并降低后续推理的质量。
第七部分：这对工程师究竟意味着什么
可迁移的技能
harness 工程这一学科，本质上是将系统思维应用于 agent 环境。它要求你对语言模型的认知架构有足够深入的理解，从而能够设计出顺应其运作机制而非与之对抗的环境。
它要求你以分布式系统工程中熟悉的方式来思考状态管理、反馈回路、错误恢复和上下文优化，只不过将其应用于一个全新的领域。
在这一新兴范式中最为高效的工程师，并不是那些拥有最佳提示词技巧的人——尽管提示词确实重要。
他们是那些理解整个系统运作方式的人：上下文如何流动、在哪里遭到污染、如何收紧反馈回路、如何跨会话保持状态，以及如何在不微观管理 agent 行为的前提下执行约束。
抽象地看，这些并非全新的技能，而是优秀软件工程师已有技能的延伸：系统设计、API 设计、错误处理、测试策略。真正新颖之处在于领域的转换：从为人类设计接口，转变为为语言模型 agent 设计环境。
你应该追问的问题
当你构建的 agent 系统出现问题时，harness 工程思维会引导出一套与朴素思维截然不同的问题。
与其问"我怎么写出更好的提示词？"不如问"agent 当前无法获取哪些它所需要的信息？
"与其问"为什么模型会犯这个错误？"不如问"缺少哪个反馈回路，导致这个错误在传播之前未能被捕获？
"与其问"agent 为什么没有按我说的去做？"不如问"环境中存在什么约束，阻止了 agent 执行我的指令？"
这种转变不只是语义层面的。它改变了你投入工程精力的方向。为某个特定故障模式设计更好的提示词，是局部的、临时的。构建能够预防一类故障模式的更好工具，是通用的、永久的。 harness 正是这种永久性投资的载体。
执行层的商品化
awesome-agent-harness 代码库核心论点中有一个令人不安的含义，值得直白地说出来。如果执行层是商品化的，那么 AI 驱动开发中的长期竞争壁垒就不在于模型本身，而在于 harness。
这意味着，那些投资于 harness 工程——构建脚手架、反馈回路、可观测性、规格工具以及使 agent 能够大规模可靠工作的编排系统——的组织和个人，将相较于那些主要专注于选择何种模型或如何提示的人，拥有持久的优势。
OpenAI 的 Codex 团队为其特定代码库和领域构建了相当于自定义开发平台的东西。 Anthropic 构建了一套 harness 架构，使其能够在复杂应用上实现数月的持续进展。 SWE-agent 团队构建了一套界面，使相同模型产出提升了 64% 的结果。这些优势没有一个来自模型本身，它们全部来自环境。
模型负责思考，harness 决定思考什么。把这个区别理解清楚，才是真正理解了这场游戏的全部。
第八部分：构建你自己的 Harness
最小可用 Harness
你不需要构建 OpenAI 的可观测性技术栈，也不需要 Anthropic 完整的双 agent 架构，就能从 harness 思维中获益。一个真实项目中针对编程 agent 的最小有效 harness，只需要少数几个核心组件。
从持久化进度文件开始。让 agent 在每次会话开始时读取它，以了解上次做了什么；在每次会话结束时写入它，以记录本次的工作。这一个单一改变，就能防止"过早宣告完成"的失败模式，并确保跨上下文窗口边界的工作连续性。
添加结构化任务列表。不是对项目的模糊描述，而是具体的、可枚举的、可验证的完成标准列表。每一项都应描述一个可端到端测试的用户可见行为，并标注状态——agent 只有在完成验证后才能更新该状态。这能防止"做了一半看起来像做完了"的失败模式。
将带有描述性提交信息的版本控制作为每次会话的一等公民。每次会话以一次提交结束。在代码提交且进度文件更新之前，agent 不应认为工作已完成。这创造了干净的交接，使多会话工作具有连贯性。
如果你在构建 Web 应用，请添加浏览器自动化。一个只能读取代码的 agent 与一个能够实际使用所构建应用的 agent，其差距，等同于一个只能读代码的开发者与一个能够运行应用的开发者之间的差距。大多数真正重要的 bug，只有在运行时才能显现。
环境审计
如果你已有一套 agent 系统但表现欠佳，harness 工程方法建议采用一套特定的诊断流程。不要急于寻找更好的模型或更长的提示词，而是做一次环境审计。
追问：agent 需要哪些它目前无法获取的信息？在任务流程中，agent 经常在哪些节点卡住或犯错？缺少什么反馈，导致 agent 无法自行捕获这些错误？上下文在哪里被无关信息污染？有哪些约束目前依赖 agent 的自我判断来执行，而应当被强制检查所取代？
每一个问题都指向一个具体的 harness 改进方向。信息缺失，变成代码库中的新工具或新文档；反馈缺失，变成新的测试、linter 或可观测性集成；上下文污染，变成新的上下文管理策略；未被执行的约束，变成新的机械化检查。
这是 harness 开发的良性循环：每一次失败都是环境需要改进的信号，而每一次环境改进都会降低该失败在未来所有 agent 会话中出现的频率。
最后一件事
变革性技术在早期阶段被误读，往往存在一个共同的规律。吸引公众眼球的东西——原始能力、令人印象深刻的演示、跑分成绩——鲜少是决定长期胜负的因素。基础设施层、harness、环境，通常才是真正价值被创造和捕获的地方。
Web 的变革性，不在于 HTML 的存在，而在于搜索引擎和浏览器让 Web 变得可导航。移动端的变革性，不在于智能手机的存在，而在于应用商店和开发者工具使得大规模地在智能手机上构建应用成为可能。在这两个案例中，组织和整合底层能力的平台层，才是持久价值的所在。
AI agent 正在遵循同样的规律。能力已然存在。问题是谁来构建让这种能力变得可靠、可控、持续可改进的环境。
SWE-agent 的研究者在 2024 年理解了这一点，并用数据加以证明。 Anthropic 在构建 Claude Code 时理解了这一点，并公开记录了下来。
OpenAI 在构建其内部产品时理解了这一点，并分享了相关经验。 awesome-agent-harness社区正在数十种工具和框架中对此进行系统性整理。
harness 就是一切。 模型是推理引擎，harness 是上下文、约束、反馈回路、记忆、工具和脚手架——它们共同决定推理引擎究竟能够完成什么。
把 harness 做对，不是一个提示词工程问题，而是一个系统工程问题。这是当前应用 AI领域最重要的工程问题。
请以此为指引，去构建。
