大重構拆場次：handoff note 工作法

ChatGPT Web + CatDesk 有一個和 Codex CLI 很不一樣的體感：對話越長越卡。官方觀察是超過 50 次工具呼叫（Tool Call）後變得極度遲鈍，記憶體一度量到 3.9 GB。因此官方建議的工作方式是「一個小功能開一個新對話」。

問題來了：重構橫跨十幾個檔案，新對話又什麼都不知道，怎麼辦？答案是把上下文寫成檔案帶過去，這就是交接筆記（handoff note）工作法。

情境

你要把 order-service 裡所有直接呼叫資料庫的程式碼，重構成經過 repository 層。粗估要動 14 個檔案、上百次工具呼叫。一場對話絕對撐不完，硬撐只會卡到懷疑人生。

目標

把重構切成三個場次，每場一個新對話，用交接筆記串場，全程不卡頓。

第一場：規劃並寫出筆記

給 ChatGPT 的 prompt：

I want to refactor order-service so all DB access goes through a
repository layer. This session is PLANNING ONLY.

1. Search for all direct DB calls (patterns: "db.query", "pool.").
2. Read enough of each hit to understand the shape.
3. Write a handoff note to .ai/handoff-refactor.md containing:
   - goal and non-goals
   - list of files to change, grouped into 3 batches
   - the repository interface you propose
   - exactly where batch 1 should start
Do not edit any source files this session.

CatDesk 工具呼叫序列（第一場）：

1. catdesk_instruction
2. search(pattern: "db.query")
3. search(pattern: "pool.")
4. read(paths: [...])           // batch reads across hits
5. write(path: ".ai/handoff-refactor.md", content: ...)

write 建立了 .ai/handoff-refactor.md。檔案放在工作區內，下一場的 ChatGPT 用 read 就能撿起來。

第二場：新對話接手第一批

先把上一場對話關掉（或開新對話），貼上這段 prompt：

Read .ai/handoff-refactor.md, then implement batch 1 only.
Follow the repository interface defined in the note.
When done, update the note's "progress" section so the next
session knows what remains.

工具呼叫序列變得極短：

1. catdesk_instruction
2. read(paths: [".ai/handoff-refactor.md"])
3. write / edit   // repository interface + first batch of call sites
4. run_command(command: "npm test -- repository")
5. edit(path: ".ai/handoff-refactor.md", ...)   // mark progress

第二場、第三場照同樣模式推進，每場結束前都更新筆記的進度區塊。

為什麼要這麼麻煩

50+ 工具呼叫之後，ChatGPT Web 的每一輪都會帶著整段歷史，延遲明顯上升，3.9 GB 的記憶體占用就是這麼來的。新對話是唯一有效的重置。
ChatGPT 的內容視窗有限（Plus 方案輸入加輸出合計 256K），長對話會把早期的探索結果擠出去；交接筆記是你自己控制的、不會被擠掉的上下文。
筆記是純檔案，可以進版控。重構做到一半中斷，明天任何一個新對話都能無痛接手。

結果與重點

三個場次、三個乾淨的對話，重構完成，每場對話的工具呼叫數都壓在 20 以內，全程沒有卡頓。

三個重點帶走：

新對話是 CatDesk 工作流的基本單位，官方明確建議每個小功能開新對話。
交接筆記讓「新對話什麼都不知道」變成「新對話只讀一個檔案就上手」。
每場結束前更新筆記進度，是整個工作法能不能接得上的關鍵。