Claude Code｜長任務的上下文整理與交接文件

長任務最容易遺失的，往往不是整段程式碼，而是「為什麼這樣改」「哪些測試真的跑過」「接下來應從哪裡開始」。本篇會把一項待辦篩選需求分成三個階段，建立可供新工作階段接手的 handoff.md、決策紀錄與未完成清單。

先讀工作階段管理、上下文整理及專案閱讀。下載第 65 篇材料，開啟 starter。需要 Node.js 22 以上，CLI 或桌面皆可。閱讀約 20 分鐘，實作約 45 分鐘。

把交接當作可以測試的產出

閱讀完整文字說明

長任務的上下文整理與交接文件，以流程和文件圖形呈現教學重點。

好的交接不是對話流水帳。讀者應能從文件找到目前版本、已完成變更、可靠證據與下一個動作，不必重新詢問所有背景。本篇的驗收方式是另開一個沒有舊對話的工作階段，只提供專案與交接檔，看它是否能正確指出下一步。

練習需求來自 fixtures/issue.json：待辦列表要有全部、未完成、已完成三種篩選，不改動原始資料，不加入登入或雲端同步。先查看 model.js 及測試，再手動執行基準。此時還沒有篩選功能，四個測試通過只代表既有資料操作正常，不代表新功能完成。

node --test tests/model.test.mjs
git status --short

若解壓縮的資料夾還沒有 Git，可先在這個獨立練習目錄初始化並建立基準提交，再記錄 git rev-parse HEAD。若暫時不使用 Git，也可記錄關鍵檔案雜湊與取得材料的日期。不要把別的專案的 HEAD 貼進來，造成看似精確但無法重現的版本資訊。

第一階段只釐清需求和方案

請 Claude 解釋資料流、提出最小實作方案與驗收案例，先不改檔。將事實與假設分開：model.js 使用 completed 布林值是事實；讀者可能希望重新整理保留篩選則是假設，這個需求尚未包含它。遇到後者，先記成排除項目或待確認事項，不要無聲地擴大功能。

閱讀 fixtures/issue.json、model.js 與 tests/model.test.mjs。
只規劃三種篩選，不修改檔案。
列出可從檔案確認的事實、仍需確認的假設，以及最小驗收案例。
不要加入登入、資料庫或部署。
最後列出第二階段需要修改的具體檔案。

確認方案後，把一個重要選擇寫入 decisions.md，例如「篩選產生新陣列，保留完整清單作為來源」。接著補上原因、替代方案及適用範圍。只寫「採用純函式」還不夠；要讓接手者理解為何不應每切換一次就刪除不符合條件的項目。

決策可以改，但改變時需要新證據。如果下一階段發現既有 UI 已有不同資料流，更新紀錄並說明影響，不要同時留兩條互斥的「最終決定」。交接文件應反映當前狀態，討論歷史則用簡短變更紀錄保存。

第二階段先完成可分離的資料邏輯

在獨立的 filter.js 建立函式，再新增對應測試，暫時不接 UI。要求函式接受 items 與 all、active、completed 三種 mode；遇到未知 mode 要明確報錯；回傳結果不得修改輸入陣列。這是一個範圍清楚、適合在交接前完成的工作切片。

可以請 Claude 實作，但仍由你檢查差異與測試輸出。保存實際命令、退出碼、測試數和時間；若測試未執行，明寫未執行。模型在回答中說「應該會通過」不是測試紀錄。第一階段的測試也不能代替本輪改檔後的結果。

此時建立 handoff.md，使用材料中的 config/handoff.md 作起點。範本空白是提醒你填入本機實際資料，不是已完成證明。記錄已完成的是資料函式與測試，未完成的是 UI 按鈕、事件與手機驗證。這樣新階段不會誤以為整個篩選已交付。

# 待辦篩選交接

## 目標與邊界
加入 all、active、completed 篩選；保留完整資料；不加入登入。

## 版本與檔案
基準提交：填入 git rev-parse HEAD 的實際輸出。
已改檔案：逐一列出本機存在的檔案及用途。

## 證據
測試命令、執行時間、退出碼與測試數：填入實際結果。
未執行或受阻的項目：如實列出。

## 下一步
把資料函式接入 UI，再驗證切換篩選後仍可切換待辦狀態。
開始前先核對目前差異與本文版本是否一致。

第三階段以新對話接手

另開新的工作階段，指向同一個專案，先只要求讀 handoff.md 和列出的檔案。不要再貼上前兩輪完整對話；否則無法測試文件是否足夠。請接手者先回報目前完成與未完成內容，再提出下一步，不要立即動手重寫整個功能。

先閱讀 handoff.md，並核對它指向的檔案和 Git 差異。
回答目前完成了什麼、哪些結果有實測證據、還缺什麼。
指出交接內容與現場狀態不一致之處。
確認後才把篩選接入 UI，不重做已存在的資料函式。

若新階段問「測試放在哪裡」，就補交接的測試入口；若重寫已存在的函式，檢查文件是否把它清楚標為完成，或函式本身是否其實未提交。修正後再開另一個新階段測一次。不要用「你剛才應該知道」補救，因為獨立接手正是本篇要驗證的能力。

新階段完成 UI 後，原先交接檔就需要更新。把下一步移到已完成、附新證據，並列出仍未做的手機或無障礙檢查。最後的 handoff.md 應說明目前狀態；不應要求讀者自己從三份互相矛盾的舊摘要拼出結果。

compact、resume 與交接檔各自負責什麼

resume 用來接續既有工作階段；compact 整理當前上下文；交接檔則是你可查閱、審查和版本控管的工作狀態。它們可以配合使用，但不應互相替代。你需要向同事說明目前程式版本時，可靠的檔案與測試紀錄比對話識別碼更容易核對。

故障練習是在寫好交接後，刻意把一個檔案改回舊版，卻不更新文件。新的接手者應發現現場與交接不一致，停止依舊描述繼續修改。這種漂移可能來自另一位同事或另一個 Worktree；解法是重新確認版本，再修正文件，不是強迫程式符合過期摘要。

接手者如何決定第一個動作

接手時先核對目前分支與交接單所寫的提交，接著查看工作目錄中的未提交差異。若兩者不一致，不直接照舊指示繼續；先列出差異，例如上一位尚未提交的測試、後來更新的需求，或已被別人修正的問題。交接單是可核對的時間切片，不能取代現場狀態。

把第一個待辦寫成能立即執行的小步驟，例如「執行指定測試，確認 filter 函式仍缺少 completed 分支」。比起「繼續完成篩選」，這樣更能避免新工作階段重複調查。如果第一步觀察與交接單相反，先更新紀錄，再重新決定接下來的操作。

若交接內容涉及一張尚未取得的畫面，明寫缺少畫面及取得方法，不要求接手者根據文字想像結果。需要帳號才能驗證的地方也保留為待驗，將可在離線環境執行的模型測試先做完。交接品質取決於資訊是否足以繼續工作，不取決於摘要長度。

交接單最後加上更新時間，並註明目前哪些檔案尚未提交。若後續又修改檔案，先更新交接內容再結束階段，避免讀者照著過期狀態接手。

完成判準與小練習

交付 handoff.md、decisions.md、未完成清單，以及至少一次不靠舊對話的接手紀錄。判準包括：能找到正確版本、沒有重做已完成部分、知道哪些證據尚缺、下一步足夠具體。筆記可以簡短，但每句「已完成」都必須對應可檢查的檔案或結果。

小練習是只把交接檔交給另一位讀者，請他在五分鐘內列出下一次應執行的命令與預期結果。若需要口頭補充，就將缺少資訊補回文件。之後可把同一方式用在跨裝置中斷恢復及SDK 狀態接續，但各環境仍要另外確認檔案與工作階段保存在哪裡。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code