name	process-task-list
description	Task list management and execution for spec-driven development. Use when: executing implementation tasks, managing task progress, processing task list with git commits. Keywords: task execution, process-task, implementation, commit, task management, 任務執行, 實作, 任務清單.

任務清單管理

用於在 Claude Code 中管理任務清單的指導原則，以追蹤完成 PRD 的進度

工作流程脈絡

整體開發流程

本指令是 claude-code-config 三步驟開發流程中的第三步：任務執行。完整流程如下：

【選用】需求研究 (/research)：深入調查技術問題、探索解決方案、產出研究文件
需求澄清 (/create-prd)：透過問答釐清需求、產出 PRD 文件
實作規劃 (/create-impl-plan)：分析 PRD 和程式碼庫、產出任務清單和驗收測試
【當前】任務執行 (/process-task-list)：逐一實作任務、執行驗收測試

當前階段的輸入與輸出

輸入來源（至少需要 PRD 或 Research 其中之一）：

implementation.md：任務清單和實作要點（必需）
acceptance.feature：驗收測試場景（必需）
PRD 文件：功能背景和商業需求（產品導向任務）
Research 文件：技術分析和解決方案（技術導向任務）

三種常見流程：

Research + PRD：完整流程，implementation.md 來自完整規劃
只有 PRD：技術明確，implementation.md 直接從產品需求產出
只有 Research：技術導向任務，implementation.md 從研究結論產出

輸出目標：

實際的程式碼變更
Git commits（每個任務完成後）
驗收測試結果

各參考文件的角色

implementation.md：

提供任務清單和優先級
提供實作要點和技術指導
提供「實作參考資訊」（來自 research 和 PRD 的技術細節）

acceptance.feature：

提供驗收測試的具體場景
幫助理解功能的預期行為

prd.md（產品導向任務）：

提供功能的商業背景和使用者價值
幫助理解「為什麼」要這樣實作
提供高層次的技術方向

research 文件（技術導向任務）：

提供問題分析和技術選型的背景
提供已驗證的解決方案和最佳實踐
補充深入的技術脈絡

當前階段的職責範圍

應該做的事：

按順序執行任務清單中的任務
參考實作要點完成實作
在需要理解背景時參考 PRD 和 research
完成任務後進行 git commit
執行驗收測試

不應該做的事：

擅自修改任務清單的順序或範圍（除非發現明確的問題）
忽略實作參考資訊中的技術決策
在不理解商業背景的情況下實作

Claude Code 任務清單同步

Claude Code 提供內建的 TodoWrite 工具來管理任務，這與 Cursor 等其他編輯器的工作方式不同。為了充分利用 Claude Code 的功能同時保持任務記錄的持久性，我們需要同步機制。

同步機制

初始載入： 從 implementation.md 的「任務概要」區塊讀取任務清單，使用 TodoWrite 工具將其轉換為 Claude Code 內部任務清單
雙向同步： 當 Claude Code 內部任務清單狀態改變時（pending、in_progress、completed），必須同步更新 implementation.md 中「任務概要」區塊對應的任務項目
格式對應：
- Claude Code pending → Markdown [ ]
- Claude Code in_progress → Markdown [ ] (可在旁邊加註 進行中)
- Claude Code completed → Markdown [x]
任務識別： 使用任務標題（而非編號）作為唯一識別方式，確保概要和細節區塊的標題完全一致

為什麼需要同步

持久化： TodoWrite 的任務只存在於當前對話，implementation.md 提供永久記錄
可見性： 用戶可以直接在檔案中查看任務進度
協作： 其他開發者可以透過 implementation.md 了解專案狀態
版本控制： implementation.md 可以透過 Git 追蹤歷史變更

任務實作

一次一個任務： 完成一個任務後，在請求用戶許可並獲得「yes」或「y」回應之前，不要開始下一個任務
執行時參考：
- 從「任務概要」區塊識別當前要執行的任務
- 從「任務細節」區塊找到對應的任務章節（標題完全一致）
- 參考該任務的「實作要點」和「相關檔案」進行實作
實作過程記錄：
- 在任務執行過程中，遇到以下情況時，立即在「實作備註」區塊記錄：
  1. 方向調整：發現原計畫不可行或需要改用其他方法時
    - 觸發條件：使用者指出錯誤、發現技術限制、原方法行不通
    - 記錄格式：[方向調整] 原計畫 X 因 Y 原因不可行，改用 Z 方法
    - 範例：[方向調整] 原計畫使用 localStorage 但需跨 tab 同步，改用 BroadcastChannel API
  2. 技術障礙：遇到預期外的問題需要特別處理時
    - 觸發條件：API 不支援、效能瓶頸、相容性問題、需要繞過的限制
    - 記錄格式：[技術障礙] 遇到 X 問題，因為 Y，解決方式是 Z
    - 範例：[技術障礙] Next.js 動態路由不支援 SSG，需使用 generateStaticParams 預生成路徑
  3. 關鍵決策：與使用者討論超過 3 輪才確定的技術方案
    - 觸發條件：有多個可行方案、需要權衡取捨、影響後續任務
    - 記錄格式：[技術決策] 在 X 和 Y 方案之間選擇 Z，因為 W
    - 範例：[技術決策] 在 REST 和 GraphQL 之間選擇 REST，因現有後端已是 REST 且團隊更熟悉
  4. 後續依賴：後續任務必須知道的資訊
    - 觸發條件：建立了新的前置條件、修改了共享資源、有執行順序要求
    - 記錄格式：[後續依賴] 後續任務需注意 X，因為 Y
    - 範例：[後續依賴] 後續任務需注意必須先呼叫 initAuth() 才能使用其他 auth 函數
- 照預期完成時：如果整個任務執行過程都按照任務敘述順利完成，沒有觸發上述任何情況，則標註「照預期開發」
- 詳細的實作備註品質指引，請參考實作備註指引
完成協議：
1. 實作任務時，參考「任務細節」中的所有實作要點
2. 完成任務後，請按照以下順序操作：
- 檢查並完善實作備註：
  - 檢視「實作備註」區塊，確認已記錄所有方向調整、技術障礙、關鍵決策、後續依賴
  - 如果執行過程中已經即時記錄，確認記錄完整清晰
  - 如果執行過程中沒有觸發任何需要記錄的情況，標註「照預期開發」
  - 不要重複記錄任務敘述中已有的實作細節
- 更新任務狀態：在 implementation.md 的「任務概要」區塊中將完成的任務標記為 [x]
- 暫存變更：執行 git add .（包含 implementation.md 的變更）
- 清理：在提交前移除任何臨時檔案和臨時程式碼
- 提交：使用描述性的提交訊息，該訊息應：
  - 使用慣例提交格式（feat:、fix:、refactor: 等）
  - 總結任務中完成的內容
  - 列出關鍵變更和新增內容
  - 引用任務標題（而非編號）和 PRD 上下文
1. 提交後，在 TodoWrite 中將任務狀態更新為 completed
每個任務完成後停止並等待用戶的許可。

任務清單維護

工作時更新任務清單：
- 使用 TodoWrite 工具管理內部任務狀態
- 同步更新 implementation.md「任務概要」區塊中的任務標記（[ ] → [x]）
- 當新增任務時，必須同時更新：
  - 「任務概要」區塊：新增 - [ ] 任務標題
  - 「任務細節」區塊：新增完整的任務章節（### 任務標題 + 實作要點 + 相關檔案 + 實作備註）
  - TodoWrite 內部清單
維護任務細節區塊：
- 每個任務的「相關檔案」列出該任務創建或修改的檔案
- 為每個檔案提供一行描述其用途的說明
- 任務執行後填寫「實作備註」，記錄重要的上下文資訊

AI 指示（Claude Code）

處理任務清單時，Claude Code 必須：

首次載入任務：
- 讀取 implementation.md 檔案
- 從「任務概要」區塊提取任務清單（僅包含任務標題和 checkbox）
- 讀取 acceptance.feature 檔案以了解驗收標準和大局觀點
- 從 implementation.md 的「PRD 參考」章節讀取來源文件：
  - 若有 PRD 文件路徑，讀取 PRD 文件
  - 若有相關研究文件路徑，讀取研究文件
  - 可能兩者都有，或只有其中一個
- 使用 TodoWrite 工具將任務清單轉換為內部任務格式
- 使用任務標題作為唯一識別方式（不使用編號）
任務狀態管理：
- 使用 TodoWrite 工具管理任務狀態（pending、in_progress、completed）
- 一次只能有一個任務處於 in_progress 狀態
- 完成任務時立即更新為 completed
執行任務時：
- 首先，讀取所有已完成任務的「實作備註」：
  - 檢視 implementation.md 中所有已標記為 [x] 的任務的「實作備註」區塊
  - 特別關注：方向調整、技術障礙、關鍵決策、後續依賴等標籤
  - 目的：了解之前實作過程中遇到的問題和做出的調整，避免當前任務與前置脈絡不一致
  - 重點檢查：當前任務是否依賴前置任務、前置任務是否有方向調整影響當前任務
- 從「任務細節」區塊找到對應的任務章節（標題與「任務概要」完全一致）
- 參考「實作要點」進行實作
- 檢查「相關檔案」了解需要修改的範圍
- 完成實作後，必須執行「完成檢查」：
  - 參考任務的「完成檢查」章節，執行所有檢查要點
  - 優先使用 MCP 工具進行檢查（如 supabase mcp、playwright mcp 等）
  - 其他檢查手段包括：執行測試指令、執行建置指令、手動驗證檔案內容等
  - 即使任務是撰寫文件，也應檢查文件是否達成預期目標
  - 所有檢查要點都通過後，才能進入下一步驟
- 完成檢查通過後，填寫「實作備註」
同步更新 implementation.md：
- 每當 TodoWrite 中的任務狀態改變時，立即更新 implementation.md 的「任務概要」區塊
- 將完成的任務標記為 [x]
- 使用 Edit 工具更新檔案
新增任務：
- 當發現新任務時，同時更新：
  - TodoWrite 內部清單
  - implementation.md 的「任務概要」區塊（新增 checkbox 項目）
  - implementation.md 的「任務細節」區塊（新增完整任務章節）
填寫實作備註：
- 執行任務過程中，遇到方向調整、技術障礙、關鍵決策、後續依賴時，立即記錄到「實作備註」區塊
- 使用結構化標籤：[方向調整]、[技術障礙]、[技術決策]、[後續依賴]
- 任務完成後，檢查實作備註是否完整，照預期完成的任務標註「照預期開發」
- 參考實作備註指引確保記錄品質
驗收測試任務處理：
- 檢測任務標題或描述中包含以下關鍵詞的任務：
  - 「驗收測試」、「acceptance testing」、「驗收」、「validate implementation」
  - 「執行驗收測試」、「進行驗收」、「驗證實作」等相關詞彙
- 當遇到驗收測試任務時，使用 Skill tool 調用 acceptance-test skill
- 調用方式：skill: "acceptance-test"
- acceptance-test skill 會自動讀取 implementation.md、acceptance.feature 和背景文件（PRD 或 research）並執行驗收測試
- 驗收測試由 acceptance-test skill 專門處理，不要在當前 skill 中直接執行測試邏輯
工作流程：
- 檢查下一個待處理任務，識別是否為驗收測試任務
- 將任務標記為 in_progress（驗收測試任務調用 acceptance-test skill）
- 完成後標記為 completed 並同步更新 implementation.md
- 等待用戶核准後再進行下一個任務

process-task-list

Install Skill

SKILL.md