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

5.8

Long work across sessions跨會話的長任務跨会话的长任务

This chapter assumes you know the task folder from Manage tasks, not chats, and that a chat gets shortened or ends (Long chats get worse).

讀這一章,你需要知道 管任務,不管對話 裡的任務資料夾,也要知道對話會被縮短或結束(長對話會變差)。

读这一章,你需要知道管任务,不管对话里的任务文件夹,也需要知道一段对话会被压短或者结束(见长对话会变差)。

The Knowledge經驗分享经验分享

In one sentence

Long work survives across sessions only if its memory is in files: the requirement, the plan, the to-do list, the handover file. Split big work into tasks small enough to accept one by one.

一句話

長時間的工作要能跨會話撐下去,它的記憶就必須放在檔案裡:需求、計畫、待辦清單、交接檔。把大工作拆成小到能一個一個驗收的任務。

一句话

长任务要跨会话延续,记忆就得放在文件里:需求、计划、待办清单、交接文件。把大任务拆成一个个小任务,小到可以逐个验收。

For leaders

  • The decision: for work that spans days, decide that its memory lives in files, and that big work is split into tasks small enough to accept one by one.
  • The risk: a new session knows nothing unless a file tells it. A big job handed over in one go gets started all at once and left half done, and a later session can see progress and call the job done too early. In my setup a person's "passed" on a step is only text, with nothing in code behind it. That is the weakest link.
  • The cost of doing it right: files cost effort: every step writes a little and a new session reads a little. For a job that fits in one session it is waste. I have not measured what a goal saves over starting a new chat.
  • Ask the team: "For our longest-running job, which file tells a new session what step it is on, and who accepted the steps so far?"

給主管

  • 要做的決定:對跨好幾天的工作,決定它的記憶放在檔案裡,並把大工作拆成小到能一個一個驗收的任務。
  • 風險:新的會話什麼都不知道,除非有檔案告訴它。一次交出去的大工作,會被一次全部開工、做到一半就丟著,之後的會話也可能看到有進展,就太早說工作做完了。在我的設定裡,人對一步說的「通過」只是文字,程式裡沒有任何東西撐著。這是最弱的一環。
  • 做對的成本:檔案要花力氣:每一步寫一點,新的會話讀一點。對一個一次會話就做得完的工作,這是浪費。一個目標比起開新對話省多少,我沒有量過。
  • 可以問團隊:「對我們跑得最久的那項工作,哪個檔案告訴新的會話它在哪一步?到目前為止的步驟,是誰驗收的?」

写给管理者

  • 要拍板的事:对要跨好几天的工作,定下它的记忆放在文件里,并且大任务要拆成能逐个验收的小任务。
  • 风险:新会话什么都不知道,除非有文件告诉它。一个大任务一股脑交出去,会被一下子全开工,然后半途而废;后来的会话看到有进展,可能过早宣布任务完成。在我的配置里,人对某一步说的“通过”只是一段文字,代码里没有任何东西支撑它。这是最薄弱的一环。
  • 做对的代价:文件要花功夫:每一步写一点,新会话读一点。对一个会话就能做完的任务,这是浪费。一个 goal 比重新开个对话能省多少,我没有测过。
  • 可以问团队:“我们跑得最久的那个任务,哪个文件告诉新会话现在做到哪一步了?到目前为止的各步,是谁验收的?”

The problem

A job that takes three days will not fit in one chat. The first session ends. Or the tool shortens it to make room, and the details go. A new session knows nothing, unless something tells it.

What can tell it? Not the agent's memory: it has none between sessions. Not your memory either, if you have to explain the background again every morning, and explain it slightly differently each time. The only thing that is the same every morning is a file.

There is a second problem, and it comes from the size of the job. Handed a big job in one go, an agent tends to start everything at once, run out of room halfway, and leave things half done. Anthropic saw the same on a long coding project: "the agent tended to try to do too much at once" (Effective harnesses for long-running agents). The same article describes the opposite failure, a later instance that would "declare the job done" too early; that one is the subject of Unattended: when it must stop.

問題

要花三天的工作,一次對話裝不下。第一個會話結束了。或者工具為了騰出空間把它縮短,細節就沒了。新的會話什麼都不知道,除非有東西告訴它。

什麼能告訴它?不是 agent 的記憶:它在會話之間沒有記憶。也不是你的記憶,如果你每天早上都得重新解釋一次背景,而且每次說得都有點不一樣。每天早上唯一一樣的東西,是一個檔案。

還有第二個問題,來自工作的大小。一次拿到大工作的 agent,傾向於一次全部開工,做到一半空間用完,留下一堆做到一半的東西。Anthropic 在一個長時間的寫程式專案上看到同樣的事:「agent 傾向一次做太多」(Effective harnesses for long-running agents)。同一篇文章也描述了相反的失敗:後來的實例太早「宣布工作完成」;那個是 無人值守:什麼時候必須停 的主題。

问题

一个要三天的任务,一次对话装不下。第一个会话结束了。或者工具为了腾地方把它压短,细节就丢了。新会话什么都不知道,除非有东西告诉它。

什么能告诉它?不是 agent 的记忆:它在会话之间没有记忆。也不是你的记忆:如果每天早上都得把背景再讲一遍,每次讲得还不太一样。每天早上唯一一模一样的东西,是文件。

还有第二个问题,来自任务的大小。一个大任务一股脑交给 agent,它往往想一下子全开工,做到一半空间用完,留下一堆做了一半的东西。Anthropic 在一个长期的编程项目上也看到了同样的情况:“agent 倾向于一次想做太多”(Effective harnesses for long-running agents)。同一篇文章还描述了相反的失败,也就是后来的实例过早“宣布任务完成”;那个问题是无人值守:什么时候必须停的主题。

How it works

What a conversation loses

A conversation holds four things that a later session needs: what was asked, what was decided and why, how far the work has got, and what comes next. When the conversation is shortened or ended, all four are at risk, and the agent does not know which ones it lost.

What goes in the folder

Put those four things where they cannot be shortened.

the task folder requirement plan to-do list progress session 1 Monday writes its chat is gone session 2 Thursday reads
  1. The memory of the work lives in one folder: the requirement, the plan, the to-do list and the progress.
  2. The first session works, and writes what it did and what comes next into the folder.
  3. The session ends, or its chat is shortened. What it held in its head is gone.
  4. A new session, days later, starts by reading the folder and carries on.
Sessions come and go. The folder stays, and it is the only memory the work has.
  • The requirement: what was asked, in a form a person confirmed (The requirement on one page).
  • The plan: how the work will be done, and what is out of scope.
  • The to-do list: steps, each small, each with a status and a way to tell it is done.
  • The handover: one short handover file (the one from Manage tasks, not chats, which also explains why the disk wins; Anthropic calls its version a progress file) that says which step it is at and what comes next. It has to stay short, within one screen, or a new session spends its room reading it.

A fifth item helps: a change log, one entry per step finished, saying what changed. When someone asks "why is it like this?", the answer is there.

What a new session reads

A new session reads the short handover file first, then the to-do list, and only then what the current step needs. It does not read the whole folder. Then it checks the file against the disk: does the file really exist, did the step really happen? When the record and the disk disagree, the disk wins. A handover file that says "step 4 done" does not make step 4 done.

Anthropic's team did three things I do not do the same way. They had the agent commit to git after each step, so every step left a clean state to return to. They had each new session first run a basic end-to-end test before starting new work, which is a check of the old state, not only a read of the file. And they kept the feature list in JSON, because the model was less likely to change a JSON file by mistake than a Markdown one. My files are Markdown, and I have not compared the two.

Build the frame first, then step by step

Do not start with the work. Start with the frame:

  1. Settle the central idea: goal, what is in scope, what is not, how the whole will be accepted.
  2. Break it into small steps.
  3. Have a person read both and confirm.
  4. Then do one step: do it, check it, hand it to the person.
  5. A step is done only when the person says it passed. Then write the log entry, update the handover file, and move to the next.

The person's "passed" is a gate (Two gates). In my setup that is text, not code: nothing in code stops an agent from writing "passed" for itself. I rely on the agent following the instruction, and on the person reading. This is a gap I know about.

What is too big, and how to split it

Most jobs are one task, and a goal is for the rest. A job is too big for one task when one of these is true (these three are my rules of thumb, not tested):

  • It cannot finish in one session, and nobody can say how far along it is.
  • You cannot say how you would accept the whole of it at once.
  • The plan keeps changing as you learn more.

The fix is a goal: the big thing as one set of files, with a few tasks under it. A task is one delivery, as in Manage tasks, not chats: one folder, its own checks, its own acceptance. The goal holds the idea and the list; each task does one piece.

one goal idea, list of steps, progress pointer task 1 accepted task 2 in progress task 3 task 4 Each task is small enough to check and accept on its own.
A big job is one goal with a few tasks under it. One task at a time is done, checked and accepted.

A good task is small enough that you can say, in a sentence, how you will accept it. The goal does not need to know the details of task 3 while you work on task 2. That is the point: the plan is allowed to change, one task at a time, without redoing what has been accepted. Steps already accepted are not rewritten; a redo is a new step.

Common traps

  • All at once. The agent tries to finish the goal in one session. The fix is the list: only one step is active.
  • Done said too early. A new session sees progress and decides it is finished. The fix is the same as for unattended work (when to stop): done is a state the files and the person confirm, not a thing the agent says.
  • A long handover file. If the pointer grows past a screen, it stops being read. Move detail to the log.
  • Making a goal for a small job. Most jobs need one task. A goal is for work that spans sessions and changes shape.

原理

對話會丟掉什麼

一段對話裝著後來的會話需要的四樣東西:被要求做什麼、決定了什麼和為什麼、工作做到哪裡、接下來是什麼。對話被縮短或結束時,這四樣都有風險,而 agent 不知道自己丟了哪些。

資料夾裡放什麼

把這四樣東西放在不會被縮短的地方。

任務資料夾 需求 計畫 待辦清單 進度 第 1 個會話 週一 寫入 對話已消失 第 2 個會話 週四 讀取
  1. 這件事的記憶放在一個資料夾裡:需求、計畫、待辦清單和進度。
  2. 第一個會話做事,把做了什麼、下一步是什麼寫進資料夾。
  3. 會話結束,或對話被縮短。它腦子裡記的東西沒有了。
  4. 幾天後的新會話,先讀資料夾,再接著做。
會話來了又走,資料夾留下來,它是這件事唯一的記憶。
  • 需求:被要求做什麼,以人確認過的形式(需求由 agent 寫,人確認)。
  • 計畫:工作要怎麼做,以及什麼不在範圍內。
  • 待辦清單:一步一步,每步都小,每步都有狀態,也有辦法判斷它做完了沒。
  • 交接:一份簡短的交接檔(就是 管任務,不管對話 裡的那個,那裡也解釋了為什麼以磁碟為準;Anthropic 把它的版本叫做 progress file),說明目前在哪一步、接下來是什麼。它必須保持簡短,一個畫面以內,不然新的會話會把空間花在讀它上面。

第五樣東西也有幫助:變更紀錄,每完成一步寫一條,說明改了什麼。有人問「為什麼是這樣?」,答案就在那裡。

新的會話讀什麼

新的會話先讀簡短的交接檔,再讀待辦清單,然後才讀目前這一步需要的東西。它不讀整個資料夾。接著它拿檔案對照磁碟:檔案真的存在嗎?這一步真的發生過嗎?紀錄和磁碟不一致時,以磁碟為準。寫著「第 4 步完成」的交接檔,不會讓第 4 步完成。

Anthropic 的團隊做了三件事,我的做法不一樣。他們讓 agent 每做完一步就 commit 到 git,所以每一步都留下一個乾淨、可以回去的狀態。他們讓每個新的會話,在開始新工作之前先跑一個基本的端到端測試,這是對舊狀態的檢查,不只是讀檔案。而且他們把功能清單放在 JSON 裡,因為模型誤改 JSON 檔案的機會,比誤改 Markdown 小。我的檔案是 Markdown,兩者我沒有比較過。

先搭框架,再一步一步來

不要從工作開始。從框架開始:

  1. 定下核心想法:目標、範圍內有什麼、沒有什麼、整體怎麼驗收。
  2. 拆成小步驟。
  3. 讓人讀這兩樣並確認。
  4. 然後做一步:做、檢查、交給人。
  5. 一步要等人說通過才算做完。然後寫變更紀錄、更新交接檔,再進入下一步。

人的「通過」是一道門(兩道門:人在哪裡批准)。在我的設定裡,那是文字,不是程式:程式裡沒有任何東西阻止 agent 替自己寫下「通過」。我靠的是 agent 遵守指令,以及人去讀。這是我知道的一個缺口。

什麼算太大,怎麼拆

大多數工作是一個任務,目標是留給其餘的。一個工作在以下任一種情況為真時,對一個任務來說就太大了(這三條是我的經驗法則,沒有測過):

  • 一次會話做不完,而且沒人說得出做到多少了。
  • 你說不出要怎麼一次驗收整件事。
  • 隨著你學到更多,計畫一直在變。

解法是一個目標:把大事情做成一組檔案,底下有幾個任務。一個任務是一次交付,就像 管任務,不管對話 裡那樣:一個資料夾、自己的檢查、自己的驗收。目標放想法和清單;每個任務做一塊。

一個目標 核心想法、步驟清單、進度指標 任務 1 已驗收 任務 2 進行中 任務 3 任務 4 每個任務都小到可以單獨檢查、單獨驗收。
大事是一個目標,底下幾個任務。一次做完、檢查、驗收一個任務。

好的任務小到你能用一句話說出怎麼驗收它。你在做任務 2 的時候,目標不需要知道任務 3 的細節。重點就在這裡:計畫可以一次改一個任務,不必重做已驗收的東西。已經驗收的步驟不會被改寫;重做是新的一步。

常見的陷阱

  • 一次全部開工。agent 想在一次會話裡完成整個目標。解法是清單:同一時間只有一步在進行。
  • 太早說做完了。新的會話看到進展,就判定做完了。解法和無人值守的工作一樣(什麼時候停):做完是檔案和人確認的一個狀態,不是 agent 說的一句話。
  • 交接檔太長。如果指標長過一個畫面,就沒人讀了。把細節移到變更紀錄。
  • 為小工作建立目標。大多數工作只需要一個任務。目標是留給跨會話、而且會改變形狀的工作。

原理

一段对话会丢掉什么

一段对话里装着后来的会话需要的四样东西:要求是什么,定了什么、为什么这么定,工作做到哪了,接下来是什么。对话被压短或者结束时,这四样都有风险,而且 agent 不知道自己丢了哪几样。

文件夹里放什么

把这四样放到压不短的地方。

任务文件夹 需求 计划 待办清单 进度 第 1 个会话 周一 写入 对话已消失 第 2 个会话 周四 读取
  1. 这件事的记忆放在一个文件夹里:需求、计划、待办清单和进度。
  2. 第一个会话干活,把做了什么、下一步是什么写进文件夹。
  3. 会话结束,或者对话被缩短。它脑子里记的东西就没了。
  4. 几天后的新会话,先读文件夹,再接着干。
会话来了又走,文件夹留下来,它是这件事唯一的记忆。
  • 需求:要求是什么,写成人确认过的样子(见需求由 agent 写,人确认)。
  • 计划:工作打算怎么做,什么不在范围内。
  • 待办清单:一步步的事项,每一步都小,每一步都有状态,也有判断它做完了没有的办法。
  • 交接:一份简短的交接文件(就是管任务,不管对话里的那份,那里也讲了为什么以磁盘为准;Anthropic 把自己的版本叫 progress file),写明现在做到哪一步、接下来是什么。它得保持简短,不超过一屏,否则新会话的空间都花在读它上面。

还有第五样会有帮助:变更日志,每完成一步记一条,写清楚改了什么。有人问“为什么是这样”时,答案就在那里。

新会话读什么

新会话先读简短的交接文件,再读待办清单,最后才读当前这一步需要的东西。它不读整个文件夹。然后它拿文件对照磁盘:文件真的存在吗,这一步真的发生了吗?记录和磁盘对不上时,以磁盘为准。交接文件写着“第 4 步做完了”,并不会让第 4 步做完。

Anthropic 的团队做了三件事,我的做法与之不同。他们让 agent 每做完一步就提交到 git,这样每一步都留下一个干净的状态可以退回。他们让每个新会话在开始新工作之前,先跑一遍基本的端到端测试,这是对旧状态的检查,而不只是读文件。他们还把功能清单放在 JSON 里,因为模型误改 JSON 文件的可能性比改 Markdown 文件小。我的文件是 Markdown,两者我没有比较过。

先搭框架,再一步一步来

别一上来就干活。先搭框架:

  1. 定下核心想法:目标是什么,范围里有什么、没有什么,整体怎么验收。
  2. 拆成小步骤。
  3. 让人把两样都读一遍并确认。
  4. 然后做一步:做完,检查,交给人。
  5. 人说“通过”,这一步才算完成。然后写日志,更新交接文件,进入下一步。

人说的“通过”是一道关卡(见两道门:人在哪里审批)。在我的配置里,它是文字,不是代码:代码里没有任何东西能阻止 agent 自己给自己写“通过”。我靠的是 agent 照着指令办,以及人去读。这是我知道的一个缺口。

多大算太大,怎么拆

大多数任务就是一个任务,goal 是留给其余的。一件事不适合只当作一个任务,是指下面任何一条成立(这三条是我的经验法则,没有测过):

  • 一个会话做不完,而且没人说得清它做到了哪里。
  • 你说不出怎么一次性验收它的整体。
  • 随着你了解得越来越多,计划总在变。

办法是用一个 goal:把这件大事放进一套文件里,下面挂几个任务。一个任务就是一次交付,和管任务,不管对话里一样:一个文件夹,有自己的检查,有自己的验收。goal 放想法和清单,每个任务做其中一块。

一个目标 核心想法、步骤清单、进度指针 任务 1 已验收 任务 2 进行中 任务 3 任务 4 每个任务都小到可以单独检查、单独验收。
大活是一个目标,底下几个任务。一次做完、检查、验收一个任务。

一个好的任务,小到你能用一句话说出怎么验收它。你在做任务 2 的时候,goal 不需要知道任务 3 的细节。这正是意义所在:计划可以一个任务一个任务地改,不用把已经验收的重做一遍。已经验收的步骤不改写;要重做,就是新的一步。

常见的坑

  • 一下子全开工。agent 想在一个会话里完成整个 goal。办法是用清单:同一时间只有一步是活动的。
  • 过早说做完了。新会话看到有进展,就认定已经完成了。办法和无人值守的活一样(见无人值守:什么时候必须停):做完是由文件和人确认的一种状态,不是 agent 嘴里说的一件事。
  • 交接文件太长。指针一旦超过一屏,就没人读了。把细节移到日志里。
  • 小任务也建 goal。大多数任务只要一个任务。goal 是留给跨会话、而且形状会变的工作。

Costs and traps

Files cost effort. Every step writes a little, and a new session reads a little. For a job that fits in one session, it is waste.

A person's "passed" is only text. Two gates binds an approval to the exact plan, and code checks it. The "passed" of a step here is not bound to anything; nothing in code stops an agent from writing it. It is the weakest link in this chapter.

Files can lie. The agent writes them, so they can be wrong or stale. That is why the disk wins, and why the person accepts step by step.

Who starts it matters. In my setup only the person starts a goal. An agent may suggest it when a job looks long, but cannot begin one. Otherwise every job would become a project.

What I have not measured. How much a goal saves over just starting a new chat and explaining. I think it saves the most when the job changes shape, but I have no numbers.

代價和陷阱

檔案要花力氣。每一步寫一點,新的會話讀一點。對一個一次會話就做得完的工作,這是浪費。

人的「通過」只是文字。兩道門:人在哪裡批准 把批准綁到確切的計畫,由程式檢查。這裡一步的「通過」沒有綁定到任何東西;程式裡沒有任何東西阻止 agent 寫下它。這是這一章最弱的一環。

檔案會說謊。檔案是 agent 寫的,所以可能是錯的或過期的。這就是為什麼以磁碟為準,也是為什麼人要一步一步驗收。

誰來開始很重要。在我的設定裡,只有人能開始一個目標。agent 看到工作很長時可以建議,但不能自己開始。不然每個工作都會變成專案。

我沒量過的。一個目標比起直接開新對話再重新解釋,省了多少。我認為當工作改變形狀時,省得最多,但我沒有數字。

代价和坑

文件要花功夫。每一步写一点,新会话读一点。对一个会话就能做完的任务,这是浪费。

人的“通过”只是文字。两道门:人在哪里审批把一次审批绑定到确切的那份计划上,由代码来检查。这里一步的“通过”没有绑定任何东西;代码里没有什么能阻止 agent 写下它。这是本章最薄弱的一环。

文件可能说谎。文件是 agent 写的,所以可能写错,也可能过期。这就是为什么以磁盘为准,也是为什么人要一步一步验收。

谁来启动很重要。在我的配置里,只有人才能启动一个 goal。任务看起来很长时,agent 可以建议,但不能自己开一个。否则每个任务都会变成一个项目。

我没有测过的。一个 goal 比起直接开个新对话再解释一遍,能省多少。我认为在任务形状会变的时候省得最多,但我没有数字。

When to delete it

If the platform keeps a trustworthy memory of a long job across sessions, so that a new session can resume without reading files, the handover file can go. I would keep the requirement and the plan as files anyway: a person can read them too, and that is how you accept the work.

什麼時候可以刪掉

如果平台能跨會話,為長工作保有可信的記憶,讓新的會話不必讀檔案就能接著做,交接檔就可以拿掉。需求和計畫我還是會留成檔案:人也讀得了它們,而驗收工作靠的就是這個。

什么时候可以删掉

如果平台能在跨会话时对长任务保有可靠的记忆,新会话不读文件就能接着干,交接文件就可以去掉。需求和计划我还是会留成文件:人也能读,验收工作靠的就是这个。

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 task folder and the goal files run in Copilot Harness. The harness can teach them to you from the inside, with the real files. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Long work across sessions". Teach me how this harness keeps long work in files (topic 9): the task folder, the handover file a new session reads, and the goal that groups several tasks. Open real files with me 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 可以從裡面教你這些,附上真實的檔案。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「跨會話的長任務」這一章。請教我這個 harness 怎麼把長工作放在檔案裡(主題 9):任務資料夾、新的會話讀的交接檔,以及把幾個任務組在一起的目標。帶我打開真實的檔案,並畫出這些部分怎麼組合在一起。

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

在 harness 里探索

任务文件夹和 goal 文件都在 Copilot Harness 里跑着。harness 可以从内部教你,配上真实的文件。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“跨会话的长任务”这一章。请教我这个 harness 是怎么把长任务放在文件里的(主题 9):任务文件夹、新会话要读的交接文件,以及把几个任务归在一起的 goal。和我一起打开真实的文件,并画出各部分是怎么拼在一起的。

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