讓 agent 管自己的進度

結構化的 self-planning

Claude Code 工作時常常要做好幾步：grep 找引用 → 讀幾個檔案 → 改程式碼 → 跑測試。如果你讓模型「憑感覺推進」，你會看到它頭幾步做得不錯，中間就開始遺忘，最後半途而廢。

s03 的解法是給它一個清單工具：模型自己調 todo 工具往裡塞任務項，TodoManager 驗證結構、持久化、傳回目前視圖。這樣有兩個好處：

• 模型被迫把「要做什麼」顯式化出來－光寫出來就已經幫它理清了思路。
• 人類能看到它在想什麼。調試體驗好十倍。

# TODO 视图，每一项都是结构化的
[ ] #1: grep "TODO" across src/
[>] #2: read src/app.py and list comments     # 正在做
[ ] #3: generate summary markdown
[ ] #4: write to TODO_LIST.md

(0/4 completed)

一條硬規則：同一時刻只有一個 in_progress

TodoManager.update() 裡有一個校驗：

if in_progress_count > 1:
    raise ValueError("Only one task can be in_progress at a time")

看似苛刻，其實是在幫模型。如果允許同時有 3 個「在做」，它就會四處開戰、哪個都沒做完。強制單任務推進，它被迫每完成一個才開下一個。

下面這個 widget 讓你扮演模型，提交各種 todo payload，看哪些通過驗證、哪些被拒絕。

Nag reminder：連續 3 輪沒更新？戳一下

即使給了 todo 工具，模型還是會偶爾「忘記」更新清單——做了一堆事，但 in_progress 還卡在第 2 條。 s03 的招式是一個非常簡單的計數器：

rounds_since_todo = 0
while True:
    response = LLM(messages, tools)
    ...
    used_todo = any(b.name == "todo" for b in tool_uses)
    rounds_since_todo = 0 if used_todo else rounds_since_todo + 1
    if rounds_since_todo >= 3:
        results.append({"type":"text", "text":"<reminder>Update your todos.</reminder>"})

計數到 3，在下一輪的 user message 裡夾一條 reminder。模型看到會本能地去調 todo。這是用工程手段把軟性約束（「請保持更新」）變成強制刺激。

這種套路的名字叫什麼？

在 agent 設計圈裡，這叫 structured self-planning with soft nudges－給模型一個它必須寫入的結構化狀態，輔以時機的 reminder。 Claude Code 真實程式碼裡用了類似模式，但更克制（頻率低、措詞中性）。

為什麼不直接把「每步都更新 todo」寫進 system prompt？ 寫是可以寫，但模型對 system prompt 裡的通用指令服從度會隨對話變長而衰減。把指令拆成「不斷重註入的 reminder」效果穩定得多。