---
site: "zyx.tw"
title: "把長任務的狀態寫進檔案，讓新對話有依據接手"
description: "用功能清單定義完成，用進度筆記交接，用 Git 保留退路。"
url: "https://www.zyx.tw/map/harness/state-in-files"
---

# 把長任務的狀態寫進檔案，讓新對話有依據接手

紀錄 055，深讀 L2，869 字，2 分鐘，v2.0.0，更新 2026-11-16

長任務會用完 context window。換新對話後，agent 不記得前一段做了什麼。把完成條件與工作進度寫進檔案，新對話才能從保存的狀態接手。

## 先建立完成條件，再開始逐項實作

這套流程用於跨多段對話開發網頁應用程式。功能清單與進度筆記來自 Anthropic 的做法，需要另外建立；Claude Code 內建的規則檔與自動記憶，保存方式見 CLAUDE.md 與 記憶。

第 1 段對話先由 agent 把目標展開成功能清單，每項標明是否通過。

只有一句目標時，agent 可能一次做太多，或太早宣布完成。

## 開工先讀現況，再確認程式能運作

檔名可以自行安排。以下沿用示意流程：features.json 放功能清單，progress.md 放進度筆記，init.sh 放啟動程式的指令。

Git 是記錄檔案修改的工具，也保存每次提交的紀錄。新對話開始時，agent 先讀 progress.md 與 Git 紀錄，了解前一段完成了哪些工作。

接著，agent 執行 ./init.sh 啟動程式，再做基本運作檢查。把啟動指令保存成腳本，可讓每段對話直接使用既有方法，不必重新摸索。

agent 再從 features.json 選取第 1 個尚未完成的項目。下圖用示意程式呈現完整流程，從讀取筆記與 Git 紀錄，到啟動、檢查、實作，再保存結果。

這套流程的成本是每段對話開頭都要讀檔與測試，換來的是不必猜測前一段做了什麼。

```text
def session():
    notes = read("progress.md")              # what was done
    log = shell("git log --oneline -20")
    shell("./init.sh")                       # start the app
    smoke_test()                             # still working?

    item = first_unfinished("features.json")
    implement(item)
    if end_to_end_test(item):
        mark_passing("features.json", item)
    shell("git commit -am 'done: ' + item.name")
    append("progress.md", summary(item))
```

Figure: Pseudo code of one session of a long task: read the progress notes and the Git log, start the app and run a smoke test, pick the first unfinished item, implement it, mark it passing only after an end-to-end test, commit, and append a summary to the notes.

1. Orient: 先讀筆記與最近的 commit。
2. Check: 啟動程式並跑基本測試。前一段留下的錯誤，先修好。
3. Pick: 從清單挑第 1 個未完成的項目。
4. Verify: 實際操作通過，才把項目標成通過。
5. Record: commit 並更新筆記，留給下一段對話。

## 測試通過才更新狀態，收工留下交接資料

agent 常在沒有完整測試時就標記完成。因此，agent 完成功能後，要從使用者的操作方式測試，再將對應項目標為通過。

網頁功能需要瀏覽器檢查，因為只看程式碼，可能漏掉實際操作才會出現的錯誤；完成證據的要求見 怎樣才算完成。

每段對話結束前，再更新進度筆記，寫明做了什麼與接下來做什麼。

交接因此包含不同用途的資料：功能清單回答哪些項目通過，筆記交代工作現況，Git 保存程式修改。下圖呈現各段對話如何依序讀取、處理單一項目、測試，再寫回共用檔案。

```text
  SESSION 1          SESSION 2          SESSION 3
╭───────────╮      ╭───────────╮      ╭───────────╮
│ read      │      │ read      │      │ read      │
│ one item  │      │ one item  │      │ one item  │
│ test      │      │ test      │      │ test      │
│ write     │      │ write     │      │ write     │
╰─────┬─────╯      ╰─────┬─────╯      ╰─────┬─────╯
      │                  │                  │
╭─────┴──────────────────┴──────────────────┴─────╮
│ FILES  feature list  progress notes  git log    │
╰─────────────────────────────────────────────────╯
```

Figure: Each session reads the files, works on one item, tests it and writes back. A feature list, progress notes and the Git log sit under all sessions and carry the state from one to the next.

1. Read: 每段對話先讀進度與 Git 紀錄，弄清楚目前的狀態。
2. One item: 一次只做清單上的 1 個項目。
3. Test: 做完先測試，通過才標記完成。
4. Write: 結束前 commit，並寫下做了什麼。
5. Files: 狀態留在檔案裡。換了對話，內容還在。

## 保留退回的狀態，也保留清單的修改限制

每完成 1 項，agent 就建立 Git 提交，保存該項修改。程式壞掉時，可以退回上一個能運作的狀態，新對話再從退回後的功能清單開始。

功能清單有修改限制：後續對話只能更新通過狀態，不能刪改項目。這套流程沒有提供清單需要增刪項目時的處理方式。

## 來源

- [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), Justin Young, Anthropic
- [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/), Ryan Lopopolo, OpenAI
- [learn-harness-engineering](https://github.com/walkinglabs/learn-harness-engineering), walkinglabs
- [Context Engineering for AI Agents: Lessons from Building Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus), Yichao Ji
- [How Claude remembers your project](https://code.claude.com/docs/en/memory), Claude Code docs

## 地圖

- 先讀：[每輪重送 context，固定前段與對話長度要分開管理](https://www.zyx.tw/map/harness/context-is-resent.md)
- 先讀：[把糾正存成規則，保存位置依適用範圍決定](https://www.zyx.tw/map/goals/remembers-me.md)
- 回到：[Harness](https://www.zyx.tw/map.md)
