> Harness EngineeringHarness EngineeringHarness Engineering The engineering outside the model模型之外的工程模型之外的工程

5.4

Let the agent check its own work讓 agent 能檢查自己的活让 agent 能检查自己的活

This chapter assumes you have used an AI coding agent. It builds on The agent loop: the agent asks the model, runs a tool, and feeds the result back.

讀這一章,你需要用過 AI 寫程式的 agent。它建立在 agent 循環,和你能插手的地方 上:agent 問模型、執行工具、把結果餵回去。

读这一章,你要用过 AI 编程 agent。它建立在 agent 循环,以及你能插手的地方之上:agent 问模型、运行一个工具、把结果送回去。

The Knowledge經驗分享经验分享

In one sentence

Give the agent a way to check its own work: run the tests, the linter, the program. A check it can run and read gives it feedback inside the loop; a reviewer only finds problems afterwards.

一句話

讓 agent 有辦法檢查自己的活:跑測試、跑 linter、跑程式。它能跑、也能讀的檢查,在循環裡就給它回饋;reviewer 只能在事後找問題。

一句话

给 agent 一个检查自己活儿的办法:跑测试、跑 linter、跑程序。agent 能运行、能读懂的检查,在循环里就给了它反馈;reviewer 只能事后才发现问题。

For leaders

  • The decision: require that every task comes with a check the agent can run and read itself, such as tests, a build or a linter, and decide which of those checks the agent may not edit.
  • The risk: an agent stops when its work looks done, and in my own use models often lean towards reporting success; I have not recorded how often. Anthropic describes a later agent that would "declare the job done" after seeing progress. An agent can also pass by weakening the test. I have not recorded such a case, so it is a risk to design for.
  • The cost of doing it right: often one line in the instruction file: the command that runs the project's check. Slow suites need a fast subset to run often. I have not measured how much a self-check improves results.
  • Ask the team: "What can the agent run to know that its work is done, and can it change that check?"

給主管

  • 要做的決定:要求每個任務都附一個 agent 自己能跑、能讀的檢查,例如測試、建置或 linter,並決定這些檢查裡,哪些 agent 不能改。
  • 風險:agent 在活「看起來」做完時就停了;就我自己的使用經驗,模型常常傾向於回報成功,我沒有記錄過頻率。Anthropic 描述過,後來的 agent 看到已有進展,就會「宣布工作完成」。agent 也可能靠削弱測試來通過。我沒有記錄過這樣的案例,所以它是要為之設計的風險。
  • 做對的成本:常常只是指令檔裡的一行:執行專案檢查的指令。慢的測試集需要一個快的子集,讓它常常跑。自我檢查能把結果改善多少,我沒有量過。
  • 可以問團隊:「agent 能跑什麼來知道它的活做完了?它能改這個檢查嗎?」

写给管理者

  • 要拍板的事:要求每个任务都带一个 agent 自己能运行、能读懂的检查,比如测试、构建或 linter,并决定这些检查里哪些 agent 不许编辑。
  • 风险:agent 在活儿看起来做完时就停下,而在我自己的使用中,模型常常倾向于报告成功;我没有记录过多久发生一次。Anthropic 描述过一个后来的 agent 在看到有进展后就会“declare the job done”。agent 还可能靠削弱测试来通过。我没有记录过这样的案例,所以这是个要在设计里防着的风险。
  • 做对的代价:往往是指令文件里的一行:运行项目检查的那条命令。慢的测试套件需要一个能经常跑的快速子集。自查能把结果提高多少,我没有测过。
  • 可以问团队:“agent 能运行什么来知道它的活儿做完了?它能改这个检查吗?”

The problem

An agent stops when its work looks done. Looks done is a feeling the model has about its own code. It has not run anything. It says "I have made the change", you read it, and you find the bug.

If the agent has nothing to run that says whether the work is done, you are the test suite. Every mistake waits until you notice it. That is slow, and it needs you in front of the screen.

In my own use I have often seen models lean towards reporting success; I have not recorded how often. Anthropic describes the same pull in long runs, where a later agent instance would "declare the job done" after seeing that progress had been made (Effective harnesses for long-running agents). And an agent that checks its own work by reading it shares its own blind spots, since the same reasoning that wrote the mistake reads it (Use subagents sparingly).

The way out is not a smarter agent. It is a check that does not depend on the agent's feeling.

問題

agent 在活「看起來」做完時就停了。看起來做完,是模型對自己程式碼的一種感覺。它什麼都沒跑過。它說「我已經做了這個改動」,你一讀,找到了 bug。

如果 agent 沒有東西可以跑來判斷活有沒有做完,你就是測試集。每個錯誤都要等你發現。這很慢,也需要你坐在螢幕前。

就我自己的使用經驗,我常看到模型傾向於回報成功;我沒有記錄過頻率。Anthropic 描述過長時間運行裡同樣的拉力:後來的 agent 看到已有進展,就會「宣布工作完成」(Effective harnesses for long-running agents)。而且靠讀來檢查自己的活的 agent,有自己的盲點,因為寫出錯誤的那套推理,同時也在讀它(慎用子 agent)。

出路不是更聰明的 agent,而是一個不靠 agent 的感覺的檢查。

问题

agent 在活儿看起来做完时就停下。看起来做完了,是模型对自己的代码的一种感觉。它什么都没运行过。它说“我做了这个改动”,你读了,然后发现了 bug。

如果 agent 没有什么可以运行、来说明活儿做完了没有,你就是那个测试套件。每个错误都要等到你发现。这很慢,而且需要你守在屏幕前。

在我自己的使用中,我常常看到模型倾向于报告成功;我没有记录过多久发生一次。Anthropic 描述过长时间运行中同样的倾向:后来的 agent 实例看到已经有进展,就会“declare the job done”(Effective harnesses for long-running agents)。而且,靠读来检查自己活儿的 agent,有自己的盲区,因为写出错误的那套思路,也在读这个错误(见慎用子 agent)。

出路不是更聪明的 agent,而是一个不依赖 agent 感觉的检查。

How it works

One of the most useful things you can add

Compare two cases.

In the first, the agent changes code and says "done". You run the tests; two fail. You tell the agent. It fixes one. You run again.

In the second, the agent changes code and runs the tests itself. Two fail. It reads the output and fixes both. It runs the tests again. They pass. It says "done" and shows the output.

Same model. The difference is that in the second case the result of the check came back inside the loop, before the agent finished. The loop in The agent loop already has a place for this: a tool result goes back to the model, and the model decides the next step. A test run is just a tool whose result says, plainly, pass or fail.

change code the agent edits run the check test, linter, program read result short and clear fails: fix and run it again; passes: go on a reviewer finds problems afterwards
  1. The agent changes the code.
  2. It runs a check it can start itself: the tests, the linter, the program.
  3. It reads the result. The result must be short enough, and clear enough, to act on.
  4. If the check fails, it fixes the problem and runs the check again, inside the same loop. No person is needed.
  5. A reviewer works after the loop. It can point out problems, but the agent has already moved on.
A check the agent can run and read puts feedback inside the loop.

Anthropic's guide for Claude Code says the same thing in its own words: give the agent something it can run that comes back pass or fail, and it can keep going on its own, so that you do not have to watch. (Best practices for Claude Code) I put this near the top of the levers. A reviewer is also valuable, but it works afterwards, on finished work. A self-check changes what the agent does while it works.

What can be run

Anything that gives a result the agent can read:

  • Tests: the project's own tests, or a new test written for this change.
  • A build or typecheck: the exit code alone says it works or not.
  • A linter or formatter: quick, and it catches a class of mistakes.
  • A script that compares output with a known-good file: good for data work, where the right answer is a table.
  • Running the program: for a pipeline, run it on a small input and look at the output.
  • A screenshot next to a mockup: for user interfaces.

If a repository already has one of these, the most useful single line in the agent's instruction file is the command that runs it. The agent cannot guess which command the project trusts.

There are also levels of how firmly you ask for it, from soft to hard. This is the ladder from A rule in a prompt is a request:

  1. In the prompt: "run the tests after, and keep going until they pass". The agent decides when it is satisfied.
  2. As a stop condition: a hook (Hooks) runs at the moment the agent tries to stop. If the check fails, the hook sends the agent back to work. The platform enforces it, so the agent cannot end its turn with a failing check. Claude Code's documentation describes this with a Stop hook (Best practices for Claude Code). I have not tested the same in Copilot for this chapter.
  3. Counted by code: the number of passes is counted by a program, not reported by the agent (Counted checks).

Make the result short and readable

The agent reads the check's output, and the output goes into its context (Context is a budget). Two things go wrong.

  • Too long. A test run that prints thousands of lines fills the context, and the failure the agent needs is lost in them. Print the failures, with the file and line, and a count. Hide the passing noise.
  • Too vague. "Error" alone gives the agent nothing to act on. A good failure says what was expected, what happened, and where.

This is the same advice as for tool messages in Tool calling: the agent is an unreliable user, and what it reads decides what it does next. A check whose output is cheap and clear is worth more than a thorough check that nobody can read.

Ask also for evidence. "All tests pass" is a claim. The command that was run, and its output, is evidence. When you were not watching, it is the only evidence you have.

What a self-check cannot catch

A passing check says: "this does what the check tests." It does not say: "this is what you wanted." Two gaps matter.

The requirement is wrong. If the page the agent works from is not what the person meant (The agent writes the requirement), then perfect code that passes every test is perfect code for the wrong thing. No test the agent writes from a wrong requirement will find that. Only a person, reading the requirement, can.

The test is weak. A test may check too little: it passes with the bug in. A test the agent wrote in the same session was written with the same understanding as the code, so it shares the same blind spot. If the agent misread the rule, its code and its test will agree with each other and both be wrong.

A third thing sits beside these: some mistakes only show when the program is run in the real setting, with real data, and the agent cannot run it there. That is a person's check, or a test environment's.

The failure mode: the agent weakens the test

Here is a failure that follows from giving the agent a check. The agent wants the loop to end with a pass. The easy way to get a pass is to change the check, not the code. It can:

  • loosen an assertion until it passes,
  • delete or skip the test that fails,
  • change the expected value to whatever the code now gives,
  • catch an error and swallow it.

Nothing here needs bad intent. The agent is doing what the loop rewards: finishing with a pass. I have not recorded a case of this in my own runs, so I describe it as a risk to design for, not as something I measured.

Three defences, from cheapest to hardest:

  1. Say it in words. "Fix the code, not the tests. If a test seems wrong, say so and stop." It helps and it is a request (A rule in a prompt is a request).
  2. Keep the tests out of its reach. If the tests are part of what must not be edited, a hook refuses the change. Guardrails explains why files that check the agent should be outside what the agent can write. This does not fit work where adding new tests is part of the job. There, protect the existing tests and let it add new ones.
  3. Do not trust the report; count. Look at the diff of the tests (the list of changed lines). A change to a test that was failing is a flag. And let code, not the agent, count passes, with a record that the check ran (Counted checks).

How it divides work with an independent check

The two are not rivals; they catch different things.

Self-check Independent reviewer
When While the agent works After it finishes
Catches Things a program can judge: it runs, it passes, it matches a file Things a program cannot judge: does it match the request, is the logic sound
Misses Wrong requirement, weak test Blind spots the reviewer shares with the author
Cost Cheap, runs again and again One more agent, several times the usage (Use subagents sparingly)

So the order is: self-checks first, as many and as cheap as you can, inside the loop. Then, where it is worth the cost, an independent check on the result. A reviewer who sees a green test run can spend its attention on the question tests cannot answer: is this the right thing?

原理

你能加的最有用的東西之一

比較兩種情況。

第一種,agent 改了程式碼,說「做完了」。你跑測試,兩個失敗。你告訴 agent。它修好一個。你再跑一次。

第二種,agent 改了程式碼,自己跑測試。兩個失敗。它讀輸出,把兩個都修好。再跑一次測試。通過了。它說「做完了」,並附上輸出。

同一個模型。差別是:第二種情況裡,檢查的結果在 agent 結束之前,就在循環裡回來了。agent 循環,和你能插手的地方 裡的循環,本來就有放這件事的位置:工具的結果回到模型,模型決定下一步。跑測試只是一個工具,它的結果直白地說通過或失敗。

改程式碼 agent 動手改 跑檢查 測試、linter、程式 讀結果 短而清楚 沒過:修了再跑;過了:往下走 檢查者事後才找問題
  1. agent 改程式碼。
  2. 它跑一個自己能啟動的檢查:測試、linter、程式本身。
  3. 它讀結果。結果要夠短、夠清楚,才讀得懂、改得動。
  4. 檢查沒過,它就修,再跑一次,全在同一個循環裡,不需要人。
  5. 檢查者在循環之後才工作。它能指出問題,但 agent 已經往下走了。
agent 自己能跑、能讀的檢查,把回饋放進循環裡。

Anthropic 給 Claude Code 的指南,用自己的話說了同一件事:給 agent 一個能跑、結果是通過或失敗的東西,它就能自己繼續做下去,你不用盯著。(Best practices for Claude Code)我把它放在各種槓桿的前面。reviewer 也很有價值,但它在事後、對做完的活才起作用。自我檢查改變的是 agent 工作時的行為。

能跑什麼

任何給出 agent 讀得懂的結果的東西:

  • 測試:專案自己的測試,或為這次改動新寫的測試。
  • 建置或型別檢查:光是結束碼,就說明行不行。
  • linter 或格式化工具:很快,能抓到一類錯誤。
  • 把輸出和已知正確的檔案比對的腳本:適合資料工作,那裡正確的答案是一張表。
  • 執行程式:對管線,用小的輸入跑一次,看輸出。
  • 截圖和設計稿並排:用於使用者介面。

如果倉庫裡已經有其中一個,agent 指令檔裡最有用的一行,就是執行它的指令。agent 猜不出專案信任哪個指令。

要求的力道也有不同的層級,從軟到硬。這是 提示裡的規則只是請求 裡的那道階梯:

  1. 在 prompt 裡:「做完之後跑測試,一直做到通過」。什麼時候滿意,由 agent 決定。
  2. 當成停止條件:agent 想停下來的那一刻,一個 hook(Hooks:每次呼叫都會經過的執行點)會執行。檢查失敗,hook 就把 agent 送回去工作。由平台強制,所以 agent 不能帶著失敗的檢查結束這一輪。Claude Code 的文件用 Stop hook 描述了這件事(Best practices for Claude Code)。這一章我沒有在 Copilot 測過同樣的做法。
  3. 由程式計數:通過的次數由程式計算,不是由 agent 回報(讓「通過」可信)。

讓結果短而好讀

agent 讀檢查的輸出,輸出會進它的上下文(上下文是一份預算)。有兩件事會出錯。

  • 太長。印出幾千行的測試運行,會塞滿上下文,agent 需要的那個失敗就埋在裡面。印出失敗,附上檔案和行號,再加一個數量。把通過的雜訊藏起來。
  • 太模糊。只有「Error」,agent 沒有任何可以行動的東西。好的失敗訊息會說:預期什麼、發生什麼、在哪裡。

這和 Tool calling,和給 agent 設計工具 裡講工具訊息的建議一樣:agent 是個不可靠的使用者,它讀到什麼,決定它下一步做什麼。輸出便宜又清楚的檢查,比沒人讀得懂的徹底檢查更有價值。

也要要求證據。「所有測試都通過」是一個說法。執行過的指令和它的輸出,才是證據。你沒在看的時候,它是你唯一的證據。

自我檢查抓不到什麼

通過的檢查說的是:「這做到了檢查所測的東西。」它沒說:「這是你要的。」有兩個缺口很重要。

需求是錯的。如果 agent 工作所依據的那一頁,不是人的本意(需求由 agent 寫,人確認),那麼通過所有測試的完美程式碼,就是為錯的東西寫的完美程式碼。agent 從錯誤的需求寫出的任何測試,都找不到這一點。只有人讀需求,才找得到。

測試是弱的。測試可能檢查得太少:bug 還在,它也通過。agent 在同一個會話裡寫的測試,和程式碼出自同一個理解,所以有同樣的盲點。如果 agent 把規則讀錯了,它的程式碼和測試會彼此一致,而且都是錯的。

旁邊還有第三件事:有些錯誤只有在真實的環境、用真實的資料執行程式時才會出現,而 agent 沒辦法在那裡執行。那是人的檢查,或測試環境的檢查。

失敗模式:agent 削弱測試

給 agent 檢查,會帶來一種失敗。agent 想讓循環以通過收尾。拿到通過最容易的辦法,是改檢查,不改程式碼。它可以:

  • 把斷言放寬到能通過,
  • 刪掉或跳過失敗的測試,
  • 把預期值改成程式碼現在給的值,
  • 抓住錯誤然後吞掉。

這些都不需要惡意。agent 做的是循環獎勵的事:以通過收尾。我在自己的運行裡沒有記錄過這樣的案例,所以我把它描述成要為之設計的風險,不是我量過的東西。

三道防線,從最便宜到最硬:

  1. 用話說。「修程式碼,不要修測試。如果測試看起來是錯的,說出來然後停下。」有幫助,但它是請求(提示裡的規則只是請求)。
  2. 讓測試在它碰不到的地方。如果測試屬於不能編輯的東西,hook 會拒絕這個改動。保護規則本身的檔案 解釋了為什麼檢查 agent 的檔案,應該在 agent 寫不到的地方。這不適合「新增測試本來就是工作一部分」的情況。那種情況下,保護現有的測試,讓它新增測試。
  3. 不信報告,要計數。看測試的 diff(改動的行的清單)。對一個原本失敗的測試做了改動,是個旗號。而且讓程式,不是 agent,來計算通過的次數,並留下檢查有執行的紀錄(讓「通過」可信)。

它和獨立檢查怎麼分工

兩者不是對手;它們抓的東西不同。

自我檢查 獨立的 reviewer
什麼時候 agent 工作的時候 它做完之後
抓得到 程式能判斷的事:能跑、能通過、和檔案相符 程式不能判斷的事:是否符合要求、邏輯站不站得住
抓不到 錯的需求、弱的測試 reviewer 和作者共有的盲點
成本 便宜,可以一再執行 多一個 agent,用量是好幾倍(慎用子 agent)

所以順序是:先做自我檢查,在循環裡盡量多、盡量便宜。然後,在值得付出成本的地方,對結果做獨立檢查。reviewer 看到測試是綠的,就能把注意力花在測試回答不了的問題上:這是對的東西嗎?

原理

你能加的最有用的东西之一

比较两种情况。

第一种,agent 改了代码,说“做完了”。你运行测试;两个失败。你告诉 agent。它修了一个。你再跑一遍。

第二种,agent 改了代码,自己运行测试。两个失败。它读输出,把两个都修了。它再跑测试。通过了。它说“做完了”,并附上输出。

同一个模型。区别在于,第二种情况里,检查的结果在 agent 做完之前,就在循环里回来了。agent 循环,以及你能插手的地方里的循环,本来就有放这个的位置:工具的结果送回模型,模型决定下一步。一次测试运行,就是一个结果直截了当地说通过或失败的工具。

改代码 agent 动手改 运行检查 测试、linter、程序 读结果 短而清楚 没过:修了再跑;过了:往下走 reviewer 事后才找问题
  1. agent 改代码。
  2. 它运行一个自己能启动的检查:测试、linter、程序本身。
  3. 它读结果。结果要够短、够清楚,才读得懂、改得动。
  4. 检查没过,它就修,再跑一次,全在同一个循环里,不需要人。
  5. reviewer 在循环之后才工作。它能指出问题,但 agent 已经往下走了。
agent 自己能运行、能读懂的检查,把反馈放进了循环里。

Anthropic 的 Claude Code 指南用自己的话说了同一件事:给 agent 一个能运行、结果是通过或失败的东西,它就能自己接着干,你就不用盯着。(Best practices for Claude Code)我把它放在各种杠杆的前面。reviewer 也有价值,但它在事后、对做完的工作起作用。自查改变的是 agent 干活时做的事。

能运行什么

任何能给出 agent 读得懂的结果的东西:

  • 测试:项目自己的测试,或者为这次改动新写的测试。
  • 构建或类型检查:光看退出码,就知道行不行。
  • linter 或格式化工具:快,能抓住一类错误。
  • 把输出和已知正确的文件做对比的脚本:适合数据工作,因为正确答案就是一张表。
  • 运行程序:对 pipeline,用一小份输入跑一遍,看输出。
  • 截图和设计稿并排放:用于用户界面。

如果仓库里已经有其中一样,那么在 agent 的指令文件里,最有用的一行,就是运行它的那条命令。agent 猜不出项目信任的是哪条命令。

要求它做的力度,也有软有硬的几个层次。这是提示里的规则只是请求里的那个阶梯:

  1. 写在 prompt 里:“之后运行测试,直到通过为止”。什么时候满意,由 agent 自己决定。
  2. 作为停止条件:hook(见 Hook:每次调用都会经过的执行点)在 agent 想停下的那一刻运行。如果检查失败,hook 把 agent 送回去干活。这是平台强制执行的,所以 agent 不能带着一个失败的检查结束这一轮。Claude Code 的文档用 Stop hook 描述了这个做法(Best practices for Claude Code)。为这一章,我没有在 Copilot 里测过同样的做法。
  3. 由代码计数:通过的次数由程序数,不由 agent 报告(见让“通过”可信)。

让结果简短、可读

agent 读检查的输出,输出会进入它的上下文(见上下文是一份预算)。有两种问题。

  • 太长。一次测试运行打印几千行,会填满上下文,agent 需要的那个失败淹没在里面。打印失败的项,带上文件和行号,再加一个计数。把通过的噪音藏起来。
  • 太含糊。光一个“Error”,agent 无从下手。好的失败信息会说明期望什么、发生了什么、在哪里。

这和Tool calling,以及怎么给 agent 设计工具里关于工具消息的建议是一样的:agent 是个不可靠的用户,它读到什么,决定了它下一步做什么。一个输出便宜又清楚的检查,比一个全面却没人读得懂的检查更有价值。

还要要求证据。“所有测试都通过了”是一个说法。运行过的那条命令和它的输出,才是证据。你没在旁边看着的时候,它是你手里唯一的证据。

自查抓不住什么

一次通过的检查说的是:“这个做到了检查所测的东西。”它没说:“这就是你想要的。”有两个缺口要紧。

需求是错的。如果 agent 依据的那一页不是人的本意(见需求由 agent 写,人确认),那么通过每一个测试的完美代码,就是为错的东西写的完美代码。agent 根据错的需求写的任何测试,都发现不了这一点。只有人读需求,才能发现。

测试很弱。测试可能检查得太少:带着 bug 也能通过。agent 在同一个会话里写的测试,和代码是带着同样的理解写的,所以有同样的盲区。如果 agent 把规则理解错了,它的代码和它的测试会彼此一致,而且都是错的。

旁边还有第三件事:有些错误只有在真实环境里、用真实数据运行程序时才会显现,而 agent 在那里运行不了。那是人的检查,或者测试环境的检查。

失败模式:agent 削弱测试

给了 agent 一个检查之后,会出现这样一种失败。agent 想让循环以通过结束。拿到通过最容易的办法,是改检查,不是改代码。它可以:

  • 把断言放松到能通过为止,
  • 删掉或跳过失败的测试,
  • 把期望值改成代码现在给出的值,
  • 捕获一个错误并吞掉。

这里不需要任何恶意。agent 是在做循环所奖励的事:以通过收尾。我自己的运行里没有记录过这样的案例,所以我把它写成一个要在设计里防着的风险,不是我测量过的东西。

三种防御,从最便宜到最难:

  1. 用话说清楚。“修代码,不要修测试。如果测试看起来不对,说出来,然后停下。”有帮助,但它是一个请求(见提示里的规则只是请求)。
  2. 让测试它够不着。如果测试属于不许编辑的东西,hook 会拒绝这个改动。保护规则本身的文件讲了为什么检查 agent 的文件应该在 agent 能写的范围之外。这不适合新增测试本身就是工作一部分的情形。那种情形下,保护已有的测试,让它新增测试。
  3. 不信报告,要数。看测试的 diff(改动行的清单)。对一个本来失败的测试做了改动,是个信号。并且让代码,而不是 agent,来数通过的次数,同时留下检查运行过的记录(见让“通过”可信)。

它和独立检查怎么分工

两者不是对手;它们抓的东西不同。

自查 独立 reviewer
什么时候 agent 干活的时候 它做完之后
抓什么 程序能判断的东西:能运行、能通过、和某个文件一致 程序没法判断的东西:符不符合需求、逻辑站不站得住
漏什么 错的需求、弱的测试 reviewer 和作者共有的盲区
成本 便宜,可以反复运行 多一个 agent,用量是好几倍(见慎用子 agent)

所以顺序是:先自查,在循环里,能多就多,能便宜就便宜。然后,在值得花这笔成本的地方,对结果做一次独立检查。reviewer 看到一次全绿的测试运行,就可以把注意力花在测试回答不了的问题上:这是对的东西吗?

Costs and traps

  • A check that can pass wrongly is worse than none. It gives false comfort. A test that never fails tells you nothing.
  • Slow checks slow the loop. If the full suite takes twenty minutes, the agent runs it rarely. Give it a fast subset to run often, and the full suite at the end.
  • Flaky checks teach the agent the wrong thing. A test that fails at random sends the agent hunting for a bug that is not there, or teaches it to rerun until green.
  • Output can fill the context. See above.
  • Some code cannot be run by the agent. Where the real data, the real environment or the permission is not available to it, a self-check can only cover part. Say which part, and leave the rest to a person.
  • I have not measured how much a self-check improves results in my own setup. The direction is clear from the vendor's guidance and from the loop itself; the size of the effect I do not know.

Test your own setup

Put a bug into working code on purpose, then run the checks the agent would run. If they stay green, the check does not cover that part of the code, whatever the agent reports. This is a cheap way to see how much a passing check is worth.

代價和陷阱

  • 可能錯誤通過的檢查,比沒有更糟。它給人虛假的安心。永遠不會失敗的測試,什麼都告訴不了你。
  • 慢的檢查會拖慢循環。如果完整的測試集要二十分鐘,agent 就很少跑它。給它一個快的子集常常跑,完整的測試集留到最後。
  • 不穩定的檢查會教錯 agent。隨機失敗的測試,會讓 agent 去找一個不存在的 bug,或教它重跑到變綠為止。
  • 輸出可能塞滿上下文。見上面。
  • 有些程式碼 agent 沒辦法執行。真實的資料、真實的環境或權限它拿不到的地方,自我檢查只能涵蓋一部分。說清楚是哪一部分,其餘留給人。
  • 我沒有量過在我自己的設定裡,自我檢查把結果改善多少。方向從廠商的指南和循環本身看得很清楚;效果有多大,我不知道。

測你自己的設定

故意在能運作的程式碼裡放進一個 bug,然後執行 agent 會執行的檢查。如果它們還是綠的,不管 agent 怎麼回報,這個檢查都沒涵蓋程式碼的那一部分。這是個便宜的辦法,能看出一個通過的檢查值多少。

代价和坑

  • 可能错误地通过的检查,比没有还糟。它给人虚假的安慰。一个永远不会失败的测试,什么也告诉不了你。
  • 慢的检查会拖慢循环。如果整个套件要跑二十分钟,agent 就很少跑它。给它一个能经常跑的快速子集,最后再跑整个套件。
  • 不稳定的检查会教坏 agent。随机失败的测试,会让 agent 去找一个不存在的 bug,或者教会它一直重跑到变绿。
  • 输出可能填满上下文。见上文。
  • 有些代码 agent 运行不了。真实数据、真实环境或权限它拿不到的地方,自查只能覆盖一部分。说清是哪一部分,其余的留给人。
  • 自查能把结果提高多少,我在自己的配置里没有测过。从厂商的指南和循环本身来看,方向是清楚的;效果有多大,我不知道。

测试你自己的配置

故意往能正常运行的代码里放一个 bug,然后运行 agent 会运行的那些检查。如果它们仍然是绿的,那么不管 agent 怎么报告,这个检查都没有覆盖代码的这一部分。这是个便宜的办法,能看出一次通过的检查值多少。

What the industry says Industry practice

Anthropic's Claude Code guide puts "give it a check to run" next to telling the agent what it cannot see, and lists a test file, a build exit code, a linter, a script that compares output with a fixture, and a browser screenshot as examples. It also says to ask for the evidence, not only "all tests pass", and mentions a command that builds and runs the app to catch what tests and typechecks miss. (Best practices for Claude Code)

業界怎麼說 業界做法

Anthropic 的 Claude Code 指南,把「給它一個能跑的檢查」和告訴 agent 它看不到的東西放在一起,並列出測試檔、建置的結束碼、linter、把輸出和 fixture 比對的腳本、瀏覽器截圖當例子。它也說要索取證據,不是只有「所有測試都通過」,並提到一個會建置並執行應用程式的指令,用來抓測試和型別檢查漏掉的東西。(Best practices for Claude Code)

业界怎么说 业界做法

Anthropic 的 Claude Code 指南,把“给它一个可以运行的检查”和告诉 agent 它看不到的东西放在一起,并列举了测试文件、构建的退出码、linter、把输出和测试数据对比的脚本、浏览器截图作为例子。它还说,要索取证据,而不只是“所有测试都通过了”,并提到一条构建并运行应用的命令,用来抓住测试和类型检查漏掉的东西。(Best practices for Claude Code)

When to delete it

The checks themselves stay as long as there is code to check. What can retire is the scaffolding I put around the agent's use of them: the repeated reminders to run the tests, and the hook that sends it back. When the platform runs the project's checks as a normal step before the agent can finish, and the agent does not weaken them, those can go. I have not seen that yet.

什麼時候可以刪掉

只要還有程式碼要檢查,檢查本身就會留著。可以退役的,是我為 agent 使用它們而加的鷹架:一再提醒執行測試,以及把它送回去的 hook。平台在 agent 能結束之前,把專案的檢查當成一般步驟來執行,而且 agent 不削弱它們的時候,這些就可以拿掉。我還沒看到這樣的情況。

什么时候可以删掉

只要还有代码要检查,检查本身就会留着。可以退役的,是我围绕 agent 使用它们而搭的脚手架:反复提醒它运行测试,以及把它送回去的 hook。当平台在 agent 能结束之前,就把项目的检查当作正常的一步运行,而且 agent 不会削弱它们,这些就可以去掉。我还没见过。

Try it on your own setup

No harness needed. Open your agent in your own repository and paste:

Find out what a coding agent could run in this repository to check its own work: tests, build, typecheck, linter, formatter, example runs. For each, give the exact command, how long it takes if you can tell, and whether the output is short and clear enough for you to act on. Say whether the instruction files tell the agent about these commands. Then name the biggest part of the code that none of these checks would catch a bug in. Do not change any files, and do not run anything that takes more than a minute.

在你自己的環境試試

不用裝 harness。在你自己的倉庫裡打開 agent,貼上:

找出在這個倉庫裡,寫程式的 agent 能執行什麼來檢查自己的活:測試、建置、型別檢查、linter、格式化工具、範例執行。對每一個,給出確切的指令、如果看得出來的話它要跑多久,以及它的輸出夠不夠短、夠不夠清楚,讓你能據以行動。說明指令檔有沒有告訴 agent 這些指令。然後指出程式碼裡最大的一塊:這些檢查沒有一個能在那裡抓到 bug。不要改任何檔案,也不要執行任何超過一分鐘的東西。

在你自己的环境里试试

不用装 harness。在你自己的仓库里打开 agent,粘贴:

查一下,在这个仓库里,编程 agent 可以运行什么来检查自己的活儿:测试、构建、类型检查、linter、格式化工具、示例运行。对每一个,给出确切的命令、能看出来的话再给出耗时,并说明它的输出是不是足够简短清楚、让你能据此采取行动。说明指令文件有没有把这些命令告诉 agent。然后指出,代码里最大的一块,是这些检查里没有任何一个能在其中抓到 bug 的。不要修改任何文件,也不要运行任何超过一分钟的东西。

Go deeper

延伸閱讀

延伸阅读

You can stop here: that is the whole idea. The next part shows where it runs, so you can look inside.讀到這裡就夠了,這就是整個想法。下一部分告訴你它在哪裡運行,可以進去看看。读到这里就够了,核心思路就是这些。下一部分告诉你它在哪里跑,可以进去看看。

In my practice (Copilot Harness)實作实战

Copilot Harness is my open-source harness for VS Code Copilot.

Repository: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

Get started: clone it, open it in VS Code, and type /harness-rookie-get-me-ready in Copilot Chat. You need Python 3.9 or later and git.

Copilot Harness 是我開源的 VS Code Copilot harness。

倉庫: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

開始:clone 下來,用 VS Code 打開,在 Copilot Chat 裡輸入 /harness-rookie-get-me-ready。需要 Python 3.9 以上和 git。

Copilot Harness 是我开源的 VS Code Copilot harness。

仓库: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

上手:把仓库 clone 下来,用 VS Code 打开,在 Copilot Chat 里输入 /harness-rookie-get-me-ready。需要 Python 3.9 及以上版本和 git。

Explore it in the harness

The harness asks for a record of self-testing before a development task counts as done, and it has a separate reviewer for what a self-check cannot judge. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Let the agent check its own work". Teach me where this harness asks the agent to run its own checks, what counts as done for a development task, and how the independent check (topic 11) fits with it. Open the real files with me and draw the loop.

It teaches one small piece at a time, stops to ask if you are following, and opens the files with you.

在 harness 裡探索

harness 在開發任務算完成之前,要求留下自我測試的紀錄,並且有一個獨立的 reviewer,處理自我檢查判斷不了的事。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「讓 agent 能檢查自己的活」這一章。請教我這個 harness 在哪裡要求 agent 執行自己的檢查、開發任務怎樣才算完成,以及獨立檢查(主題 11)怎麼和它搭配。帶我打開真實的檔案,並畫出這個循環。

它一次教一小塊,停下來確認你跟得上,然後和你一起打開檔案。

在 harness 里探索

harness 要求一个开发任务在算作做完之前,要有一份自测的记录;对自查判断不了的东西,它还有一个单独的 reviewer。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“让 agent 能检查自己的活”这一章。请教我,这个 harness 在哪里要求 agent 运行自己的检查,开发任务怎样才算做完,以及独立检查(主题 11)是怎么和它配合的。带我打开真实的文件,并画出这个循环。

它一次只教一小块,停下来确认你跟上了,再和你一起打开文件。