概觀
writing-plans 技能能做什麼
writing-plans 技能協助你把產品規格或技術需求文件，轉成一份完整、可直接實作的計畫，讓團隊在 還沒開始動程式碼之前 就把路線規劃清楚。它特別適合有多步驟功能或變更要上線時，幫你產出一份拆解良好、讓另一位工程師在沒有既有背景下也能照著做的實作計畫。
使用 writing-plans，你產出的計畫會：
- 假設執行者是有能力的開發者，但對你的 程式庫與領域都是新手。
- 明確列出每個工作要 新增或修改哪些檔案。
- 強調需要的 測試、文件更新與人工檢查。
- 把工作切成 小而可交付的任務，邊界清楚。
這能讓交辦工作、審查計畫，以及避免範圍膨脹或遺漏邊角情境更容易。它反映 DRY、YAGNI、TDD、frequent commits 等實務精神，但重點放在 專案規劃與工作拆解，而不是產生程式碼。
適合哪些人使用 writing-plans？
如果你是以下角色，可以考慮使用 writing-plans：
- 需要為功能開發與重構建立可重複規劃流程的 技術主管與工程經理。
- 想在實作風險較高或跨多層面變更前，先釐清自己做法的 個人開發者。
- 使用 subagents 或分散式協作、需要透過清楚的書面計畫來協調貢獻者的團隊。
特別適用在：
- 你手上有功能、遷移或整合的 規格或需求文件。
- 工作會動到 多個檔案、元件或服務。
- 你希望別人能在 不必一直來問問題 的情況下完成實作。
不那麼適合用在：
- 還在 發想問題或找解法 的階段（先使用發想／腦力激盪類的技能會比較好）。
- 任務 非常小（例如只改一行）而不需要正式計畫。
- 你主要需求是 程式碼審查或程式碼產生，而不是規劃與任務拆解。
在你的工作流程中的定位
這個 repository 預期 writing-plans 會在腦力激盪階段之後，並在專案的 專用 worktree 中使用。一般流程如下：
- 先在本技能之外進行腦力激盪並釐清規格。
- 為該功能建立或打開專用的 worktree。
- 執行 writing-plans 技能產出實作計畫。
- 將計畫（預設）儲存到：
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md- 或你自訂的其他計畫儲存位置。
- 可以選擇使用提供的模板，派送一個 plan document reviewer subagent 來在實作前檢查並驗證這份計畫。
如何使用
安裝與設定
1. 安裝 writing-plans 技能
你可以直接從 obra/superpowers repository 安裝此技能：
npx skills add https://github.com/obra/superpowers --skill writing-plans
這會拉下 writing-plans 的技能定義以及相關 prompts，讓你能在自己的專案中使用。
2. 檢視核心檔案
安裝完成後，建議先查看這些關鍵檔案，以了解並調整整體工作流程：
skills/writing-plans/SKILL.md– 說明此技能預期行為的主檔案，包含範圍、計畫結構，以及對工程師的假設。skills/writing-plans/plan-document-reviewer-prompt.md– 可重複使用的 prompt 模板，給用來審查完成計畫的 subagent。
本機路徑會依你如何 vendor 或 mirror 此 repository 略有不同，但檔名會維持相同。
準備執行 writing-plans
3. 確認規格與範圍
在使用 writing-plans 之前，請先確認你已經準備好：
- 一份針對這個功能或變更的 清楚規格或需求文件。
- 足夠的細節，能辨識主要元件、整合點與限制條件。
此技能包含一個 Scope Check 步驟：如果你的規格涵蓋多個彼此獨立的子系統，它預期你已在腦力激盪期間，把這些工作拆成各自獨立的子專案規格。如果尚未拆分，你應該：
- 將工作切成多份 獨立計畫，每個子系統一份。
- 確保每份計畫都能單獨產出 可運作且可測試的軟體。
這能避免單一計畫變得難以掌控，也有助於讓工作對齊可部署的單位。
4. 準備 worktree 與計畫檔
上游的建議假設你會：
-
在為此功能準備的 專用 worktree 中工作（在腦力激盪期間就已建立）。
-
將產出的實作計畫儲存為：
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
如果你的團隊偏好其他目錄結構，例如 docs/plans/ 或 planning/，也可以自行調整。關鍵是這份計畫要 被納入版本控制，與程式碼一起版控，並且之後容易找到。
執行技能並撰寫計畫
5. 宣告並開始規劃工作階段
當你呼叫此技能或開始規劃對話時，建議明確說出：
"I'm using the writing-plans skill to create the implementation plan."
這能讓目標明確：現在要產出的是一份 有結構的實作計畫，而不是設計探索或程式碼輸出。
6. 先規劃檔案結構
在列出任務之前，writing-plans 會特別強調 以檔案為單位的拆解：
- 先找出會 新增或修改哪些檔案。
- 為每個檔案指定一個 單一且明確的責任。
- 設計彼此具有 清楚界面與邊界 的單元。
在這個階段，計畫應該要能回答：
- 新的邏輯會放在哪裡？
- 會動到哪些既有檔案，原因是什麼？
- 這些檔案在高層次上會如何互動？
在一開始就把合理的檔案結構定下來，能大幅降低後續任務拆解、程式碼審查與未來重構的難度。
7. 把工作拆成小塊任務
在檔案對應（file map）確立之後，利用 writing-plans 把規格轉成一連串 小而可獨立理解的任務。上游指引特別強調：
- 每個任務都要有 清楚的目標，而且具體可執行。
- 任務要小到可以 頻繁 commit。
- 計畫本身要符合 DRY（不要重複指示），並避免 YAGNI 式的多餘工作（不要做預先猜測的任務）。
對於每個任務，計畫應包含：
- 會動到哪些檔案。
- 在高層次上要修改哪些程式或設定。
- 需要新增或更新哪些測試。
- 需要更新哪些文件。
目標是讓幾乎沒有背景的工程師，也能接下一個任務就獨立完成，且有信心不會誤解。
8. 把測試與文件納入計畫
writing-plans 預期你會把 測試與文件 直接寫進計畫中：
- 指出需要新增或更新哪些 unit tests、integration tests 或 end-to-end tests。
- 在適用時明確標出如何 執行測試（例如指令、測試入口）。
- 說明必須更新哪些 文件，例如 README 段落、使用者指南或 API 文件。
這能確保品質與可維護性一開始就成為計畫的一部分，而不是事後才補強。
檢視與反覆修正計畫
9. 使用 plan document reviewer 模板（選用但強烈建議）
plan-document-reviewer-prompt.md 檔案提供了一個給 plan document reviewer subagent 使用的結構化 prompt。它的目的包括：
- 檢查計畫是否 完整，並且符合規格。
- 驗證 任務拆解 是否合理且可執行。
- 確認工程師能 一路照計畫實作而不會卡關。
這個模板會列出多個審查面向，包括：
- 完整性 – 重要需求不可出現 TODO、佔位符或關鍵步驟缺漏。
- 規格對齊 – 計畫必須涵蓋規格內容，且沒有明顯的範圍膨脹。
- 任務拆解 – 任務邊界清楚且可實作。
- 可建置性 – 有能力的工程師能從頭到尾照著計畫完成實作。
審查者會被指示要聚焦在可能造成 實作上真實問題 的事項，而不是文字小修或風格偏好。
你可以把這個審查步驟整合進 CI、審查流程或人工審閱中。
10. 依照回饋反覆調整
如果審查者（不論是人還是 subagent）發現缺漏需求、步驟互相矛盾，或任務描述太模糊等問題：
- 在計畫檔內修正內容。
- 視需要重新執行或再次派送 reviewer。
- 一旦計畫獲得核准，就把它當成實作的 單一權威來源（source of truth）。
讓 writing-plans 更貼合你的團隊
11. 自訂結構與慣例
雖然上游技能定義了清楚的行為與預設值，你仍然可以依團隊需求做調整，例如：
- 變更 計畫檔儲存位置，讓它符合你的 repository 架構。
- 加入團隊特有的 檢查清單（例如資安審查、效能測試）當作重複出現的任務。
- 將計畫與你的 issue tracker 整合，把任務對應到實際的 ticket。
由於 writing-plans 主要關注的是 結構化工作流程與專案管理，因此能很好地跨語言、框架與領域套用。
常見問題
什麼時候應該使用 writing-plans？
只要你有一個 多步驟的功能、重構或整合工作，並且有相對明確的規格，而且希望產出一份讓其他工程師在沒有背景下也能執行的實作計畫時，就適合使用 writing-plans。特別適合在會觸及多個檔案或子系統的複雜變更之前使用。
什麼情況下 writing-plans 不太適合？
以下情況 writing-plans 並不是理想選擇：
- 你仍在 探索解法，規格尚不穩定。
- 工作規模小到使用正式計畫只會增加負擔。
- 你只是在尋求 程式碼產生 或 程式碼審查，而不是任務拆解與專案規劃。
這些情況下，建議改用腦力激盪、設計或以程式碼為主的技能。
一定要用預設的 docs/superpowers/plans/ 路徑嗎？
不用。上游建議把計畫存放在：
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
但也明白說明 使用者對計畫存放位置的偏好可以覆寫這個預設值。你可以依照 repository 與文件標準，自由選擇任何目錄與命名方式。
可以用 writing-plans 處理非程式專案嗎？
此技能是以 軟體專案與程式碼庫 為前提設計的，包括檔案對應與測試等概念。不過，它的核心想法──將工作拆成小任務、釐清責任分工、檢查完整性──也可以調整後套用到其他技術工作流程。只要你的領域多少存在檔案、測試或文件更新等概念，它就仍然有相當效果。
writing-plans 如何幫助新人上線與工作交接？
由於 writing-plans 假設執行者 對你的程式庫完全沒有背景，而且品味堪慮，它會逼你：
- 清楚解釋程式該放在哪裡，以及原因是什麼。
- 把測試與文件寫得明確。
- 從任務描述中移除模稜兩可之處。
這讓把工作交接給新成員、外包工程師或 subagents 容易得多。他們可以直接照計畫執行，而不需要從規格中反推你的本意。
writing-plans 和專案管理工具之間的關係是什麼？
writing-plans 是對專案管理工具的補充，而不是替代：
- 它提供一份 結構化的文字計畫，具體說明如何在程式碼與檔案層級實作某份規格。
- 接著你可以把計畫中的任務對應到 Jira、GitHub Issues、Linear 等工具中的項目。
這個技能位在 專案管理、工作流程模板與技術報告撰寫 的交會點，提供一個可重複使用的模式，幫你建立一致的實作計畫。
可以只用 reviewer prompt，而不使用整個技能嗎？
可以。plan-document-reviewer-prompt.md 可以獨立當作任何類型「計畫式文件」的 審查模板 使用。你可以把它當成 subagent 的 prompt 來：
- 審查用 writing-plans 撰寫的計畫。
- 檢查由其他流程或工具產出的計畫。
不過，當計畫內容與審查流程都對齊 writing-plans 的工作流時，通常能得到最一致、最有品質的結果。