如何管理大型任務：上下文與可驗證的階段

大型任務往往從一句聽起來很合理的要求開始："建立一份地區設定參照表：列出項目、提供搜尋、依國家篩選，還要有像樣的版面。"一小時後，您面前的頁面可能只完成一半，搜尋漏掉某些欄位，版面已經改了兩次，而對話長到讓人分不清哪些是驗證過的成果，哪些只是說過會做到。

可能的原因之一，是沒有把任務拆成各有明確成果的部分。這不代表程式碼不會出錯，但知道目前應該有哪些功能，檢查起來就容易得多。接下來會說明如何把大型工作拆成可驗證的階段、在目前階段提供哪些資訊給代理，以及該記下什麼，才能明天回來繼續，不論沿用同一段對話或另開新對話，都不必憑記憶重建整個脈絡。

最後的參照表應該長這樣：有搜尋功能的清單，每筆資料包含地區代碼、語言、國家、貨幣與網域。記住這個版面，實作時可以把它當作風格範例，不只是張圖片。

大型任務與漫長對話

大型任務可能還沒遇到程式碼錯誤就卡住，因為整個流程逐漸失去方向。上下文越來越長，假設和已經做好的決定混在一起，原本只要加搜尋，卻不知不覺又改起版面。上下文視窗確實有限，但更麻煩的是，您會搞不清楚現在在做什麼、哪些部分已經完成。

TASK_SPEC 記錄整個任務的目標、範圍與驗證方式。接著依照這份規格，把工作拆成可驗證的階段，也就是 milestones。每個階段都有自己的成果與範圍，例如新增搜尋，但保留資料和版面。這能讓 Claude 專注在任務上，也讓您看清楚目前進度。

如果任務還不明確，第一個階段可以先做探索：讀取兩三個關鍵檔案、列出可能的解法與風險，再釐清任務描述和後續階段。

每個階段結束時都要執行檢查，並寫下簡短摘要（summary）：完成了什麼、如何驗證、接下來要做什麼。如果專案使用 Git，就把驗證過的修改存成小型 commit。摘要保存決策，commit 保存程式碼版本；兩者搭配，方便檢查成果，也能在暫停後接續工作。

什麼才算一個階段

Milestone（里程碑）是任務中有一項可驗證中間成果的節點。從開始到這個節點的工作，就稱為一個階段。

每個階段都必須包含三個部分：

• 成果 - 具體會有哪些功能開始運作；
• 範圍 - 這次不會修改哪些內容；
• 驗證 - 您要檢查什麼來確認成果。

比較一下兩種寫法就很清楚。"處理一下搜尋"沒有完成的判準，因為可以一直做下去，任何人都能自行決定何時算"完成"。"搜尋能依地區代碼找到資料，空白查詢則顯示完整清單"就有明確的檢查點，半分鐘內便能在瀏覽器中確認。

階段沒有通用的時間或檔案數量限制，但大小還是重要。如果一個階段混進好幾項彼此獨立的修改，讓您無法一次清楚地驗證成果，就該把它拆小。判斷的參考是：最近一個能單獨取得、也能單獨驗證的實用成果。

把成果拆成可運作的部分

以一份教學用地區設定參照表為例。每筆資料的欄位和上面的版面相同：地區代碼、語言、國家、貨幣與網域。為了簡化範例，完整陣列直接放在 app.js，並由 index.html 載入。頁面不會另外發出請求載入資料，因此不用伺服器也能在瀏覽器中開啟。資料如下：

[
  { "code": "en-US", "language": "English", "country": "United States", "currency": "USD", "tld": ".us" },
  { "code": "de-DE", "language": "German", "country": "Germany", "currency": "EUR", "tld": ".de" },
  { "code": "fr-CA", "language": "French", "country": "Canada", "currency": "CAD", "tld": ".ca" },
  { "code": "ja-JP", "language": "Japanese", "country": "Japan", "currency": "JPY", "tld": ".jp" }
]

完整需求是：顯示清單、搜尋，以及依國家篩選。開頭提到的"像樣的版面"不另外拆成一個階段：M1 顯示清單時就要有基本版面，只有新的視覺設計，也就是切換主題，才列入"延後處理"。我們把需求拆成三個階段。

先讓清單正常運作，之後才方便檢查資料篩選。搜尋和篩選可以用不同順序新增；這裡先做搜尋，並在 M3 確認兩者能搭配使用。階段之間的箭頭表示前一階段已經驗證完成，綠色的 M3 則代表所有需求都已實現。

這裡是依成果拆分工作。每個階段都包含讀取程式碼、修改和驗證。如果計畫是"先完成所有 HTML，再寫所有 JS，最後一起檢查"，就得等到最後才能確認功能是否正常。寫好的 HTML 標記確實可以是有用的中間成果，但光看標記還無法得知搜尋能不能用。

請留意，代理通常會自然採用依層次拆分的方式：先完成全部標記，再處理整個邏輯。不少長期使用 AI 代理的人也提過這種傾向，例如 Matt Pocock 在分享自己流程的工作坊中就談到，即使明確要求依成果拆分，代理仍可能提出這類計畫。因此，檢查代理提出的每個階段時，只要問一件事：階段結束後，能不能開啟某個東西，親眼看到它正在運作？

三個階段只是範例，不是固定標準。有時兩個就夠，有時則需要六個。

提供目前階段所需的上下文

選好階段後，只要提供代理完成該階段所需的資訊，不必一次交代整個專案。教學參照表的 M2 要求可以這樣寫：

為地區設定清單新增搜尋功能。
目前四筆資料的清單已經正常運作。保留欄位和版面，
不要修改原始陣列內容。只新增搜尋所需的項目。

請閱讀 @index.html 和 @app.js。

需求：
- 在清單上方新增搜尋欄位；
- 可依地區代碼和語言名稱搜尋；
- 搜尋 de-DE 和 German 都會找到 de-DE；
- 搜尋 zzz 時清單不顯示任何資料；
- 查詢欄空白時顯示完整清單。

這次不新增依國家篩選的功能。
如果還需要其他檔案，請指出並閱讀。
先說明成果與階段範圍，暫時不要修改檔案。

如果您認可代理提出的範圍，下一則訊息就請它執行 M2，並列出要在瀏覽器中進行的檢查。也請它分清楚哪些是自己驗證過的，哪些還需要您檢查。

範例中的路徑只是示意，您手上的檔案會不同。如果工作需要的來源檔案沒有出現在要求中，代理應該指出來並讀取。只憑檔名猜測檔案內容不是好方法，也不該要求它這麼做。

版面在這裡是另一類資訊，而這個階段正是要保留它。但有時版面本身會是階段成果，例如頁面第一次出現時。只用文字很難描述清楚："弄漂亮一點"沒有任何可驗證的條件，決定權就留給代理。這時可以附上範例，例如版面草圖、截圖，或列出色彩和 class 名稱的小檔案。

也要記得這類說法的限度。"這次不新增篩選功能"只是要求，不是技術上的限制。它能指引工作方向，卻無法真正阻擋修改，所以您仍然要自行檢查成果。

什麼時候該縮小階段

階段很容易在工作過程中越擴越大。原本只是新增搜尋，途中卻發現最好重整資料結構、更新版面，順便加上頂部導覽。這種情況應該不陌生。

針對每項新增需求，先問它是不是目前成果所必需。新的色彩主題和導覽可以晚點再做，但搜尋輸入欄位不可少。如果資料中缺少搜尋所需的欄位，先重新確認範圍：可以在目前階段補上資料，也可以把資料準備工作另外拆成一個可驗證的階段。原本不准修改資料的限制，不能在工作途中默默取消。

重新限定範圍的要求可以寫得很短：

這次不修改資料、版面和導覽，
請把它們分別列為之後再做的項目。
保留依代碼和語言搜尋：輸入欄位、比對結果、空白查詢。

階段在取得約定成果並完成驗證後才算結束。如果檢查沒通過，先處理目前階段；直接跳到下一個階段只會讓情況更不明朗。

有時階段也會卡住：您指出問題，代理修改後還是不對，又得再改一次。失敗的嘗試不會消失，它們仍留在對話裡，後續嘗試也會受到影響。Claude Code 文件提供一個簡單的判斷方式：同一件事如果已經修正超過兩次，就開啟新對話，並把目前掌握的資訊寫進要求裡。例如："用獨立陣列來搜尋行不通，因為它和原始資料不一致；請直接搜尋主要陣列。"通常這樣比連續修改第三次更有效。如果還是沒改善，階段可能太大，應該再拆小一些。

保存接續工作的起點

左側分支會回到同一階段繼續修改，因為成果還沒通過驗證。右側則前往記錄狀態和下一階段。請在備忘錄中保存通過的檢查，以及尚未涵蓋的部分。

確認成果後，就記下目前狀態。寫備忘錄不是為了交代工作，而是避免隔天或換個對話時，還得在聊天紀錄裡翻找整段過程。

檔名不限，也可以沿用現有的工作備忘錄。這裡就叫它 PROGRESS.md。以下是 M1 驗證完成後的教學範例；請只記錄您實際完成和觀察到的內容：

# 地區設定參照表

## 已完成
M1：頁面會顯示 app.js 陣列中的地區設定清單。

## 已驗證
在瀏覽器中開啟 index.html：有 4 筆資料，每筆的五個欄位
都與 app.js 中的原始陣列相符。

## 尚未驗證
資料集為空時，頁面會顯示什麼。
這項檢查不在 M1 的條件中；目前還不知道空陣列時會如何處理。

## 決策
資料以陣列形式存放在 app.js，沒有另外載入資料。
新增搜尋功能時，保留資料內容與版面。

## 不採用的做法
從獨立的 JSON 檔案載入資料：沒有伺服器時，瀏覽器
無法讀取這個檔案，而頁面必須能直接以檔案形式開啟。

## 檔案
index.html, app.js

## 待完成階段
M2：可依地區代碼或語言名稱搜尋。
驗證：de-DE 和 German 都會找到 de-DE；
zzz 找不到資料；空白查詢會顯示四筆資料。

M3：依國家篩選可與搜尋搭配使用。
驗證：Canada + French 只留下 fr-CA；
Canada + German 不會找到資料；
清除兩個條件後會顯示四筆資料。

## 下一步
執行 M2。暫時不要新增依國家篩選的功能。

這裡最重要的是"已驗證"一節。一週後再看到"全部正常"完全沒有參考價值，但"在瀏覽器開啟，看到 4 筆資料，欄位相符"就很明確。特地列出尚未驗證的部分，就是因為到了明天，您已經記不得這個差別。

"不採用的做法"這一節很容易被當成多餘，畢竟記的都是專案中沒有的內容。但在新對話裡，代理不知道之前試過什麼，很可能又提出同一種方法。多寫一句原因，就能省下一整輪溝通。

您可以請代理寫備忘錄，但要把內容和目前的檔案及驗證結果比對。它可能只根據對話紀錄整理，而紀錄中會同時出現已完成的操作與計畫。要記錄瀏覽器中的觀察結果時，請註明由誰檢查；不要說成是代理做了它其實沒執行的驗證。

還有兩項限制。任務目前的進度不應寫進 CLAUDE.md，那裡放的是專案的長期規則，不是今天正在處理的事情。備忘錄也不會保存程式碼版本，它只是狀態紀錄，不是檔案的副本。

帶著需要的資訊繼續工作

階段的分界點很適合用來決定接下來要在哪段對話中工作。只要問自己：目前的對話對下一步有幫助，還是已經開始妨礙工作？

如果還有幫助，就繼續使用，不必特地做什麼。沒有"每個階段結束後都要清空對話"這種規則，也沒有某個使用百分比門檻，超過後就必須重新開始。

如果不確定對話紀錄占用了多少空間，可以執行 /context，查看上下文視窗的使用狀況。再對照目前的工作進度：下一階段還需要哪些冗長的輸出和討論？這個指令可以協助您評估用量，但不會替您判斷哪些資訊有用。

如果對話累積了太多無關內容，而您決定另開一段對話，先保存備忘錄。執行 /clear 會開始新對話：舊紀錄不會納入新對話的工作上下文，原始檔案仍保留在磁碟上，專案指示也會繼續載入。這不代表舊對話被永久刪除，您仍可透過 /resume 回到已保存的對話。不過要在新工作階段接續任務，最好明確提供需要的決策資訊。

兩支箭頭在繼續工作前會合。備忘錄保存決策和驗證結果，檔案則呈現目前的程式碼。代理會閱讀兩種來源並重述現況；在請它執行 M2 之前，您要先確認它的說明是否正確。

開啟新對話時，可以這樣開始：

請閱讀 @PROGRESS.md、@index.html 和 @app.js。
請用自己的話說明哪些已完成並通過驗證，還有哪些待完成。
暫時不要修改檔案。

仔細閱讀代理的回覆。如果它說某項工作已完成，但您其實沒有做過，就把它的說法和備忘錄、檔案及驗證結果互相比對。可能是紀錄不夠精確、程式碼已經過時，也可能是代理自己判斷錯誤。開始修改前先釐清差異：開啟新對話本身不會修正錯誤的任務描述，也不保證代理能正確理解。

從頭到尾完成這份參照表

前面的說明到此告一段落，接下來請親自完成同一份參照表：從空資料夾開始，做到 M2 通過驗證，並記錄接續工作的起點。四個步驟的順序和本文一致。每一步都先自行撰寫 prompt，再把範例當作另一種參考；重點是判斷代理需要哪些資訊，而不是照抄範例。

步驟 1：先規劃，不寫程式碼

目前還沒有專案，您可能最想直接說"做一份參照表"。那樣一來，檔案會比相關決策更早出現。這一步的目標正好相反：取得計畫，但一個檔案也不建立。輸入之前，先想想以下四點：

• 要怎麼讓代理先別急著開始寫程式碼；
• 檔案尚未建立時，可以先提供哪些資訊；
• 要說明哪些技術限制，才不會多出不需要的工具；
• 目前還不能建立檔案時，該要求代理提供什麼。

範例如下：

我想建立一份教學用地區設定參照表：列出項目、提供搜尋，
並依國家篩選。目前還沒有專案。

頁面必須能直接以檔案形式在瀏覽器中開啟，不需要伺服器或建置：
只有 index.html、styles.css 和 app.js。每筆資料包含地區代碼（en-US）、
語言、國家、貨幣和網域。

請先擬定計畫：
- 說明整個任務的目標、範圍和驗證方式；
- 將工作拆成三個階段；
- 說明每個階段的成果，以及我驗證時會看到什麼；
- 指出還需要我提供哪些資訊；
- 列出您會建立哪些檔案。

暫時不要建立檔案。

請將代理提出的階段和上方的 M1-M3 表格比對，順序不同也沒關係。如果它把工作拆成"完成所有標記，再處理所有 JS"，就請它重擬計畫，讓頁面在每個階段完成後都能實際運作。如果某個階段沒有可觀察的行為，現在就調整描述；還沒開始寫程式碼時，一句話就能解決。

步驟 2：只做 M1，並附上範例

這個階段的範圍很小：頁面只顯示四筆資料，不做搜尋或篩選。不過版面無法延後決定，因為頁面第一次出現時就會有某種外觀。因此請附上範例：將 mockup.html 存在專案資料夾中，裡面只放靜態標記、色彩和 class 名稱，不要使用 JavaScript。

<style>
  body   { background:#0f172a; color:#e2e8f0; font-family:system-ui, sans-serif; padding:24px }
  .search{ width:100%; margin-bottom:12px; padding:10px 14px; border-radius:10px;
           background:#1e293b; color:#e2e8f0; border:1px solid #334155 }
  table  { width:100%; border-collapse:collapse }
  th, td { padding:10px 12px; text-align:left; border-bottom:1px solid #334155 }
  th     { color:#8b98b1; font-size:13px }
  .code  { font-family:ui-monospace, monospace; font-weight:700; color:#818cf8 }
</style>

<input class="search" placeholder="Search by code or language">
<table>
  <tr><th>Code</th><th>Language</th><th>Country</th><th>Currency</th><th>TLD</th></tr>
  <!-- 範例資料列；實際資料列由 app.js 產生 -->
  <tr><td class="code">en-US</td><td>English</td><td>United States</td><td>USD</td><td>.us</td></tr>
</table>

範例中已經畫好搜尋欄，但 M1 不要把它加到頁面上：一個不能用的空白欄位很難驗證。它的樣式定義在 .search class 中，M2 會用到。

還有一點：請明確提供資料給代理。沒有資料時，它會自行編一組，表格中提到的檢查條件就會對不上，例如四筆資料、de-DE、Canada。現在先想想 prompt 要怎麼寫：如何讓代理限定在一個階段、修改前要它說明什麼，以及您要如何驗證成果。

只執行 M1：頁面顯示 app.js 陣列中的地區設定清單。
這次不做搜尋或篩選，也先不要加入範例中的搜尋欄位。

資料就是以下四筆陣列，不要修改內容：
[請貼上本文中的陣列]

版面請依照 @mockup.html，使用其中的色彩與 class 名稱，
不要自行新增其他名稱。

請先列出檔案計畫，並說明會在哪裡停止。
在我確認計畫之前，請不要建立檔案。
修改完成後，告訴我應該開啟哪些內容，以及要拿來和什麼比對。

完成 M1 後請停下，沒有我的指示不要開始 M2。

計畫範圍太大，就先別確認，要求代理將這個階段縮小到一項可驗證的成果。計畫合理後，再允許修改，接著開啟頁面，將四筆資料和陣列比對。從這一刻起，基本版面就固定了：後續要保留它，完整更換主題則繼續列在延後處理的項目中。

步驟 3：M2 與如實記錄

M2 的 prompt 已經在"提供目前階段所需的上下文"一節說明過。回到那裡，換成您自己的路徑即可。文中提到兩個檔案，但完成 M1 後您有三個：除了 index.html 和 app.js，還有 styles.css，也要一併提供。再補上一句：現在是保留既有版面，不是重新指定版面。

M1 已依照 @mockup.html 設定版面，請保持原樣，
並使用其中的 .search class 設定搜尋欄的樣式。

代理提出的範圍正確，就允許它修改。如果它的計畫碰到篩選功能或資料結構，先問清楚再讓它動手。三項搜尋檢查都通過後，參考上面的格式，在 PROGRESS.md 記錄目前狀態；這次要寫 M2 完成後的情況和您自己的檔案清單。

也試著檢查備忘錄是否真的有用。想像"已驗證"一節只寫著"幾乎都好了，剩下一點收尾工作"。一週後看來，這句話完全沒有資訊。請補上足以讓您接續工作的內容：實際開啟了什麼、看到了什麼、哪些項目尚未檢查，以及下一步要做什麼。例如："M2：搜尋 de-DE 和 German 都找到 de-DE；zzz 找不到資料；空白查詢顯示四筆資料"、"尚未檢查資料集為空時的行為"、"下一步：M3，依國家篩選"。

步驟 4：從新對話接續工作

最後一步要檢查的是備忘錄，不是程式碼。開啟新對話，請代理根據 PROGRESS.md 和所有最新檔案重述現況，包含 styles.css 在內的三個檔案都要讀，再把它的說明和您實際做過的事比對。如果代理說某項工作已完成，但您從未驗證過，問題很可能出在備忘錄寫得太籠統，應該修改備忘錄，而不是再開一段對話。不過也要比對檔案：原因可能在程式碼，也可能是代理判斷錯誤。都確認無誤後，您就有通過驗證的 M1、M2，以及開始 M3 的明確起點。

如何進入下一個階段

最後可以整理成幾個簡單步驟：

1. 選擇最近、可驗證的成果；
2. 提供代理此階段需要的來源，並說明範圍；
3. 完成目前階段，並另外記下新增的需求；
4. 執行約定的驗證；在本文範例中，請於瀏覽器檢查頁面行為；
5. 記錄狀態：已完成、已驗證、尚未驗證、不採用的做法，以及下一步；
6. 決定要繼續使用目前的對話，還是另開一段。

一個階段不等於一則訊息，可能會用上三則，也可能十五則，這都很正常。階段數也不等於對話數：相鄰的兩個階段可以在同一段對話中完成，而一個較難的階段有時也會用上兩段對話。

不過，不論進行到哪一步，您都能回答目前有哪些功能正在運作，以及如何驗證。對大型任務來說，這大概是最重要的事。