writing-plans

writing-plans skill 概覽

writing-plans skill 會做什麼

writing-plans skill 的用途，是在正式開始寫程式之前，先把功能規格或需求文件整理成一份細緻、可執行的 implementation plan。它的核心工作不是發想點子，而是產出一份能落地、能審查的計畫；即使實作者對 codebase 幾乎沒有背景，也能從中拿到清楚的檔案層級指引、測試步驟與任務順序。

誰適合使用 writing-plans

這個 skill 最適合已經有明確需求範圍、現在需要為 Requirements Planning 做執行計畫的工程師、tech lead，以及 agent 驅動的工作流程。特別是當工作會跨多個檔案、涉及測試與文件，或是最後要交接給原始 spec 作者以外的人時，writing-plans 會特別有價值。

它真正解決的是什麼問題

使用 writing-plans 的人，通常是想降低實作時的猜測成本。重點不只是「做一份計畫」，而是「做一份讓有能力的工程師在沒有隱含前提下也能照著做的計畫」。這包含要動哪些檔案、怎麼把工作拆成小而可執行的任務、要測哪些內容，以及哪些範圍應該在實作前就先切開。

它和一般 prompt 有什麼不同

writing-plans skill 在幾個關鍵地方有明確的方法論，而且這些差異真的會影響成果：

• 它會先做 scope 檢查，再進入拆解
• 它要求先釐清各檔案的責任，再寫任務
• 它偏好小而可測的增量，而不是大區塊階段
• 它預設實作者對領域與 codebase 的背景很弱
• 它附帶 reviewer prompt，用來檢查這份計畫是否真的可實作

如果你在意交接品質，這會比一句「幫我寫 implementation plan」的通用 prompt 更可靠。

什麼情況下 writing-plans 特別適合

當你手上有以下條件時，建議使用 writing-plans：

• 已寫好的 spec、ticket 或 requirements doc
• 一個有多個步驟、且實作細節不可忽略的變更
• 需要協調程式碼、測試與文件
• 一個檔案邊界與實作順序都很重要的 repository

如果你只是想快速列個大綱或抓個粗估，這個 skill 可能就偏重了。

如何使用 writing-plans skill

writing-plans install 的實際情境

這個 repository 並沒有在 skill 內提供獨立的 package-level installer，所以實務上的 writing-plans install 做法，是先安裝上層 skill collection，再從裡面呼叫這個 skill：

npx skills add https://github.com/obra/superpowers --skill writing-plans

如果你的環境使用其他 skill loader，就安裝 obra/superpowers collection，然後從 skills/writing-plans 選用 writing-plans。

先讀這兩個檔案

如果你想快速判斷是否值得採用，建議先看：

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

SKILL.md 提供的是實際的規劃流程；而 reviewer prompt 則能看出這份計畫預期要達到的品質門檻。若你打算把 writing-plans 用進正式流程，先看這兩份會很有幫助。

這個 skill 需要哪些輸入

writing-plans usage 在你提供以下資訊時效果最好：

• 原始 spec 或需求文件
• 目標 repository 或 codebase 範圍
• 架構、tooling、時程或 backward compatibility 等限制
• 如果你不想用預設位置，請提供計畫輸出的目標路徑
• 這份工作是否應拆成多份彼此獨立的 plan

如果沒有真實 spec，這個 skill 通常還是能產出看起來合理的結構，但 implementation guidance 會明顯變弱。

一開始先照要求宣告

上游說明明確要求 agent 先宣告：

I'm using the writing-plans skill to create the implementation plan.

如果你要把它整合進 agent workflow，建議保留這一行。這可以讓 skill 的啟用更明確，也能降低外界不清楚目前套用哪一套規劃標準的情況。

最好在寫程式前使用，理想上放在獨立 worktree

這個 skill 是為實作前規劃而設計的，並預期在上游 brainstorming workflow 建出的獨立 worktree 中執行。就算你沒有完全照這個搭配方式使用，背後的原則仍然很重要：先在隔離的工作環境裡完成規劃，再開始改 code，這樣 plan 才會是有意識產出的工件，而不是邊寫邊補出來的副產品。

怎麼把模糊需求改寫成更強的 prompt

弱的 prompt：

• 「幫我規劃加入 billing。」

更強的 prompt：

• 「Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

為什麼這樣比較有效：

• 它明確指出 spec
• 它點出可能會碰到的檔案或模組
• 它交代了會影響拆解方式的限制條件
• 它允許依 scope 切成多份 plan，而不是硬塞成一份過大的計畫

依照 skill 的規劃順序走

一份好的 writing-plans guide，應該遵循 repository 隱含的方法順序：

1. 先檢查這份 spec 是否應拆成多份獨立 plan
2. 在拆任務之前，先把檔案和責任對應起來
3. 寫出小而可執行的 implementation tasks
4. 把 tests、docs 和 validation steps 一起納入
5. 完成後再用 spec 回頭檢查整份 plan

其中最常見、也最容易讓成果變空泛的問題，就是跳過檔案結構這一步。

好的輸出應該包含什麼

一份強而實用的 writing-plans for Requirements Planning 輸出，通常應該包含：

• 計畫目標與對應的 spec
• 需要新增或修改的檔案
• 每個檔案為什麼存在、或為什麼需要改
• 小到可以獨立完成、獨立驗證的任務
• 不只是 coding steps，還要有 testing guidance
• 如有需要，包含文件或 migration 更新
• 細節要足夠，讓另一位工程師接手時不會卡住

如果輸出大多只是像「backend」「frontend」「QA」這種主題式階段，通常代表拆得還太粗。

預設的 plan 存放路徑，以及何時該覆寫

這個 skill 建議把 plan 存成：

docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

如果你的 repo 本來就有既定規劃路徑，例如 docs/plans/ 或 specs/implementation/，就應該覆寫成既有慣例。真正重要的是一致性，以及 reviewer 之後找得到這份文件。

怎麼用 reviewer prompt

在 plan 初稿完成後，可以用 plan-document-reviewer-prompt.md 當作第二輪審查模板。它的審查標準很務實：

• 完整性
• 與 spec 的對齊程度
• 任務拆解品質
• 是否真的可建置、可實作

這也是 writing-plans skill 很有辨識度的一點：它不只幫你生成內容，還附了一個輕量的驗收檢查，讓你知道這份 plan 是否達標。

一套實務上好用的 workflow

一個可靠的流程大致會長這樣：

1. 收集 spec 與 repo 脈絡
2. 執行 writing-plans
3. 檢查 plan 是否切分得正確
4. 審視檔案邊界與任務粒度是否合理
5. 執行 plan reviewer prompt
6. 在真正開始實作前先修訂 plan

這樣用時，writing-plans 最有價值的角色是規劃關卡，而不只是省一點寫文件時間的工具。

writing-plans skill 常見問題

writing-plans 適合新手嗎？

適合，前提是新手手上已經有一份相對具體的 spec。這個 skill 會用明確的檔案指引與測試要求，補足對 codebase 背景不熟的問題。但如果真正卡住的是產品方向還沒想清楚，它就幫不上那麼多。

它和直接叫 AI 寫 implementation plan 有什麼差別？

通用 prompt 很常產出看起來完整、實際上偏淺的 plan。writing-plans 更有用的地方，在於它會逼你做到檔案層級拆解、可測性，以及交接品質。這通常能讓正式開始寫 code 後少走很多回頭路。

什麼情況不該用 writing-plans？

遇到以下情況可以跳過：

• 變更很小，而且只在局部
• 產品範圍還在討論中
• 你現在需要的是架構探索，而不是執行規劃
• 這份工作本來就是實驗性質，而且很可能馬上改方向

這些情境下，輕量筆記往往比正式 plan 更合適。

它有要求特定技術棧或 framework 嗎？

沒有。這個 skill 偏重流程方法，而不是綁定特定 framework。它之所以能跨技術棧使用，是因為重點放在拆解、檔案責任、測試與可審查性。

writing-plans 能處理大型 spec 嗎？

可以，但前提是你要尊重 scope-check 這一步。原始內容已經明講：如果 spec 涉及多個彼此獨立的 subsystem，通常應拆成不同的 plan。若你硬要把所有內容塞進一份超大型 plan，任務品質通常就會下降。

只靠 writing-plans 就足夠做 Requirements Planning 嗎？

如果你做的是偏 implementation 的 Requirements Planning，很多情況下夠用；但如果還在 discovery 階段，就不夠。因為它的前提是你已經知道要做什麼，現在缺的是一條可靠的落地路徑，而不是繼續釐清需求方向。

如何改進 writing-plans skill 的使用效果

提供更強的 repository 脈絡

想提升 writing-plans 輸出品質，最簡單的方法就是直接點名可能涉及的目錄、模組或檔案。這個 skill 會很早就嘗試對應檔案責任；如果你先給出可能的 touchpoints，輸出就會更具體，也比較不會流於空泛。

先把彼此獨立的 subsystem 拆開

如果你的 spec 混在一起談了幾個其實不相干的議題，最好在要求最終 plan 之前先拆開。例如：

• auth 變更
• billing 變更
• admin UI 變更

它們在產品層面也許會一起上線，但若能各自獨立實作與測試，通常就值得拆成不同的 plan。

明確要求先做檔案責任對應

如果第一版 plan 還是太模糊，可以直接要求：

• 「List each file to add or modify and state its responsibility before writing tasks.”

這種要求和 skill 本身的結構高度一致，通常很能改善拆解模糊的問題。

強制把任務粒度縮小

很常見的失敗模式，是任務大到不適合安全實作。你可以明確要求：

• 任務必須能產生可測的進度
• 每個任務都有清楚邊界
• 每個主要變更後都要有明確 validation

這也是 writing-plans usage 最容易看出改善幅度的地方：任務越小，越容易審查、分派與執行。

把測試要求講得更具體

不要只說「包含 tests」。更好的做法是直接指定：

• 哪個層級的測試最重要
• 哪些既有 test suites 需要更新
• 是否需要 migration、integration 或 regression checks

這個 skill 本來就重視測試，但限制條件講得越清楚，最後 plan 的實用性就越高。

用 reviewer 驅動的迭代來打磨初稿

把 reviewer template 當作編修工具，而不只是最後把關。第一版 plan 出來後，可以接著問：

• spec 還缺了哪些需求
• 哪些任務其實不可執行
• 哪些地方會讓實作者卡住
• 是否出現 scope creep

這種方式通常比單純下「improve the plan」這類寬泛指令，更能產出銳利的第二版。

留意這些常見失敗模式

writing-plans skill 在以下情況會比較弱：

• spec 不完整
• 檔案邊界是猜的，沒有根據 repo 實況
• 任務只描述結果，沒有實作步驟
• 有提到測試，但沒有和 code 變更對起來
• 一份過大的 plan 掩蓋了多個其實獨立的 deliverables

如果你看到這些症狀，先回頭修輸入條件，而不是立刻怪 skill 不好用。

補上會影響實作選擇的限制條件

有用的限制條件包括：

• backward compatibility 要求
• 效能預期
• migration 安全性
• deployment 順序
• 文件更新義務
• 禁止新增 dependency 的規則

這些細節能幫助 writing-plans for Requirements Planning 產出符合你環境的 plan，而不是停留在理想化、通用型的答案。

用實際交接需求來檢查 plan

最直接的品質檢查方式其實很簡單：如果另一位對背景不熟的工程師拿到這份文件，能不能不需要反覆追問就開始實作？如果不行，就繼續補強，直到檔案選擇、任務邊界與 validation steps 都足夠明確。

讓 plan 保持 DRY，並聚焦 implementation

原始指引強調 DRY、YAGNI、TDD 與 frequent commits。落到實務上，就是要去掉重複任務、避免預先做過多假設性的工作，並優先選擇能快速編碼與驗證的小步增量。和一味增加篇幅相比，這些原則對輸出品質的影響其實更大。