產生路線圖
路線圖是一份可供下一個人直接接手執行，而不需仰賴產生它的對話的計畫。它說明專案試圖達成什麼目標、以何種順序進行、如何判斷每個部分已完成，以及哪些問題仍懸而未決。路線圖與其所描述的程式碼一同存放在儲存庫中，因此與其他檔案一樣，會經過審查和版本控制。
路線圖記錄決策，而非制定決策。當某件事尚未決定時，路線圖會如實說明。
儲存庫規則優先
在開始撰寫之前，請先查閱儲存庫自身的慣例：AGENTS.md、CLAUDE.md、CONTRIBUTING.md、docs 或 wiki 的結構，以及任何現有的路線圖。這些慣例決定路線圖的存放位置、攜帶的中繼資料、議題的連結方式以及應執行的檢查。當它們與本技能衝突時，以它們為準。請遵循現有路線圖的格式，而不是引入另一種格式。
工作流程
1. 確認需求
釐清使用者想要的是哪一種操作，因為每種操作需要的工作量不同：
- 新路線圖： 針對專案、功能、遷移、測試工作等。
- 更新： 新增或變更項目、重新排序階段、記錄決策。
- 對齊： 使現有路線圖與實際已完成的工作保持一致。
- 審查： 閱讀路線圖並報告遺漏之處，不進行改寫。
2. 先蒐集證據，再提問
閱讀專案已知的資訊：相關的程式碼和測試、已開啟和最近關閉的議題、已合併和開啟中的 PR、現有文件，以及該區域的提交歷史。記錄目前已存在的內容、已在進行中的工作，以及過去曾嘗試過的方法。
任何能透過這種方式獲得資訊，就不要詢問使用者。
3. 詢問需要判斷的事項
路線圖的好壞取決於其背後的決策，而這些決策大多屬於使用者。以簡短輪次提問，而不是一次列出長串問題，並在取捨不明顯時解釋問題的重要性。合適的主題：
- 目標： 這項工作值得做的成果是什麼？如何判斷是否達成？
- 範圍： 明確排除哪些事項？哪些內容不能更改（API、資料格式、行為）？
- 限制： 截止日期、發佈時程、人員、預算、平台。
- 優先級： 如果只能完成一半，該先完成哪一半？
- 風險： 最不了解的部分是什麼？是否應該優先處理？
- 完成標準： 哪些測試、指標或審查可視為完成的證明？
當證據支持時，提供建議。務必讓使用者可以回答「尚未決定」。該答案應歸入「開放決策」，而不是猜測。
對於小型更新，可直接開始撰寫。對於新路線圖，預計需要兩到三個輪次。
4. 選擇結構
- 單一檔案（
ROADMAP.md，或與儲存庫相符的名稱）適用於大多數路線圖。 - 目錄（
roadmaps/<slug>/README.md加上輔助頁面）僅在計畫需要大量輔助材料（例如研究筆記、設計草稿或測試矩陣）且這些材料會淹沒工作項目時使用。主頁面仍應擁有所有工作項目的 ID。
5. 撰寫
使用下方的範本。以下規則可確保路線圖長期有效：
- 穩定的 ID。 為每個工作項目賦予一個 ID，例如
R-001。永不重新編號，也永不重複使用 ID。已放棄的工作應留在檔案中，標記為dropped，並說明原因。 - 階段有退出標準。 每個階段說明完成時應滿足的條件。階段的排序應先依據依賴關係，其次為風險，再來是價值。
- 驗收條件是可檢查的。 撰寫他人可以驗證的條件：一個通過的測試、一個成功執行的指令、一個可衡量的數字。避免使用如「穩健」、「改善」、「乾淨」等詞彙。
- 依賴關係明確。 使用 ID 列出。標明任何超出團隊控制範圍的事項，例如其他儲存庫、供應商或決策。
- 使用完整 URL 或儲存庫相對路徑連結證據，以確保連結在複製到其他地方後仍有效。
- 描述計畫，而非會議。 使用現在式，描述當前狀態。歷史記錄應歸入變更日誌。
6. 檢查
在交付之前：
- 每個項目都有 ID、狀態和至少一個驗收條件。
- 每個依賴關係都指向一個存在的 ID。
- 沒有階段依賴於後續階段。
- 每個未決問題都在「開放決策」中，而非隱藏在某個項目內。
- 連結可解析，檔案路徑存在。
- 儲存庫的格式化和文件檢查通過。
- 變更日誌包含此次變更的條目。
7. 報告
告知使用者你建立或變更了哪些內容、記錄了哪些決策，以及仍有哪些問題懸而未決。
使路線圖與實際情況對齊
隨著工作完成，路線圖會漸漸偏離實際狀況。要進行對齊：
- 列出所有狀態不是
done或dropped的項目。 - 對於每個項目，尋找已合併的 PR、已關閉的議題，以及滿足其驗收條件的程式碼。
- 僅在每個條件都滿足時，才將項目標記為
done。並附上證據的連結。 - 如果工作完成方式與計畫不同，請更新項目以描述實際情況，並在變更日誌中記錄差異。
- 將你發現的任何新工作作為新項目，並賦予新的 ID。
- 向使用者總結變更。在放棄任何項目之前，先詢問使用者。
審查路線圖
當僅要求審查時，不要進行改寫。請依重要性排序報告：
- 目標或階段無法判斷何時完成；
- 驗收條件模糊的項目；
- 缺少依賴關係或存在循環依賴；
- 看似已定案但證據並不支持的決策；
- 程式碼或議題追蹤器顯示已完成或已不再相關的項目；
- 缺少風險：最困難或最不了解的部分被安排在後期。
範本
# <專案或功能> 路線圖
**目標：** <以一兩句話說明的成果>
**狀態：** <draft | active | complete | superseded>
**最後更新：** <YYYY-MM-DD>
## 背景
這項工作為何在此時有其重要性、目前已存在的內容，以及相關證據的連結。
## 範圍
- **包含：** …
- **排除：** …
- **不可變更：** …
## 狀態說明
| 狀態 | 意義 |
| ------------- | ------------------------------------------- |
| `planned` | 已同意，尚未開始 |
| `in-progress` | 有人正在進行中 |
| `blocked` | 等待依賴項或決策（請說明） |
| `done` | 所有驗收條件已滿足，並附有證據 |
| `dropped` | 不進行（請說明原因） |
## 階段 1：<名稱>
**退出標準：** <此階段完成時應滿足的條件>
### R-001：<簡短標題>
- **狀態：** planned
- **原因：** <此項解決的問題>
- **驗收條件：**
- [ ] <可檢查的陳述>
- **依賴於：** <ID 或 "none">
- **證據：** <議題、PR 或檔案連結>
## 階段 2：<名稱>
…
## 開放決策
| ID | 問題 | 選項 | 阻擋項目 | 負責人 |
| ----- | --------- | --------- | -------- | ------ |
| D-001 | … | … | R-004 | … |
## 風險
| 風險 | 可能性 | 影響 | 緩解措施 |
| ------- | ------ | ----- | -------- |
## 變更日誌
- <YYYY-MM-DD>：<變更內容與原因>
刪除不適用的章節。一個小型路線圖可能只需要目標、一個階段和一個變更日誌。
請勿
- 因為路線圖看起來不完整而編造一個決策。
- 用沒有具體成果的通用項目（例如「增加文件」、「改善測試」）來填充計畫。
- 重新編號項目，或刪除已放棄的項目。
- 僅根據 PR 標題就將工作標記為
done，而未檢查驗收條件。 - 將路線圖的全部內容複製到議題中，或反過來。應使用連結。