Combining Strategic Cutover Docs with Tactical Headless Orchestrators

缺口：戰略協調有了，戰術執行還在手動驅動

上一篇講了一份 CUTOVER.md 怎麼當跨 session、跨 repo 的控制平面 — 用 8 個 pattern 解決「AI agent 有遺忘症、任務卻沒結束」的協調問題。那套機制解的是戰略層：哪些高階決策被做過、哪個方案被否決、誰改完了等誰配合。

但它有個明顯缺口。Cutover doc 追蹤的是「高階任務」這個粒度 — 例如「後端 dual-write regression 要修」是一個 row。可是這個 row 底下，真正的執行還是我一個 session、一個 session 手動驅動：開 session、貼 pickup prompt、看它跑、它卡住我再 nudge、跑完我再回來 push doc。

換句話說，戰略層自動化了（doc 自己會被各 session pickup），但每個高階任務內部的戰術 loop — 寫測試、跑、看結果、修、再跑 — 還是人在當 orchestrator。

Anthropic 自家在 Building effective agents 這篇 engineering 文章裡定義過一個叫 orchestrator-workers（orchestrator–工人 pattern — 一個中央 LLM 動態拆解任務、派發給 worker LLM、再彙總結果）的工作流：原文寫「a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results」。配上 Claude Code 的 subagents（子代理 — 由主 agent spawn 的獨立 agent，每個都有自己 isolated context window）跟 headless mode（非互動模式 — 用 claude -p 把 prompt 餵進去、跑完吐結果，不開互動對話），就能補上 cutover doc 的戰術缺口 — 也就是「單一高階任務底下，怎麼讓 AI 自己跑數小時的 autonomous loop（自主迴圈 — 不需要人在中間 nudge，loop 自己 plan / execute / evaluate 直到條件達成）而不撞牆」。

把這兩件事疊起來，會長出一個乾淨的兩層架構。

戰略層回顧：cutover doc 是 long-term memory

先快速回顧上一篇的核心：cutover doc 是一份放在獨立 metadata repo 的 append-only 文件，扮演跨 session 的 out-of-band control plane（帶外控制平面）。它的關鍵特質是「為遺忘症而設計」：

• Append-only audit trail — 否決過的方案不刪，永遠攤在桌上，避免下個 session 自信地重新提案。
• High-density activity log — 每一列 Note 自我完備（root cause、failing code path、verification、cleanup），下個 session 不必翻 commit 就能還原全部上下文。
• Pickup prompt — 給下個 AI agent 開場讀的 step-by-step prompt，不是給人看的 README。

它的時間尺度是天到月。一份 doc 累積 30 天、十幾個 session 的協調歷史。它記的是「為什麼這樣決定」這類元決策 — 這是 raw git history 永遠翻不出來的東西。

但 cutover doc 從不關心「某個高階任務內部，AI 跑了幾輪 loop 才把測試弄綠」。那是太細的粒度，寫進 append-only doc 只會稀釋訊號。這正是戰術層該接手的地方。

戰術層：orchestrator + claude headless 為什麼不撞牆

問題的核心是：如果讓單一 agent 在同一個 context window 裡跑 planning → execution → evaluation 一輪又一輪，context 會越長、準確度越低 — 也就是所謂的 context wall（上下文牆 — 同一 context window 越長，模型準確度單調下降的現象）。最糟的情境是它在 evaluation 階段幻覺、誤判「任務完成」其實沒完成。

Anthropic subagents 文件 對此給的設計哲學是：subagent「help manage context by using isolated context windows with only relevant information sent back to the orchestrator」— 用 isolated context window（隔離上下文視窗 — 子 agent 跑自己一份乾淨 context，跑完只回傳精簡結論）來防止主 agent 累積雜訊。配合 Agent SDK 的 headless 模式，對應的解法就是把角色拆兩個：

• Orchestrator — 只負責 planning 跟 evaluation，不親自執行。因為它不碰繁重的執行細節，它的 context window 能長期維持在低佔用。這正是 orchestrator-workers pattern 的 orchestrator 角色。
• claude headless — 每一輪 iteration 由 orchestrator 觸發一個全新的 headless session 去執行。每個 headless 都是乾淨的 context window，跑完即丟（這正是 worker / subagent 角色）。

關鍵在最後那一步：headless session 可以自己再 spawn subagent、自己消化大量細節，只把精簡結論回報給 orchestrator。所以繁重的 token 消耗都發生在「跑完即丟」的 headless 裡，orchestrator 的 context 始終乾淨。這就是為什麼這套能撐數小時到數天的 autonomous 執行而不撞牆。Anthropic 在 How we built our multi-agent research system 那篇文章裡也分享了類似結構 — 一個 lead agent 規劃方向，多個 subagent 並行去 retrieve（檢索 — 從不同來源找資料），各跑各的 context、最後彙整。

實作上常見的做法是把它包成 Claude Code 的 skill：一個 super orchestrator 負責調度，每一輪觸發對應的 skill — 例如 super QA（用 BFS（廣度優先搜尋 — 一層一層往外擴的走訪法）走訪所有頁面、寫 Playwright（瀏覽器端對端測試框架）e2e、找 bug）、super build（用 TDD（測試驅動開發 — 先寫測試再寫實作）修 bug）。loop 條件就是「沒有更多 bug 可修、沒有更多 feature 要測」。

而要讓這個 loop 知道「現在做到哪、還有什麼沒做」，他需要 state。

接口：state 怎麼分層

State 可以存在 markdown file 裡，但用 GitHub Projects（GitHub 內建的看板工具 — 跨 repo、跨 issue 的任務看板）當看板更順手：queue、testing、done、bug、flaky（不穩定 — 有時過有時不過的測試）、skip 幾個欄位，靠 Claude Code 內建的 GitHub CLI 直接讀寫。super QA 用 BFS 把待測 feature 一個個推進 queue，測過的進 visited，壞的進 bug 欄。

這裡有個值得注意的對位關係。GitHub Project 在這個架構下扮演的是戰術 state（tactical state — 易變、單一 loop 壽命的工作佇列） — 它的生命週期就跟這一輪 orchestrator loop 一樣長，是一個高速、易變、用完即清的工作佇列。它對應的概念是 CPU 的 L1 cache（L1 快取 — CPU 內最快、最小、最易變的記憶層）或人的 working memory（工作記憶 — 大腦同時操作幾個項目的短期暫存）。

而我的 cutover doc 是戰略 state — append-only、永不刪、跨月保存。它對應的是 main memory / disk，或人的 long-term memory。

兩層之間靠兩個方向的接口連起來：

向下（doc → orchestrator）：cutover doc 的 pickup section 本來就是寫給 AI 開場讀的 step-by-step prompt。現在它不再餵給「我手動開的 session」，而是直接當成 orchestrator 的高階 mandate — orchestrator 讀完戰略 context，知道「這一輪要解 B7 dual-write regression」，然後自己派 headless 去跑。

向上（orchestrator → doc）：當戰術 loop 終止（condition 達成），orchestrator 把整輪的結果壓縮成一列 high-density activity log，append 回 cutover doc。中間跑了 12 輪、開了 30 個 headless session 的雜訊全部丟棄，只留下自我完備的結論：root cause、最終 fix、verification proof、commit hash。

這正好呼應上一篇的設計哲學 — 戰術層產生海量低密度過程，戰略層只收高密度結論。promote 這個動作就是兩層之間的壓縮閥。

一次完整運作長什麼樣

把兩層接起來後，一個高階任務的生命週期大致是這樣：

我這邊的真實情境：cutover doc 上有一條 Open Q「dual-write 沒寫 link 表」。過去我得自己開 session 貼 pickup、盯著跑。接上 orchestrator 之後，這條 Open Q 變成 orchestrator 的條件式任務 — 它派 headless 反覆「寫 regression 測試 → 跑 → 看哪條 link row 沒被寫入 → 修 resolver → 再跑」，直到 5 條測試全綠。整輪跑完，orchestrator 才回來把 Q 標 Closed、附上 commit fc914a8、壓一列 Note 進 activity log。

我從「loop 的驅動者」退位成「loop 的設計者」 — 我定義條件跟 pickup prompt，執行交給戰術層，結果由戰略層歸檔。

把自己升級成 loop 的設計者 — 完整 how-to

「升級成 loop 的設計者」聽起來抽象，具體要做的事其實只有四步：寫 pickup mandate（任務委派 — 給 AI agent 的明確指令格式）、寫 orchestrator script、定義 termination condition（終止條件 — loop 自我判定該停的 boolean 表達式）、定義 promote rule（晉升規則 — 戰術結論怎麼壓縮回戰略 doc）。

Step 1：把 cutover doc 的 Open Q 改寫成 mandate

cutover doc 上的 Open Q 平常是給人讀的，長這樣：

### Q B7: dual-write regression — link table 沒被寫入
- Status: Open
- Owner: backend
- Severity: high
- 觸發條件: listing detail 顯示 0 個 amenity，但 admin 後台有勾

要餵給 orchestrator 之前，要在這條 Q 底下接一段 mandate 區塊：

### Pickup mandate (machine target)

**Task condition (terminate when ALL true):**
- `pytest tests/regression/dual_write_test.py` exit code = 0
- 至少一條測試覆蓋「link table 沒被寫入」這個 root cause
- 既有 116 條 integration 測試全綠（`pytest tests/integration/`）

**Stop condition (terminate when ANY true):**
- Task condition 達成
- iteration 數 ≥ 20
- 連續 3 輪 evaluation 評為「no progress」

**Output contract (orchestrator 收到的 JSON 必須含):**
- `final_commit`：完成的 commit hash
- `root_cause`：一句話 root cause
- `verification`：測試輸出最後三行
- `condition_met`：boolean

關鍵設計：condition 必須機器可驗。「測試全綠」可驗，「修得不錯」不可驗。把模糊的人話翻譯成 boolean 表達式，是 loop 設計者最關鍵的工作。

Step 2：orchestrator script — 最小可運行版本

orchestrator 不必複雜，bash + jq（命令列 JSON 處理工具 — 從 JSON 抽欄位、轉換、過濾）就夠：

#!/usr/bin/env bash
set -euo pipefail

MANDATE_FILE="cutover/B7-dual-write-regression.mandate.md"
STATE_FILE=".orchestrator/queue.json"
LOG_FILE=".orchestrator/log.jsonl"
MAX_ITERATIONS=20
NO_PROGRESS_LIMIT=3

iteration=0
no_progress_count=0

while [ $iteration -lt $MAX_ITERATIONS ]; do
  iteration=$((iteration + 1))
  echo "=== iteration $iteration ==="

  # 1) spawn 全新 headless session（每輪都是乾淨 context window）
  result=$(timeout 600 claude -p \
    --output-format json \
    --allowedTools "Bash,Read,Edit,Write,Grep,Glob" \
    "$(cat "$MANDATE_FILE")

當前 state:
$(cat "$STATE_FILE")

請以 JSON 回覆，包含 condition_met / progress / state_delta / final_commit / root_cause / verification 欄位。")

  echo "$result" | jq -c ". + {iteration: $iteration}" >> "$LOG_FILE"

  # 2) evaluate：condition 達成？
  if echo "$result" | jq -e '.condition_met == true' > /dev/null; then
    echo "✓ condition met at iteration $iteration"
    break
  fi

  # 3) progress check
  if echo "$result" | jq -e '.progress == "none"' > /dev/null; then
    no_progress_count=$((no_progress_count + 1))
    [ $no_progress_count -ge $NO_PROGRESS_LIMIT ] && { echo "✗ no progress, abort"; exit 1; }
  else
    no_progress_count=0
  fi

  # 4) 更新 state（state delta 是這一輪 headless 算出的「下一輪該知道什麼」）
  echo "$result" | jq '.state_delta' > "$STATE_FILE"
done

# 5) promote 回 cutover doc（壓縮成一列 Note）
final_commit=$(echo "$result" | jq -r '.final_commit')
root_cause=$(echo "$result" | jq -r '.root_cause')
verification=$(echo "$result" | jq -r '.verification')

cat >> ../metadata-repo/CUTOVER.md <<EOF

### Note $(date +%Y-%m-%d) — Q B7 closed
- **Root cause:** $root_cause
- **Fix:** commit \`$final_commit\`
- **Verification:** $verification
- **Iterations consumed:** $iteration
EOF

git -C ../metadata-repo add CUTOVER.md
git -C ../metadata-repo commit -m "close: Q B7 dual-write regression"

每一輪 claude -p 都是全新 context window。它讀完 mandate + 當前 state，自己決定要 spawn 什麼 subagent、跑什麼指令，最後回一個結構化 JSON。--output-format json 是 Agent SDK headless docs 列出的官方旗標 — 它讓 stdout 變成可程式化處理的 JSON，包含 total_cost_usd、各 model 用量明細，方便用 jq 抽欄位。

Step 3：把 condition 寫成 boolean 表達式

最常見的失敗是 condition 寫得太鬆或太模糊。三個好 condition 的特徵：

寫不出機器可驗的 condition，就是這個高階任務還不適合下放到自主迴圈 — 留給人手動更安全。

Step 4：promote 規範

orchestrator 跑完不是直接 push code，而是按一個固定模板把整輪結果壓成一列高密度 Note 加進 cutover doc 的 activity log：

### Note 2026-05-22 14:30 — Q B7 closed

**Root cause:** GraphQL resolver 的 nested write 沒呼叫 link table 的 setter — 
listing.amenities 雖然 setter 有跑，但 link table 的 amenityId 對應永遠是空。

**Fix:** commit `fc914a8` — 在 `resolveAmenities` middleware 末尾加 
`await ctx.entityManager.flush()`，強制把 pending writes 沖到 DB。

**Verification:** 5/5 regression 測試通過，既有 116 條 integration 測試全綠。

**Iterations consumed:** 12 orchestrator iterations / 47 sub-headless spawns / 約 800k token

整輪 12 輪 orchestrator iteration、47 個 headless session、800k token 的中間過程全部不寫進 doc。doc 只留下一列自我完備的結論。中間過程留在 .orchestrator/log.jsonl（戰術 log — 跟戰術 state 一樣壽命，跑完即清）。

個案實錄：dual-write regression 全 12 輪

把上一節抽象的 loop 用實際案例展開。起點是 cutover doc 第 17 列：

| 2026-05-15 | B7 | dual-write 沒寫 link 表 | Open | high | backend |

我貼進 pickup mandate 那一刻就退場了。下面是 orchestrator 跑出來的 trace（從 .orchestrator/log.jsonl 摘要）：

iteration 1–2（探索階段）

• iter 1：headless spawn pytest 跑既有 116 條 integration test → 全綠，問題不在 read path
• iter 2：headless 自己寫一個 hypothesis test，模擬建立 listing 並查 link table → 0 row，root cause confirmed

iteration 3–4（定位階段）

• iter 3：headless 用 grep + Read 走訪 resolver code，找到嫌疑犯 resolveAmenities
• iter 4：headless 加 console.log 印 entityManager 內部 state，發現 setter 走的不是 flush path

iteration 5–7（修法 A — 失敗路徑）

• iter 5：headless 改用 bulkInsert 一次寫入，跑測試 → 4/5 過（剩下一條是 race condition — 並發寫入順序不對）
• iter 6：headless 加 mutex（互斥鎖 — 同時只允許一個 thread 進入該段 code），跑 → 1/5 過（鎖太狠 deadlock — 兩條 thread 互相等對方 release 永遠卡死）
• iter 7：orchestrator 對比 iter 5/6 結果，評估「regression vs. progress」 — 標記 A 路徑 progress=none

iteration 8–11（修法 B — 成功路徑）

• iter 8：headless 切回原 path，改在 resolveAmenities middleware 末尾加 await flush()
• iter 9：跑 regression → 5/5 過
• iter 10：headless 自己 spawn 一個 subagent 跑既有 integration 全集 → 116/116 過
• iter 11：headless 再 spawn subagent 跑 chaos test（混沌測試 — 亂序、並發、模擬 partial failure 的 stress test）→ 全通過

iteration 12（收尾）

• headless 用 git commit -m、跑 git log -1 --format=%H 拿到 commit hash fc914a8
• orchestrator 評估「condition met」，break out of loop
• promote phase：寫一列 Note 進 cutover doc，標 Q B7 為 Closed

Context 使用量曲線（用 claude --output-format json 拿到的 total_cost_usd 換算）：

orchestrator 自己的 context 一直維持在 < 20k（健康區），因為每輪結束都只留一行結論。每個 headless 的 60k tokens 跑完即丟，下一輪是乾淨的 0。如果整件事跑在同一個 session 裡，總 context 估計會超過 700k — 早就撞 context wall 而誤判 done。

五個踩過的雷

這套架構講起來很美，但我踩過五個雷，每個都讓我重新設計過 orchestrator script。

雷 1：condition 寫得太模糊 → 無限迴圈

第一版 mandate 我寫的 condition 是「測試看起來大致對」。orchestrator 跑了 50 輪 evaluation 永遠不結束，因為 LLM 對「看起來對」的評估每次都不太一樣 — 有時 confident、有時保守。

修法：強制 condition 必須是 boolean 表達式 — 測試 exit code、檔案 hash、HTTP status code、grep 出來的行數。我現在的 mandate template 第一行就是 必須以 \exit code` / `file hash` / `row count` 等可機器驗證的指標表達`。

雷 2：headless session 沉默卡死

claude -p 偶爾會卡在某個 MCP server（Model Context Protocol server — Claude 連外部工具的協議）或卡在 Bash permission prompt，30 分鐘沒回應。orchestrator 傻等就一直空轉，計費還在累積。

修法：每個 spawn 用 timeout 600 claude -p ... 強制 600 秒上限，超時直接 kill 並計一輪 retry。Step 2 那段 bash script 已經放了這個保險。另外 --allowedTools 明確列出允許的工具白名單，避免它跑到陌生工具被卡住。

雷 3：subagent 之間共享了 working state

某輪 headless A 改了 file X，下一輪 headless B 自以為 X 沒人動，覆蓋 A 的修改。最後 commit 是錯版本。

修法：每個 headless spawn 前先 git stash、跑完再 commit；或更乾脆讓 orchestrator 跑在 git worktree（git 工作樹 — 同一 repo 多個 isolated 工作目錄，每個有獨立的 working files）裡，每個 headless 配一個專屬 worktree。Anthropic 的 Claude Code Advanced Patterns webinar 也提到這種隔離方式。

雷 4：promote 太頻繁 → 戰略 doc 被戰術 log 淹沒

最早我設計 orchestrator「每輪都 append 一筆進 doc」，想要可追蹤性。結果一週下來 doc 多了 300 列 Note，每列幾乎都是「跑了測試」、「retry 了」這種雜訊 — 完全違反高密度原則，下一個 session pickup 時被淹死。

修法：promote 只在整個 mandate 完成或徹底失敗時發生，中間過程一律寫到 .orchestrator/log.jsonl（戰術 log，跟戰術 state 一樣壽命，跑完即清）。promote 是兩層之間的壓縮閥，絕對不能變漏斗。

雷 5：orchestrator 自己撞 context wall（諷刺版）

聽起來很諷刺：orchestrator 不就是為了不撞 context wall 設計的嗎？但 orchestrator 跑 50 輪 iteration、每輪即使只留結論也會堆積 — 我跑過一輪 200 個 iteration 的 dataset migration（資料集遷移 — 把舊版 schema 的全部資料轉到新 schema），orchestrator 自己 context 飆到 80k 也開始幻覺，跳過某些 batch。

修法：orchestrator 每 N 輪（我設 30）自己也spawn 一個 sub-orchestrator，把目前 state 摘要交棒。記憶體階層可以多階 — 跟 CPU 有 L1 / L2 / L3 cache 一樣，AI 工作流也可以有 orchestrator → sub-orchestrator → headless 三層或更多。Anthropic 在 How we built our multi-agent research system 那篇也描述過 lead agent → subagent → tool-use 三層結構。

跟 prd / ralph / autonomous-loop 的對位

讀者可能會問：這套不是已經有現成工具嗎？簡單對位一下：

最大的對位差別在於：本文架構強調「兩層分離」。prd / ralph / autonomous-loop / auto mode 都聚焦在「單一 autonomous run 怎麼跑得久或跑得安全」，但都沒處理「跨月、跨團隊、跨 repo 的失憶問題」。cutover doc 接在它們上面，把它們從「能跑」升級成「跑完還記得跑過什麼、為什麼那樣決定」。

合理的疊法是：

prd 跟 cutover doc 都屬於戰略層，但 prd 是前向產生（從需求生規格），cutover doc 是後向歸檔（從執行結果壓決策日誌）。兩者其實互補 — 一個產 mandate、一個收 result。

為什麼一定要分兩層，不能合成一層

直覺上會想：何不讓 orchestrator 直接讀寫 cutover doc 當它的 state 就好，省掉 GitHub Project？

不行，理由跟「為什麼 L1 cache 不能直接是 disk」一樣：

• 更新頻率天差地遠。戰術 queue 一輪 loop 可能改 50 次（推進、標 testing、標 bug、retry）。如果這些全寫進 append-only 的 doc，doc 會在幾小時內爆量到沒人（也沒 AI）讀得動，徹底違反「高密度、自我完備」的初衷。
• 保存期不同。戰術 state 是用完即丟的；戰略 doc 要跨月保存。把易變資料塞進不可變的日誌，等於拿永久儲存去存暫存資料。
• 讀者不同。戰術 state 的讀者是 orchestrator 自己（機器迴圈）；戰略 doc 的讀者是「下一個從零開始的 session」。混在一起會讓兩種讀者都讀到一堆對自己無用的雜訊。

分兩層，每層各自最佳化自己的更新頻率、保存期、讀者 — 這是記憶體階層幾十年來反覆驗證的同一招。

When NOT to stack both layers

跟上一篇一樣，過早疊兩層 = 過度設計：

• 單輪就能解的任務：如果一個高階任務 headless 跑一兩輪就完成，根本不需要 orchestrator loop，更不需要回填 doc。直接做。
• 沒有可機器判定的終止條件：orchestrator loop 的命脈是「condition 達成沒」。如果任務無法寫成「測試全綠 / queue 清空」這種機器可驗的條件，戰術層就退化成無限迴圈，不如人來判斷。
• 任務不跨 session：如果整件事一個下午、單一 session 就收工，戰略層那套 cutover doc 純屬空轉 — 上一篇已經講過這點。

合理的採用順序是：先有跨 session 的痛、長出 cutover doc（戰略層）；之後發現某些高階任務內部的 loop 重複到值得自動化，再往下接 orchestrator（戰術層）。兩層都該是被痛點逼出來的，不是預先設計的。

Closing：把記憶體階層搬到 AI 工作流

回頭看，這整件事就是把電腦科學最古老的一個概念 — 記憶體階層 — 搬到 AI 工作流上：

• 戰略層（cutover doc）= 慢、大、持久的 long-term memory，存的是跨月的決策日誌。
• 戰術層（orchestrator + headless）= 快、小、易變的 working memory，跑的是單一任務內的自動化 loop。
• 兩層之間靠 promote（戰術結論壓縮上傳）跟 pickup prompt（戰略任務派發下放）雙向接口連起來。

Anthropic 的 orchestrator-workers pattern 自己解的是「單一 autonomous run 不要撞 context wall」；我的 cutover doc 解的是「跨 session 不要失憶」。它們各自只覆蓋一個時間尺度。疊起來，才第一次有了「從數小時到數月、全程不掉上下文」的完整覆蓋。

下次你發現某個 cutover doc 上的高階任務，自己一個 session 一個 session 手動驅動到厭世 — 別再當那個 loop 的驅動者。在那條 Open Q 底下接一個 orchestrator，把自己升級成 loop 的設計者就好。