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

5.2

The agent writes the requirement, the person confirms it需求由 agent 寫,人確認需求由 agent 写,人确认

This chapter assumes you have used an AI coding agent. It builds on Manage tasks, not chats: a task is one job with one folder of files.

這一章假設你用過 AI 程式 agent。它建立在管任務,不管對話上:任務是一份工作,配一個放檔案的資料夾。

读这一章,你要用过 AI 编程 agent。它建立在管任务,不管对话之上:一个任务就是一件事,加一个放文件的文件夹。

The Knowledge經驗分享经验分享

In one sentence

People's requests are vague and they shift. Have the agent write the requirement on one page and the person confirm that page; everyone then works from it.

一句話

人的請求含糊,而且會變。讓 agent 把需求寫成一頁,由人確認這一頁;之後大家都照它做。

一句话

人提的需求含糊,还会变。让 agent 把需求写成一页,由人来确认这一页;之后大家都照它干活。

For leaders

  • The decision: require, for anything bigger than a small change, a one-page requirement that the agent writes and the requester confirms before work starts.
  • The risk: requests are vague, leave things out and shift over time. If the agent starts from the first message, every guess is built into the result and you find out at the end. I have no numbers on how often this happens.
  • The cost of doing it right: a few minutes of reading from the requester per task. For a one-line change it is too much, so small tasks can skip it. Too many questions also wear people out, and I have not measured how many is too many.
  • Ask the team: "Where is the page the requester confirmed, and what does its 'not clear yet' list say?"

給主管

  • 要做的決定:比小修改大的事,都要求一頁需求,由 agent 寫,由提出需求的人在開工前確認。
  • 風險:請求含糊、會漏東西、會隨時間改變。agent 從第一則訊息開始做的話,每個猜測都會被做進結果,到最後你才發現。這有多常發生,我沒有數字。
  • 做對的成本:每個任務請提出需求的人花幾分鐘讀。一行的修改就太多了,所以小任務可以跳過。問題太多也會讓人累,多少算太多,我沒有量過。
  • 可以問團隊:「提出需求的人確認過的那一頁在哪裡?它的『還不清楚』清單寫了什麼?」

写给管理者

  • 要拍板的事:凡是比小改动大的事,都要求先有一页需求,由 agent 来写,提需求的人在开工之前确认。
  • 风险:需求含糊,会漏东西,还会随时间变。如果 agent 从第一条消息就开工,每一个猜测都会做进结果里,你到最后才发现。这种事有多常发生,我没有数字。
  • 做对的代价:每个任务让提需求的人花几分钟读一读。对一行的改动来说太多了,所以小任务可以跳过。问题太多也会让人厌烦,多少算太多,我没有测过。
  • 可以问团队:“提需求的人确认过的那一页在哪里?它的‘还不清楚’清单上写了什么?”

The problem

You write: "add the customer region to the daily report." The agent does it. It is not what you meant. You meant the region of the shipping address; it used the billing one. Neither of you was wrong about the words. The words were not enough.

This is the normal case, not the odd one. A request to an agent has three weaknesses:

  • It leaves things out. You know the context, so you skip it. The agent does not know it, and it fills the gap with a guess.
  • It is read in more than one way. "Region" can mean several things.
  • It changes. Over a few turns you add a condition, drop another, change your mind. Which version is the request?

Here is the trap. If you let the agent start work from the first message, every guess is built into the result, and you find out at the end.

So the question is what the whole job should go by. The tempting answer is: the person's words, kept exactly. I tried to design that, and gave it up.

問題

你寫:「在每日報表加上客戶的地區。」agent 做了。這不是你的意思。你指的是收貨地址的地區;它用了帳單地址的。你們誰也沒有搞錯字面。字面不夠用。

這是常態,不是特例。對 agent 的請求有三個弱點:

  • 它會漏東西。你知道背景,所以就略過了。agent 不知道,它用猜測填補空缺。
  • 它可以有不止一種讀法。「地區」可以指好幾種東西。
  • 它會變。幾輪之內,你加一個條件、拿掉另一個、改變主意。哪一版才是請求?

陷阱在這裡。讓 agent 從第一則訊息就開工,每個猜測都會被做進結果,到最後你才發現。

所以問題是:整份工作要以什麼為準。誘人的答案是:人說的原話,原封不動地留著。我試著設計過,放棄了。

问题

你写:“在日报里加上客户所在地区。”agent 做了。但不是你的意思。你指的是收货地址的地区,它用的是账单地址的。你们俩对字面的理解都没错。光有字面不够。

这是常态,不是个别情况。给 agent 的一条需求有三个弱点:

  • 它会漏东西。你熟悉背景,所以略过了。agent 不熟悉,它用猜测把缺口补上。
  • 它可以有不止一种读法。“地区”可以指好几样东西。
  • 它会变。几轮之间,你加一个条件、去掉一个、改了主意。到底哪一版才是需求?

陷阱在这里。如果让 agent 从第一条消息就开工,每一个猜测都会做进结果里,你到最后才发现。

所以问题是:整件事该以什么为准。诱人的答案是:人说的原话,原样保留。我试着设计过,后来放弃了。

How it works

Why I do not keep the person's exact words

My first idea was to record every prompt, so that "what the person asked" is always on disk. It fails for the reasons above. The words leave things out and are unclear. The requirement shifts over turns, so the first prompt is not it and the last prompt alone is not it either. Keeping them all also fills the context (Context is a budget) with chatter that the agent then has to sort out again.

So the exact words are not the requirement. The requirement is what the person means, written down so that they can check it.

The agent writes it; the person confirms it

The agent writes the requirement from the conversation, as one page. The person reads that page and confirms it. This is the requirement file, the one file every later step goes by.

vague words may leave things out agent asks about what it cannot look up one-page requirement written by the agent person confirms reads the page, not the chat a change goes into the page first
  1. The person says what they want. It is short, it leaves things out, and it may change next hour.
  2. The agent first looks up what it can find itself. It asks only about what it cannot: intent, scope, what counts as done.
  3. The agent writes the answer as one page the person can read in minutes.
  4. The person confirms the page. From now on the plan, the work and the checks all go by this page.
  5. When the request changes, the page changes first, and the person confirms it again.
The requirement is a page the agent writes and the person confirms. The person's first words are not it.

Why this order, and not "the person writes it"? Because people do not like writing specifications, and the page is much easier to check than to write. Reading "you will use the shipping address" and saying "yes" or "no, billing" is cheap. Producing the whole page from nothing is not. It uses what the agent is good at (turning a mess into a structure) and what the person is good at (knowing what they meant).

It also gives the confirmation a clear meaning. The person is not confirming "I understood you". They are confirming "this page is what I want".

What goes on the page

Keep it to what the later steps need:

  • The goal: what should be true when this is done.
  • What to do, and what not to do: the scope and its limits.
  • Done when: the checks that show it is finished, each one something a person or a program can verify.
  • Where each point came from: the file and place in the sources, or the person's answer.
  • Not clear yet: the open questions. This is an honest list, not a hidden guess.

"Done when" matters most. The independent check (Use subagents sparingly) goes by this page alone, and so do the self-checks in Let the agent check its own work.

How the agent asks

An agent that asks too much is as bad as one that guesses. The rules I give it come from my own use; I have not tested them against other ways of asking:

  1. Stop before work. While things are unclear it only reads. It changes nothing.
  2. Look up what can be looked up. Which test framework the project uses is in the repository. Asking about it wastes the person's time.
  3. Ask only what cannot be looked up: intent, preference, trade-offs, what counts as done.
  4. Give options and a recommendation. "A, B or C; I suggest B because..." is easier to answer than "what do you want?". A recommendation is advice; it does not count until the person confirms.
  5. Do not take a shrug as a yes. "Whatever" is not a confirmation. Ask back once: "I will do X. Is that all right?" and write down that the person agreed to leave it to the agent.
  6. Ask in batches that follow dependencies. Upstream questions first, a few at a time.

The method is plain, and the point is the first rule: the agent must not fill in with its own guess what the person did not say. The default that looks obvious is where a guess goes wrong most easily.

When the requirement is a pile of documents

This part matters only when the request comes as business documents.

Sometimes the request is a business paper, a spreadsheet of mappings and some emails. Giving these to the agent as they are costs context and invites mistakes: a Word file carries a cover page, a revision history and comments; a spreadsheet has hidden sheets and colours that mean something. A binary file is not text at all.

So a program, not a model, turns them into plain text first. Word becomes Markdown; each sheet becomes a table in a text file. The original is kept untouched, and a short report lists what the program left out, such as hidden sheets or pictures. This costs no tokens, and it should change no number, though it can lose meaning that sits in layout or colour (see Costs). The person trims the text and adds a short note on what the job is. Then the agent reads that and writes the one page.

Two rules keep the agent honest here. A number that looks wrong is quoted and asked about, never corrected. Two sources that disagree are a finding to report, not something to settle by itself. This is the same split as Who decides: a program for the fixed conversion, a model for the reading.

The review of the requirement

Once the page exists, it can be checked before any work starts. In my setup the agent compares it with what is known about the system, such as the knowledge base (an index of the code kept for the agent, A knowledge base: an honest index of the code; skip this step if you have none), and writes each problem into the "not clear yet" list: the question, why it matters, and the source. It asks the person the few most blocking questions, puts each answer into the page, and repeats until the list is empty and the person confirms.

Two things guard against a bad review. The agent asks only where the documents contradict each other, are wrong, or do not match the system. It does not ask the person to confirm what the documents clearly say. And it leaves the confirmation line to the person: only they fill it in.

When the request changes

It will change. The rule is that the page changes first. The agent edits the requirement, adds a line to the change record, and only then touches the work. If the person's latest instruction conflicts with the page, a hook reminds the agent to bring them in line before doing anything.

A plan stands on a confirmed requirement. In my setup, approving a plan is refused while the requirement is unconfirmed or has changed since (Two gates). If the requirement changes after work began, the person confirms it again, approves the plan again, and the work already done is checked again, not thrown away.

Test your own setup

Give the agent a short request with two sentences that contradict each other, for example one that says the report is daily and one that says it is weekly. See whether the page it writes lists the conflict under "not clear yet", or quietly picks one. If it picks one, the page is sounding sure about a guess.

原理

為什麼我不留人的原話

我的第一個想法是記錄每個 prompt,讓「人要求了什麼」永遠在磁碟上。它因為上面的理由行不通。原話會漏東西,也不清楚。需求在幾輪之間會變,所以第一個 prompt 不是它,只看最後一個 prompt 也不是。全部留著,還會用閒聊塞滿上下文(上下文是一份預算),而 agent 還得再整理一遍。

所以原話不是需求。需求是人想表達的意思,寫下來,讓他能檢查。

agent 寫,人確認

agent 根據對話把需求寫成一頁。人讀這一頁並確認。這就是需求檔,之後每一步都以這一個檔案為準。

幾句含糊的話 可能 漏東西 agent 追問 問它 查不到的 一頁 需求 由 agent 來寫 人 確認 讀這一頁, 不是讀聊天 有變動,先改這一頁
  1. 人說出想要什麼。話很短,會漏東西,一小時後還可能變。
  2. agent 先查自己查得到的。只問查不到的:意圖、範圍、怎樣才算完成。
  3. agent 把答案寫成一頁,人幾分鐘就能讀完。
  4. 人確認這一頁。之後計畫、工作、檢查都以這一頁為準。
  5. 請求變了,先改這一頁,人再確認一次。
需求是 agent 寫、人確認的一頁。人最初說的話不是需求。

為什麼是這個順序,不是「人來寫」?因為人不喜歡寫規格,而這一頁檢查起來比寫容易得多。讀到「你會用收貨地址」,回答「對」或「不,用帳單的」,成本很低。從零產出整頁就不是了。這個順序用上了 agent 擅長的(把一團亂變成結構)和人擅長的(知道自己的意思)。

它也讓確認有了清楚的意義。人確認的不是「我懂你了」。他確認的是「這一頁就是我要的」。

這一頁寫什麼

只寫後面幾步需要的:

  • 目標:做完時什麼應該成立。
  • 要做什麼、不做什麼:範圍和它的邊界。
  • 做完的條件:顯示它做完了的檢查,每一項都是人或程式能驗證的。
  • 每一點的來源:來源資料裡的檔案和位置,或人的回答。
  • 還不清楚:未解決的問題。這是一張誠實的清單,不是藏起來的猜測。

「做完的條件」最重要。獨立檢查(慎用子 agent)只看這一頁,讓 agent 能檢查自己的活裡的自我檢查也是。

agent 怎麼問

問太多的 agent 和亂猜的一樣糟。我給它的規則來自我自己的使用;我沒有拿它們和別的問法比較過:

  1. 開工之前先停。還不清楚的時候它只讀,什麼也不改。
  2. 查得到的先查。專案用哪個測試框架,在倉庫裡看得到。問這個是浪費人的時間。
  3. 只問查不到的:意圖、偏好、取捨、什麼算做完。
  4. 給選項,也給建議。「A、B 或 C;我建議 B,因為……」比「你要什麼?」好回答。建議只是建議;人確認之前不算數。
  5. 不把聳肩當成同意。「隨便」不是確認。反問一次:「我打算做 X。可以嗎?」並寫下人同意交給 agent 決定。
  6. 按相依關係分批問。上游的問題先問,一次幾個。

方法很平淡,重點是第一條:agent 不可以用自己的猜測,填補人沒說的東西。看起來理所當然的預設,是猜測最容易出錯的地方。

需求是一堆文件的時候

這一部分只在請求以業務文件的形式送來時才重要。

有時請求是一份業務文件、一張對應表的試算表和幾封信。原樣交給 agent,既花上下文,也容易出錯:Word 檔帶著封面、修訂歷史和註解;試算表有隱藏的工作表,還有帶意義的顏色。二進位檔案根本不是文字。

所以先由程式,不是模型,把它們轉成純文字。Word 變成 Markdown;每張工作表變成文字檔裡的一個表。原件原封不動地保留,並由一份簡短的報告列出程式漏掉的東西,例如隱藏的工作表或圖片。這不花 token,而且不該改動任何數字,不過它可能丟掉藏在版面或顏色裡的意義(見代價)。人修剪這份文字,加一小段說明這份工作是什麼。然後 agent 讀它,寫出那一頁。

有兩條規則讓 agent 在這裡保持誠實。看起來不對的數字要引用出來、提出來問,絕不修正。兩份互相矛盾的來源是要回報的發現,不是自己去裁決的事。這和誰來判斷:程式、便宜模型、主模型、人是同一種分工:固定的轉換交給程式,閱讀交給模型。

需求的審查

這一頁一旦存在,就可以在任何工作開始之前被檢查。在我的設定裡,agent 拿它和已知的系統資訊對照,例如知識庫(為 agent 保存的一份程式碼索引,知識庫:程式碼的誠實索引;沒有的話跳過這一步),並把每個問題寫進「還不清楚」清單:問題、為什麼重要,和來源。它向人問最卡住的幾個問題,把每個答案放進這一頁,一直重複,直到清單空了、人確認為止。

有兩件事防止糟糕的審查。agent 只在文件互相矛盾、有錯、或和系統對不上的地方問。文件寫得清楚的,它不請人確認。而且確認那一行留給人:只有人才能填。

請求改變的時候

它一定會變。規則是:先改這一頁。agent 編輯需求,在變更紀錄裡加一行,然後才碰工作。如果人最新的指示和這一頁衝突,hook 會提醒 agent 先把兩者對齊,再做任何事。

計劃建立在已確認的需求上。在我的設定裡,需求還沒確認、或確認後又改了的時候,批准計劃會被拒絕(兩道門:人在哪裡批准)。開工之後需求才改的話,人要重新確認,重新批准計劃,已經做完的工作要重新檢查,不是丟掉。

測一下你自己的設定

給 agent 一個簡短的請求,裡面有兩句互相矛盾的話,例如一句說報表是每天的,一句說是每週的。看它寫的那一頁,是把衝突列在「還不清楚」下面,還是悄悄選了一個。選了一個的話,這一頁就是對一個猜測說得很有把握。

原理

为什么我不保留人的原话

我最初的想法是记录每一条 prompt,这样“人要求了什么”始终在磁盘上。它因为上面那些原因行不通。原话会漏东西,也不清楚。需求在几轮之间会变,所以第一条 prompt 不是需求,只看最后一条 prompt 也不是。全部留着,还会用一堆闲聊填满上下文(见上下文是一份预算),agent 之后又得重新把它们理清。

所以原话不是需求。需求是人想表达的意思,写下来,让他能检查。

agent 来写,人来确认

agent 根据对话把需求写成一页。人读这一页,并确认它。这就是需求文件,之后每一步都以这一个文件为准。

几句含糊的话 可能 漏东西 agent 追问 问它 查不到的 一页 需求 由 agent 来写 人 确认 读这一页, 不是读聊天 有变动,先改这一页
  1. 人说出想要什么。话很短,会漏东西,一小时后还可能变。
  2. agent 先查自己查得到的。只问查不到的:意图、范围、怎样才算做完。
  3. agent 把答案写成一页,人几分钟就能读完。
  4. 人确认这一页。之后计划、工作、检查都以这一页为准。
  5. 需求变了,先改这一页,人再确认一次。
需求是 agent 写、人确认的一页。人最初说的话不是需求。

为什么是这个顺序,而不是“人来写”?因为人不喜欢写规格说明,而且这一页检查起来比写起来容易得多。读到“你会用收货地址”,回答“对”或者“不对,用账单地址”,成本很低。从零写出整页,成本就不低了。这个顺序用到了 agent 擅长的(把一团乱整理成结构)和人擅长的(知道自己是什么意思)。

它还让确认有了清楚的含义。人确认的不是“我听懂你了”,而是“这一页就是我要的”。

这一页上放什么

只放后面几步需要的:

  • 目标:做完之后,什么应该成立。
  • 要做什么,不做什么:范围和它的边界。
  • 做完的标准:表明已经做完的检查,每一条都是人或程序可以验证的。
  • 每一点的来源:来源文档里的文件和位置,或者人的回答。
  • 还不清楚:悬而未决的问题。这是一份诚实的清单,不是一个藏起来的猜测。

“做完的标准”最要紧。独立检查(见慎用子 agent)只以这一页为准,让 agent 能检查自己的活里的自查也是。

agent 怎么提问

问得太多的 agent,和乱猜的 agent 一样糟。我给它定的规则来自我自己的使用;我没有拿它们和别的提问方式比较过:

  1. 开工之前先停。还不清楚的时候,它只读,什么都不改。
  2. 能查到的先查。项目用哪个测试框架,仓库里就有。去问这个是浪费人的时间。
  3. 只问查不到的:意图、偏好、取舍、怎样才算做完。
  4. 给出选项和推荐。“A、B 或 C;我建议 B,因为……”比“你想要什么?”好回答。推荐只是建议;人确认之前不算数。
  5. 不把耸肩当成同意。“随便”不是确认。回问一次:“我打算做 X,可以吗?”并写下人同意交给 agent 决定。
  6. 按依赖关系分批问。上游的问题先问,一次问几个。

方法很朴素,要点在第一条:agent 不能用自己的猜测,去填人没有说的东西。看起来理所当然的默认值,正是猜测最容易出错的地方。

需求是一堆文档的时候

这一部分只在需求以业务文档的形式出现时才要紧。

有时候需求是一份业务文件、一张映射表格,加上几封邮件。把这些原样交给 agent,既费上下文,又容易出错:Word 文件带着封面、修订历史和批注;表格里有隐藏的工作表,还有带含义的颜色。二进制文件根本就不是文本。

所以先由程序,而不是模型,把它们转成纯文本。Word 变成 Markdown;每张工作表变成文本文件里的一张表。原件原样保留,一份简短的报告列出程序丢掉了什么,比如隐藏的工作表或图片。这不花 token,而且不该改变任何数字,不过它可能丢掉藏在排版或颜色里的含义(见“代价和坑”)。由人修剪文本,再加一段简短的说明,讲这件事是什么。然后 agent 读这些,写出那一页。

有两条规则让 agent 老实。看起来不对的数字,要引用并提问,绝不擅自更正。两个来源互相矛盾,是要报告的发现,不是自己去裁决的事。这和谁来判断:代码、便宜模型、主模型、人是同样的分工:固定的转换交给程序,阅读交给模型。

需求的审查

这一页写出来之后,在开工之前就可以检查。在我的配置里,agent 把它和系统里已知的东西对照,比如知识库(为 agent 维护的一份代码索引,见知识库:代码的诚实索引;没有的话跳过这一步),把每个问题写进“还不清楚”清单:问题是什么、为什么要紧、来源在哪。它向人问最卡住进度的几个问题,把每个答案写进那一页,一直重复,直到清单为空、人确认为止。

有两件事防着一次糟糕的审查。agent 只在文档互相矛盾、有错、或者和系统对不上的地方才提问。文档说得清楚的东西,它不让人再确认一遍。而且确认那一行留给人:只有人才能填。

需求变了的时候

它会变。规则是先改那一页。agent 先编辑需求,在变更记录里加一行,然后才去动工作。如果人最新的指示和这一页冲突,hook 会提醒 agent 先把两者对齐,再做别的。

计划建立在已确认的需求之上。在我的配置里,需求还没确认,或者确认之后又变了,批准计划就会被拒绝(见两道门:人在哪里审批)。如果开工之后需求变了,人要重新确认,重新批准计划,而已经做完的工作要重新检查,不是扔掉。

测试你自己的配置

给 agent 一段简短的需求,里面有两句互相矛盾的话,比如一句说报告是每天的,一句说是每周的。看它写的那一页,是把这个冲突列在“还不清楚”下面,还是悄悄选了一个。如果它选了一个,这一页就是对着一个猜测说得很笃定。

Costs and traps

  • It costs the person a few minutes of reading. For a one-line change this is too much. A small task can skip the page; see the sizes in Manage tasks, not chats.
  • A confirmation is not a proof. People confirm pages they skimmed. The page can be wrong and confirmed. It makes the misunderstanding visible earlier, nothing more.
  • The agent can write a page that sounds sure. A good page has an honest "not clear yet" list. An empty list on a complex request is a warning sign, not a good sign.
  • Questions can become a chore. Too many, or questions about what could be looked up, and the person starts answering "whatever". I have not measured how many questions is too many.
  • Conversion drops things. Colours, comments and pictures do not survive. The report says what was left out; read it.

代價和陷阱

  • 它花提出需求的人幾分鐘讀。一行的修改,這太多了。小任務可以跳過這一頁;見管任務,不管對話裡的大小。
  • 確認不是證明。人會確認只掃過一眼的頁面。這一頁可能是錯的,卻被確認了。它只是讓誤解更早被看見,僅此而已。
  • agent 可以寫出聽起來很有把握的一頁。好的一頁有一張誠實的「還不清楚」清單。複雜的請求,這張清單卻是空的,是警訊,不是好事。
  • 問題可能變成苦差事。太多,或者問的是查得到的事,人就開始回答「隨便」。多少個問題算太多,我沒有量過。
  • 轉換會丟東西。顏色、註解和圖片都留不下來。報告會說漏掉了什麼;去讀它。

代价和坑

  • 要花提需求的人几分钟来读。对一行的改动,这太多了。小任务可以跳过这一页;见管任务,不管对话里的规模。
  • 确认不是证明。人会确认自己只扫了一眼的页面。这一页可能是错的,却被确认了。它只是让误解更早地显现出来,仅此而已。
  • agent 可以写出一页听起来很笃定的东西。好的一页有一份诚实的“还不清楚”清单。复杂的需求配一份空清单,是警示信号,不是好兆头。
  • 提问可能变成负担。问得太多,或者问的是能查到的东西,人就开始回答“随便”了。多少个问题算太多,我没有测过。
  • 转换会丢东西。颜色、批注和图片留不下来。报告会说丢掉了什么;要读。

When to delete it

  • The asking method. As models ask better questions on their own, shorten the rules for asking. Keep the one page and the confirmation: they are about the person, not the model.
  • The conversion program. If agents read Word and Excel reliably, with the noise left out, the program can go. I have not tested this.

什麼時候可以刪掉

  • 提問的方法。隨著模型自己會問出更好的問題,就把提問的規則縮短。一頁和確認要留著:它們是為了人,不是為了模型。
  • 轉換程式。如果 agent 能可靠地讀 Word 和 Excel,把雜訊去掉,這個程式就可以丟。我沒有測過。

什么时候可以删掉

  • 提问的方法。模型自己越来越会提好问题时,就缩短提问的规则。保留那一页和确认:它们关乎的是人,不是模型。
  • 转换程序。如果 agent 能可靠地读 Word 和 Excel,并且把噪音去掉,这个程序就可以去掉。我没有测过。

Try it on your own setup

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

Look at the most recent merged pull request or the latest few commits in this repository, together with any issue or ticket text they link to. Reconstruct the request as a one-page requirement: the goal, what was in and out of scope, what "done" would have meant, and where each point comes from. Then list what the request left out or left open, and what in the change shows that someone guessed. Do not change any files.

在你自己的環境試試

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

看這個倉庫最近一個合併的 pull request,或最新的幾個 commit,連同它們連結的任何 issue 或工單文字。把請求重建成一頁需求:目標、範圍內和範圍外的是什麼、「做完」會是什麼意思,以及每一點的來源。然後列出這個請求漏掉了什麼、留下什麼沒說,以及修改裡有哪些地方顯示有人在猜。不要改任何檔案。

在你自己的环境里试试

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

看这个仓库里最近一个合并的 pull request,或者最近的几个提交,连同它们链接的 issue 或工单文字。把这个需求还原成一页需求:目标、范围里有什么没有什么、“做完”本来会意味着什么,以及每一点的来源。然后列出这个需求漏掉了什么、留着没定的是什么,以及改动里哪些地方表明有人在猜。不要修改任何文件。

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 requirement file, the asking method, the review of a requirement and the conversion of business files all run in Copilot Harness. After the setup above, type:

/harness-rookie-wondering I have read the chapter "The agent writes the requirement, the person confirms it". Teach me how this harness does it (topic 9, the requirement part, and topic 15 on why the exact words are not kept). Open a real requirement file with me, show how a change goes into it first, and draw how the pieces fit together.

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

在 harness 裡探索

需求檔、提問的方法、需求的審查,和業務檔案的轉換,都在 Copilot Harness 裡運行。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「需求由 agent 寫,人確認」這一章。請教我這個 harness 怎麼做(主題 9 的需求部分,以及主題 15 講為什麼不留原話)。和我一起打開一個真實的需求檔,讓我看一個修改怎麼先進到它裡面,並畫出各部分怎麼接在一起。

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

在 harness 里探索

需求文件、提问的方法、需求的审查,以及业务文件的转换,都在 Copilot Harness 里跑着。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“需求由 agent 写,人确认”这一章。请教我这个 harness 是怎么做的(主题 9 的需求部分,以及主题 15 里为什么不保留原话)。带我打开一份真实的需求文件,演示一次变更是怎么先进入它的,并画出各部分是怎么配合的。

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