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

B

Troubleshooting排錯排错

This appendix is for the day something goes wrong. Find your symptom, do the first check, then read the chapter. Everything here comes from the chapters and the harness docs. It is advice I can point to, not a complete list of causes.

這個附錄是給出事的那一天用的。找到你的症狀,做第一個檢查,再讀那一章。這裡的一切都來自各章和 harness 的文件。這是我能指出出處的建議,不是原因的完整清單。

这个附录是给出问题那天用的。先找到你的症状,做第一项检查,再去读对应的章节。这里的一切都来自各章和 harness 的文档。这是我能指出出处的建议,不是完整的原因清单。

How to use it

Two rules apply to almost every symptom.

  • Look at what happened, not at what the agent said. The agent's account of its own work can be wrong; a log can be checked (Record what happened).
  • Change one thing, then run the same task again. Otherwise you cannot tell which change helped (Fixed tasks, scored by a script).

Find your symptom by what you see:

怎麼用

有兩條規則,幾乎適用於每個症狀。

照你看到的找症狀:

怎么用

两条规则,几乎适用于每个症状。

按你看到的现象找症状:

Rules and instructions

The agent ignores a rule {#rule-ignored}

Check first. Is the rule actually loaded? Open a new chat and ask a question only your rules can answer (A minimal harness). If it is loaded, go through the usual causes in order: the file is too long, two rules conflict, the rule sits far from where it applies, it gives no reason, or it is only a request. If the rule must hold, move it into code.

Chapter. Instructions and skills, section "Why a written rule is ignored", then A rule in a prompt is a request.

The rules file is long and getting worse {#rules-rot}

Check first. For every line, ask whether the agent would get it wrong without it. Cut the lines that fail, then run the same task and see whether anything got worse. Keep each rule in one place.

Chapter. A minimal harness (costs and traps) and Instructions and skills.

A rule is followed in a short chat and dropped in a long one {#rule-drift}

Check first. Distance. A rule written in the first message is far away after hours of work. Put it nearer: load it by file, or have a hook repeat a few lines. Also try the cheap test of asking the agent to state the rule after an hour.

Chapter. Long chats get worse and Instructions and skills.

規則和指令

agent 無視一條規則 {#rule-ignored}

先檢查。這條規則真的載入了嗎?打開新的對話,問一個只有你的規則才答得出的問題(30 分鐘搭一個最小 harness)。如果載入了,依序檢查常見的原因:檔案太長、兩條規則衝突、規則離它適用的地方太遠、沒有給理由,或者它只是一個請求。如果這條規則必須成立,把它搬進程式碼。

章節。指令與 skill:只載入需要的,「寫下來的規則為什麼會被無視」一節,然後是 提示裡的規則只是請求。

規則檔很長,而且越來越糟 {#rules-rot}

先檢查。對每一行問:沒有它,agent 會做錯嗎?刪掉答案是否定的那些行,然後跑同一個任務,看有沒有變差。每條規則只放在一個地方。

章節。30 分鐘搭一個最小 harness(代價和陷阱)和 指令與 skill:只載入需要的。

規則在短對話裡被遵守,在長對話裡被丟掉 {#rule-drift}

先檢查。距離。寫在第一則訊息裡的規則,工作好幾個小時之後就離得很遠。把它放近一點:依檔案載入,或者讓 hook 重複幾行。也可以試一個便宜的測試:過了一個小時,請 agent 說出這條規則。

章節。長對話會變差 和 指令與 skill:只載入需要的。

规则和指令

agent 无视一条规则 {#rule-ignored}

先查什么。 这条规则真的加载了吗?开一个新对话,问一个只有你的规则才答得出的问题(30 分钟搭一个最小 harness)。如果加载了,就按顺序过一遍常见原因:文件太长,两条规则冲突,规则离它适用的地方太远,没有给理由,或者它只是个请求。如果这条规则必须成立,就把它挪进代码里。

章节。 指令与 skill:只加载需要的,“4. 写下来的规则为什么会被无视”一节,然后是提示里的规则只是请求。

规则文件很长,而且越来越差 {#rules-rot}

先查什么。 对每一行都问一句:没有它,agent 会不会做错?删掉通不过的行,然后跑同一个任务,看有没有变差。每条规则只放一个地方。

章节。 30 分钟搭一个最小 harness(代价和坑)和指令与 skill:只加载需要的。

规则在短对话里遵守,在长对话里被丢掉 {#rule-drift}

先查什么。 距离。写在第一条消息里的规则,干了几个小时之后就离得很远了。让它离得更近:按文件加载,或者让 hook 重复几行。还可以做个便宜的测试:干了一个小时之后,让 agent 把这条规则复述出来。

章节。 长对话会变差和指令与 skill:只加载需要的。

Skills

A skill is never used {#skill-not-loaded}

Check first. Open a new chat (an old one may already hold the skill), do not type the skill's name, and ask in the words a person would use. Then look at which skills were loaded, using the platform's log if it has one. If it did not load, the description lacks the user's words. If you have many skills, a neighbour may be taking the request: keep each skill narrow and say what it is not for.

Chapter. Instructions and skills, "Test that a skill is found"; A minimal harness (step 2).

A skill loads when it should not {#skill-too-wide}

Check first. The description is too wide. Narrow it, and write the neighbouring requests that must not trigger it as test cases.

Chapter. Instructions and skills.

A skill loads but nothing changes {#skill-no-effect}

Check first. Run the same task twice in new chats, with and without the skill. If you see no difference, cut the lines that make none; the agent already knew them. Then check that the skill is not out of date.

Chapter. Instructions and skills and Skills as workflows.

Skills

一個 skill 從沒被用到 {#skill-not-loaded}

先檢查。打開新的對話(舊的可能已經載入了這個 skill),不要輸入 skill 的名稱,用人會說的字來問。然後看載入了哪些 skill,如果平台有紀錄就用紀錄。如果沒載入,描述缺少使用者的字。如果你有很多 skill,可能是鄰近的搶走了請求:讓每個 skill 保持窄,並寫明它不是做什麼的。

章節。指令與 skill:只載入需要的,「測 skill 找不找得到」;30 分鐘搭一個最小 harness(第 2 步)。

一個 skill 不該載入時載入了 {#skill-too-wide}

先檢查。描述太寬。把它收窄,並把鄰近、不該觸發它的請求寫成測試案例。

章節。指令與 skill:只載入需要的。

一個 skill 載入了,卻什麼都沒變 {#skill-no-effect}

先檢查。在新的對話裡,把同一個任務各跑兩次,一次有 skill,一次沒有。如果看不出差別,就刪掉沒有差別的那幾行;agent 本來就知道。然後檢查這個 skill 有沒有過時。

章節。指令與 skill:只載入需要的 和 把團隊的做法寫成 skill。

Skill

skill 从来没被用上 {#skill-not-loaded}

先查什么。 开一个新对话(旧对话里可能已经装着这个 skill),不要输入 skill 的名字,用一个人平常会说的话去问。然后看加载了哪些 skill,平台有日志的话就用日志。如果没加载,说明描述里缺用户的说法。如果你有很多 skill,可能是旁边的某个抢走了请求:让每个 skill 保持狭窄,并写明它不管什么。

章节。 指令与 skill:只加载需要的,“测试 skill 能不能被找到”;30 分钟搭一个最小 harness(第 2 步)。

skill 不该加载的时候加载了 {#skill-too-wide}

先查什么。 描述太宽。收窄它,并把那些不该触发它的相邻请求写成测试用例。

章节。 指令与 skill:只加载需要的。

skill 加载了,但什么都没变 {#skill-no-effect}

先查什么。 在新对话里把同一个任务跑两遍,一遍带 skill,一遍不带。如果看不出差别,就删掉那些没起作用的行;agent 本来就知道它们。然后检查这个 skill 是否已经过时。

章节。 指令与 skill:只加载需要的和把团队的做法写成 skill。

Hooks and refusals

The hook did not fire {#hook-silent}

Check first. Four things, from what I found in October 2026 (they will change): the hook file is read when the window starts, so reload the window after a change; the hooks did not run when I used the command-line mode of Copilot; an organization policy can turn hooks off for a workspace; and a setting that looks like an off switch may not stop them in newer sessions. Then test with the smallest hook your platform allows: one that only appends the event name to a file.

Chapter. Hooks, "What a hook cannot see" and "Test your own setup".

The hook fired but the model did not get the message {#hook-lost-message}

Check first. Check what the model really received, not what the hook returned. In my case some prompts arrived without the rules, because the platform's own reminders took the slot the hook used (the numbers are in the chapter below).

Chapter. Hooks, the story at the top.

Every tool is refused after I changed the hook {#hook-wont-start}

Check first. If the hook program cannot start (for example the interpreter is not found), Copilot treats it as a refusal and no tool can run. The screen only says the hook errored. Run the hook command by hand in a terminal to see the real error.

Chapter. A minimal harness and Hooks, "Three ways a hook goes wrong".

A hook that should have blocked a call let it through, with no notice {#hook-timeout}

Check first. Time. A hook that runs past its limit is treated as a pass, silently. Measure how long your hook takes, and keep it cheap.

Chapter. Hooks and Build the enforcement layer like software, which is about deciding in advance whether a failure blocks or lets through.

The agent keeps trying the same refused thing {#refusal-loop}

Check first. Read the refusal reason. A reason that only says "denied" makes the agent retry or try something worse. Rewrite it to say why and what to do instead. But do not explain how to dodge the rule.

Chapter. Hooks (the reason is part of the design) and Asking is not a limit.

A refusal blocks real work {#false-refusal}

Check first. The pattern is too wide. The agent cannot argue with a refusal, so a false refusal is a stuck task. Narrow the pattern, keep a way for a person to approve what is wrong to refuse, and read the logs to see which rule fired.

Chapter. A rule in a prompt is a request and Asking is not a limit.

The agent got around a rule, or changed the rule files {#rule-bypassed}

Check first. Is the rule in a prompt or in a hook? What does the hook see: the text of the call, or its effect? A hook stops common spellings, not an agent set on getting around it. Also check that the files holding the rules and the hook are on the guarded list. For things that must never be touched, do not give them to the agent at all.

Chapter. Guard the files that hold the rules and Some things you never hand over.

The agent approved something for itself {#self-approval}

Check first. Test it: ask the agent to run the approval command and check that it is refused. If the hook that refuses it was removed, edited or failed, an agent that can run commands could approve for itself.

Chapter. Two gates: where a person approves.

Hook 和拒絕

hook 沒有觸發 {#hook-silent}

先檢查。四件事,來自我 2026 年 10 月的發現(它們會變):hook 檔是在視窗啟動時讀的,所以改了之後要重新載入視窗;我用 Copilot 的命令列模式時,hook 沒有執行;組織的政策可以為一個工作區關掉 hook;而且一個看起來像關閉開關的設定,在較新的會話裡可能擋不住它們。然後用你的平台允許的最小 hook 測試:只把事件名稱附加到一個檔案的 hook。

章節。Hooks:每次呼叫都會經過的執行點,「hook 看不到什麼」和「測你自己的設定」。

hook 觸發了,但模型沒收到訊息 {#hook-lost-message}

先檢查。檢查模型真正收到了什麼,不是 hook 回傳了什麼。在我的情況,有些 prompt 到達時沒有規則,因為平台自己的提醒占掉了 hook 用的位置(數字在下面那一章)。

章節。Hooks:每次呼叫都會經過的執行點,開頭的故事。

我改了 hook 之後,每個工具都被拒絕 {#hook-wont-start}

先檢查。如果 hook 程式啟動不了(例如找不到直譯器),Copilot 會當成拒絕,沒有任何工具能執行。畫面上只說 hook 出錯了。在終端機裡手動執行 hook 的指令,看真正的錯誤。

章節。30 分鐘搭一個最小 harness 和 Hooks:每次呼叫都會經過的執行點,「hook 出錯的三種方式」。

一個本來該擋下呼叫的 hook 放行了,而且沒有任何通知 {#hook-timeout}

先檢查。時間。執行超過時限的 hook,會被當成通過,而且是無聲的。量一量你的 hook 花多久,讓它保持便宜。

章節。Hooks:每次呼叫都會經過的執行點 和 把執行層當軟體來設計,後者講的是事先決定失敗時是擋下還是放行。

agent 一直試同一件被拒絕的事 {#refusal-loop}

先檢查。讀拒絕的原因。只寫「denied」的原因,會讓 agent 重試,或試更糟的事。改寫成說明為什麼,以及該改做什麼。但不要解釋怎麼閃躲這條規則。

章節。Hooks:每次呼叫都會經過的執行點(原因是設計的一部分)和 詢問不是限制。

拒絕擋住了真正的工作 {#false-refusal}

先檢查。樣式太寬。agent 沒辦法跟拒絕爭辯,所以錯誤的拒絕就是一個卡住的任務。把樣式收窄,保留一個讓人批准那些不該被拒絕的事的辦法,並讀紀錄看是哪條規則觸發的。

章節。提示裡的規則只是請求 和 詢問不是限制。

agent 繞過了一條規則,或改了規則檔 {#rule-bypassed}

先檢查。這條規則在 prompt 裡,還是在 hook 裡?hook 看到什麼:呼叫的文字,還是它的效果?hook 擋得住常見的寫法,擋不住一心要繞過它的 agent。也要檢查放規則和 hook 的檔案,是不是在受保護的清單上。對絕不能被碰的東西,根本不要給 agent。

章節。保護規則本身的檔案 和 有些東西根本不給。

agent 自己批准了某件事 {#self-approval}

先檢查。測試它:請 agent 執行批准的指令,確認它被拒絕。如果拒絕它的 hook 被移除、被編輯或失敗了,能執行指令的 agent 可能會為自己批准。

章節。兩道門:人在哪裡批准。

Hook 和拒绝

hook 没触发 {#hook-silent}

先查什么。 四件事,来自我在 2026 年 10 月的发现(它们会变):hook 文件在窗口启动时读取,所以改完之后要重新加载窗口;我用 Copilot 的命令行模式时,hook 没有运行;组织的策略可以对某个工作区关闭 hook;还有,一个看起来像关闭开关的设置,在较新的会话里可能拦不住它们。然后用你的平台允许的最小的 hook 来测:只把事件名追加到一个文件里的那种。

章节。 Hook:每次调用都会经过的执行点,“hook 看不到什么”和“测一测你自己的配置”。

hook 触发了,但模型没收到消息 {#hook-lost-message}

先查什么。 查模型实际收到了什么,不要查 hook 返回了什么。在我的情况里,有些 prompt 到达时没带规则,因为平台自己的提醒占了 hook 用的那个位置(数字在下面那一章里)。

章节。 Hook:每次调用都会经过的执行点,开头的那个故事。

我改了 hook 之后,所有工具都被拒绝 {#hook-wont-start}

先查什么。 如果 hook 程序启动不了(比如找不到解释器),Copilot 会把它当作拒绝,任何工具都跑不了。屏幕上只说 hook 出错了。在终端里手动运行 hook 的命令,就能看到真正的错误。

章节。 30 分钟搭一个最小 harness和Hook:每次调用都会经过的执行点,“hook 出问题的三种方式”。

本该拦住一次调用的 hook,悄悄放它过去了 {#hook-timeout}

先查什么。 时间。超出时限的 hook 会被当作通过,而且不会有任何提示。量一量你的 hook 要跑多久,让它保持轻量。

章节。 Hook:每次调用都会经过的执行点和把执行层当软件来设计,后者讲的是事先决定一次失败是拦截还是放行。

agent 一直重试同一件被拒绝的事 {#refusal-loop}

先查什么。 读一读拒绝的理由。只写“已拒绝”的理由,会让 agent 重试,或者去试更糟的办法。把它改成说明为什么,以及改做什么。但不要解释怎么绕开这条规则。

章节。 Hook:每次调用都会经过的执行点(理由是设计的一部分)和询问不是限制。

一次拒绝挡住了正常的工作 {#false-refusal}

先查什么。 匹配模式太宽。agent 没法和拒绝争辩,所以一次误拒就是一个卡住的任务。收窄匹配模式,留一条让人批准那些不该拒绝的事的路,再读日志看是哪条规则触发的。

章节。 提示里的规则只是请求和询问不是限制。

agent 绕过了一条规则,或者改了规则文件 {#rule-bypassed}

先查什么。 这条规则是在 prompt 里,还是在 hook 里?hook 看到的是什么:调用的文字,还是调用的效果?hook 拦得住常见的写法,拦不住一心要绕开它的 agent。还要检查,存放规则的文件和 hook 是否在受保护的名单上。对那些绝不能碰的东西,干脆不要交给 agent。

章节。 保护规则本身的文件和有些东西根本不给。

agent 替自己批准了某件事 {#self-approval}

先查什么。 测一下:让 agent 运行审批命令,确认它被拒绝。如果拒绝这条命令的 hook 被删了、被改了或者出错了,一个能运行命令的 agent 就可能替自己批准。

章节。 两道门:人在哪里审批。

Loops, stops and cost

The agent goes in circles {#agent-loops}

Check first. Does anything outside the agent judge that it is stuck? An agent that is stuck is the worst judge of that. Put stop rules in code, judged from facts: a limit on turns and time, a limit on refusals, no progress over several rounds, a changed plan, checks used up. Also see whether it keeps trying something the guardrails block.

Chapter. Unattended: when it must stop.

A stopped run left the person with a puzzle {#stop-vague}

Check first. Does the stop hand back why it stopped, where it is, and what a person has to decide, in one sentence? "Ran into a problem" is not enough.

Chapter. Unattended: when it must stop, "What a stop hands back".

The agent says "done" and the tests fail {#done-too-early}

Check first. Did it run a check and show the command and its output? A claim of "all tests pass" tells you very little by itself. Give it a way to run the checks inside its loop, and let the run end on facts (steps ticked, a counted check passed) and not on the agent's word.

Chapter. Let the agent check its own work and Unattended: when it must stop, "Guarding against done said too early".

Subagent usage does not add up {#subagent-usage}

Check first. A tool often shows the usage of the main conversation only. Check whether yours counts subagents too. Also remember that each subagent starts with an empty context and reads from zero, so several of them cost several times one agent. A limit on how many start is not a budget.

Chapter. Use subagents sparingly (costs and traps) and Unattended: when it must stop, section "A budget is a total, not a count".

The bill is higher than expected {#bill}

Check first. What the agent reads. Every turn rereads the whole context, so what is read matters more than how clever the model is. Look at tool results and loaded rules first, then at how often a task is redone. Do not cut so much that tasks fail and are thrown away. Check the usage numbers of one whole run, not one message. Cached context is billed at a lower rate (Anthropic's docs: about a tenth of the base price); I have not verified that on Copilot, so look at what your own plan shows.

Chapter. Choosing a model: cost per finished task, The agent loop and Context is a budget.

循環、停止和成本

agent 一直繞圈 {#agent-loops}

先檢查。有沒有 agent 之外的東西,判斷它卡住了?卡住的 agent,是最差的判斷者。把停止規則放進程式碼,從事實來判斷:一輪數和時間的上限、拒絕次數的上限、好幾輪都沒有進展、計劃改了、檢查次數用完。也看看它是不是一直在試護欄擋住的事。

章節。無人值守:什麼時候必須停。

一次停止,讓人面對一個謎 {#stop-vague}

先檢查。這次停止有沒有用一句話交回:為什麼停、停在哪裡,以及人要決定什麼?「遇到問題」是不夠的。

章節。無人值守:什麼時候必須停,「一次停止交回什麼」。

agent 說「做完了」,測試卻失敗 {#done-too-early}

先檢查。它有沒有執行檢查,並給出指令和輸出?一句「所有測試都通過」,本身告訴你的很少。給它一個在自己循環裡執行檢查的辦法,並讓運行以事實結束(步驟打勾、算數的檢查通過),不以 agent 的話為準。

章節。讓 agent 能檢查自己的活 和 無人值守:什麼時候必須停,「防著太早說「做完了」」。

子 agent 的用量加不起來 {#subagent-usage}

先檢查。工具通常只顯示主對話的用量。確認你的工具有沒有把子 agent 也算進去。也要記得,每個子 agent 都從空的上下文開始,從零讀起,所以好幾個子 agent 的花費是一個 agent 的好幾倍。對有多少個可以啟動的限制,不是預算。

章節。慎用子 agent(代價和陷阱)和 無人值守:什麼時候必須停,「預算是總量,不是次數」一節。

帳單比預期高 {#bill}

先檢查。agent 讀了什麼。每一輪都會重讀整個上下文,所以讀了什麼,比模型多聰明更重要。先看工具結果和載入的規則,再看任務被重做的頻率。不要砍到任務失敗、被丟掉。要看一整次運行的用量數字,不是一則訊息。快取的上下文用較低的費率計費(Anthropic 的文件:約基本價格的十分之一);我沒有在 Copilot 上驗證過,所以看你自己的方案顯示什麼。

章節。選模型:算的是每次成功的成本、agent 循環,和你能插手的地方 和 上下文是一份預算。

循环、停止和成本

agent 原地打转 {#agent-loops}

先查什么。 agent 之外有没有东西在判断它卡住了?卡住的 agent 恰恰是最不适合做这个判断的。把停止规则放进代码,根据事实来判断:轮数和时间的上限,拒绝次数的上限,几轮下来没有进展,计划变了,检查次数用完。还要看它是不是一直在试护栏拦着的事。

章节。 无人值守:什么时候必须停。

一次停下的运行,给人留下一个谜 {#stop-vague}

先查什么。 停下的时候,有没有用一句话交回:为什么停、停在哪、人要决定什么?“遇到了问题”是不够的。

章节。 无人值守:什么时候必须停,“3. 停下时交回什么”。

agent 说“做完了”,测试却失败 {#done-too-early}

先查什么。 它跑过检查,并给出命令和输出了吗?一句“所有测试都通过”,本身说明不了什么。让它能在自己的循环里运行检查,并让这次运行以事实结束(步骤打了勾,一次计数的检查通过了),不以 agent 的话结束。

章节。 让 agent 能检查自己的活和无人值守:什么时候必须停,“4. 防止过早说‘做完了’”。

子 agent 的用量对不上 {#subagent-usage}

先查什么。 工具往往只显示主对话的用量。看看你的工具有没有把子 agent 也算进去。还要记住,每个子 agent 都从空白的上下文开始,从零读起,所以几个子 agent 的成本是单个 agent 的好几倍。限制能开几个,不是预算。

章节。 慎用子 agent(代价和坑)和无人值守:什么时候必须停,“2. 预算是总量,不是次数”一节。

账单比预想的高 {#bill}

先查什么。 agent 读了什么。每一轮都会把整个上下文重读一遍,所以读了什么,比模型多聪明更要紧。先看工具返回的结果和加载的规则,再看任务被重做的频率。不要削得太狠,以至于任务失败被扔掉。看一整次运行的用量数字,不要看一条消息的。缓存的上下文按较低的价格计费(Anthropic 文档:约为基础价格的十分之一);我没有在 Copilot 上验证过,所以看你自己的套餐显示什么。

章节。 选模型:看每次成功的成本、agent 循环,以及你能插手的地方和上下文是一份预算。

Checks

The checks never pass {#checks-never-pass}

Check first. Read the findings. If each round brings new findings, the loop is open-ended: use a limit, and let the person extend or waive. If findings do not point to a real file and line, they are noise. If the verdict is wrong, a false FAIL sends the author to fix a problem that is not there. If edits keep cancelling earlier passes, the fingerprint of the work may include too much, such as progress notes.

Chapter. Make a pass count and Can a model check a model?.

Checks are on, but nothing was checked {#checks-silent}

Check first. The agent may simply never have called the checker, and then no FAIL is ever recorded. A rule in a prompt will not catch this. Put the check at a point the agent must pass, such as the moment it tries to stop.

Chapter. Make a pass count, "Checks on, but nothing checked".

A test passes sometimes and fails sometimes {#flaky}

Check first. A test that fails at random sends the agent hunting for a bug that is not there, or teaches it to rerun until green. Fix or drop it. If the full suite is slow, give the agent a fast subset to run often.

Chapter. Let the agent check its own work.

Two runs of the same task give different results {#variance}

Check first. That is normal. Run the task several times, look at the spread, and read the runs that failed. One run proves nothing. It is not normal when the spread is so wide that no result can be trusted; then the task is too loose or the check is too weak, and you should fix that first.

Chapter. One run proves nothing.

檢查

檢查一直過不了 {#checks-never-pass}

先檢查。讀發現的問題。如果每一輪都帶來新的發現,這個循環就沒有終點:設一個上限,讓人可以延長或豁免。如果發現沒有指向真實的檔案和行號,它們是雜訊。如果結論是錯的,錯誤的 FAIL 會讓作者去修一個不存在的問題。如果編輯一直抵銷先前的通過,這份工作的指紋可能包含太多東西,例如進度筆記。

章節。讓「通過」可信 和 模型能檢查模型嗎。

檢查開著,卻什麼都沒檢查 {#checks-silent}

先檢查。agent 可能根本從沒呼叫過檢查者,那就永遠不會有 FAIL 被記下。prompt 裡的規則抓不到這個。把檢查放在 agent 必須經過的地方,例如它想停下來的那一刻。

章節。讓「通過」可信,「檢查開著,卻什麼都沒檢查」。

一個測試有時通過、有時失敗 {#flaky}

先檢查。隨機失敗的測試,會讓 agent 去找一個不存在的 bug,或教它重跑到變綠為止。修好它,或丟掉它。如果完整的測試很慢,給 agent 一個快的子集,讓它常常執行。

章節。讓 agent 能檢查自己的活。

同一個任務跑兩次,結果不同 {#variance}

先檢查。這是正常的。把任務跑好幾次,看分布的範圍,並讀失敗的那幾次運行。一次運行證明不了什麼。如果範圍大到沒有結果可以信,那就不正常;這時任務太鬆,或檢查太弱,應該先修這個。

章節。一次運行證明不了什麼。

检查

检查一直通不过 {#checks-never-pass}

先查什么。 读一读发现的问题。如果每一轮都有新问题,这个循环就是没有尽头的:设一个上限,让人来延长或豁免。如果发现的问题没有指向真实的文件和行号,那就是噪音。如果结论是错的,一次误报的 FAIL 会让作者去修一个不存在的问题。如果改动不断抵消之前的通过,可能是这份工作的指纹包含的东西太多,比如进度笔记。

章节。 让“通过”可信和模型能检查模型吗。

检查开着,却什么都没检查 {#checks-silent}

先查什么。 agent 可能压根没调用过检查者,于是从来没有记下过 FAIL。prompt 里的规则抓不住这种情况。把检查放在 agent 必须经过的点上,比如它想要停下的那一刻。

章节。 让“通过”可信,“检查开着,却什么都没检查”。

一个测试有时过、有时不过 {#flaky}

先查什么。 随机失败的测试,会让 agent 去找一个不存在的 bug,或者教会它反复重跑直到变绿。修好它,或者去掉它。如果完整的测试集太慢,就给 agent 一个能经常跑的快速子集。

章节。 让 agent 能检查自己的活。

同一个任务跑两次,结果不同 {#variance}

先查什么。 这是正常的。把任务多跑几次,看波动范围,再读那些失败的运行。一次运行证明不了什么。如果波动大到没有哪个结果可信,那就不正常了;这时是任务太松,或者检查太弱,应当先把它们修好。

章节。 一次运行证明不了什么。

Context and memory

A long chat got worse {#long-chat}

Check first. Do not rely on the model to remember. Write what matters into a file, and start a fresh chat from that file. Test it: ask what you would lose if this chat disappeared now. If chats get long because the task is too big, the fix is a smaller task.

Chapter. Long chats get worse.

The notes or memory file says something false {#notes-wrong}

Check first. Treat notes as the agent's report: check the ones that matter against the source. Keep the notes short and cut what is done, because a growing notes file fills the window. Memory that an agent writes should carry a source and a date, and be reviewed by a person.

Chapter. Long chats get worse and What an agent should remember.

The agent obeyed text it read in a file or a web page {#injection}

Check first. Count the three circles: can it read private data, does it read untrusted text, can it send data out? Remove any one. A summary of untrusted text is untrusted too. Re-check whenever you add a tool.

Chapter. Text the agent reads can give it orders and MCP servers.

上下文和記憶

長對話變差了 {#long-chat}

先檢查。不要靠模型記住。把重要的寫進檔案,從那個檔案開一個新的對話。測試它:問自己,如果這個對話現在消失,你會失去什麼。如果對話變長,是因為任務太大,解法是更小的任務。

章節。長對話會變差。

筆記或記憶檔說了假的東西 {#notes-wrong}

先檢查。把筆記當成 agent 的報告:把重要的對照來源檢查。筆記要短,做完的就刪掉,因為越長越大的筆記檔會塞滿視窗。agent 寫的記憶,應該帶有來源和日期,並由人審查。

章節。長對話會變差 和 agent 該記住什麼。

agent 服從了它在檔案或網頁裡讀到的文字 {#injection}

先檢查。數那三個圈:它能不能讀私人資料、有沒有讀不可信的文字、能不能把資料送出去?去掉任何一個。不可信文字的摘要,也是不可信的。每次加一個工具,就重新檢查。

章節。agent 讀到的文字可能在指揮它 和 MCP server:插工具的標準接口。

上下文和记忆

长对话变差了 {#long-chat}

先查什么。 不要指望模型记得住。把要紧的写进文件,从这个文件开一个新对话。试一试:问问自己,如果这个对话现在消失,会丢掉什么。如果对话变长是因为任务太大,解法是把任务变小。

章节。 长对话会变差。

笔记或记忆文件里写了不实的内容 {#notes-wrong}

先查什么。 把笔记当作 agent 的报告:要紧的,对照源头核对。笔记保持简短,做完的就删掉,因为不断变长的笔记文件会把窗口填满。agent 写的记忆应当带来源和日期,并由人审查。

章节。 长对话会变差和agent 该记住什么。

agent 听从了它在文件或网页里读到的文字 {#injection}

先查什么。 数一数三个圈:它能读私有数据吗,它读不可信的文本吗,它能把数据发出去吗?去掉任何一个。不可信文本的摘要也是不可信的。每次加工具,都要重新检查。

章节。 agent 读到的文字可能在指挥它和MCP server:接工具的标准接口。

Seeing what happened

I cannot tell what the agent did {#cannot-tell}

Check first. Is there a record written by code, of every call and every refusal? Read the trace of a failed run, not the agent's summary. A hook sees only what the platform shows it, so a clean log can still have a hole.

Chapter. Record what happened, not what the agent said and A report a person can read in five minutes.

A new model made things worse {#model-upgrade}

Check first. An upgrade is not better at every task. Rerun your fixed tasks, then remove old rules and steps one at a time, running the evals after each.

Chapter. When the model is upgraded, delete.

看見發生了什麼

我說不出 agent 做了什麼 {#cannot-tell}

先檢查。有沒有一份由程式碼寫的紀錄,記下每個呼叫和每個拒絕?讀失敗那次運行的軌跡,不要讀 agent 的摘要。hook 只看得到平台給它看的東西,所以乾淨的紀錄仍然可能有洞。

章節。記下發生了什麼,不是 agent 說了什麼 和 一份五分鐘讀得完的報告。

新模型讓事情變糟 {#model-upgrade}

先檢查。升級不是在每個任務上都更好。重跑你的固定任務,然後一次刪掉一條舊的規則和步驟,每次之後都執行評測。

章節。模型升級了,就要刪。

看清发生了什么

我分不清 agent 做了什么 {#cannot-tell}

先查什么。 有没有一份由代码写下的记录,涵盖每次调用和每次拒绝?读失败那次运行的轨迹,不要读 agent 的总结。hook 只能看到平台给它看的东西,所以干净的日志里仍然可能有个洞。

章节。 记下发生了什么,而不是 agent 说了什么和一份五分钟读得完的报告。

换了新模型,反而更糟 {#model-upgrade}

先查什么。 升级并不是在每个任务上都更好。把你的固定任务重跑一遍,然后一次删一条旧规则或旧步骤,每次都跑评测。

章节。 模型升级了,就要删。