subagent-driven-development

subagent-driven-development skill 概覽

subagent-driven-development 實際上在做什麼

subagent-driven-development skill 是一套執行實作計畫的工作流程：先把工作切成彼此獨立的任務，再把每個任務交給全新的 subagent，最後對每份結果做兩輪審查：先看是否符合 spec，再看程式碼品質。它真正的價值不在於「多用幾個 agent」，而是刻意利用隔離的 context，讓每個執行者只拿到完成當前任務所需的任務內容、需求與局部程式碼背景。

這個 skill 最適合哪些情境

這個 subagent-driven-development skill 最適合已經有計畫、現在需要在當前 session 裡把計畫穩定落地的人。尤其適合以下情況：

• 任務之間大多彼此獨立
• 你希望 coordinator agent 專注在 orchestration，而不是親自寫所有程式碼
• 你在意的不只是需求偏移，也包括草率、鬆散的實作
• 你要的是可重複執行的審查迴圈，而不是一次性的 coding prompt

要解決的核心工作

使用者會採用 subagent-driven-development for Agent Orchestration，通常是因為一般的「幫我實作這份計畫」prompt 已經開始出現固定失敗模式：agent 把多個任務混在一起、忘記限制、過度實作，或產出看起來合理卻沒真正符合 spec 的程式碼。這個 skill 提供的是一種有紀律的交接與審查模式，用來降低這些失敗。

它和一般 prompt 有什麼不同

它的差異點很實務：

• 每個任務都用全新的 subagent，而不是讓同一個長時間運作的 agent 背著一堆雜訊歷史
• 明確的 task packet，把完整任務內容直接貼進去，而不是要求執行者自行從分散的檔案推斷需求
• 先提問再開始 coding，讓不清楚的需求提早浮出來
• 兩階段審查，把「有沒有照 spec 做」和「程式碼寫得好不好」分開處理

這種分離很重要。很多團隊會先看品質再驗 scope，結果反而更難看出實作是否做過頭，或做得不夠。

什麼情況下不適合用

如果你手上還沒有具體的 implementation plan、任務之間高度耦合，或這份工作其實更適合放到另一條平行執行流程，而不是留在這個 session 內，就不要一開始直接用 subagent-driven-development。這些情況通常應該先做規劃，或改用其他執行型 skill。

如何使用 subagent-driven-development skill

安裝 subagent-driven-development skill

如果你是透過這個 repository 的 Skills CLI 安裝 skill，請使用：

npx skills add https://github.com/obra/superpowers --skill subagent-driven-development

安裝後，第一次使用前先打開這個 skill 本體以及相關 prompt templates。

先讀這幾個檔案

如果你想快速上手，建議照這個順序讀：

1. SKILL.md
2. implementer-prompt.md
3. spec-reviewer-prompt.md
4. code-quality-reviewer-prompt.md

這個閱讀順序會先讓你掌握整體 workflow，再看到 implementer 與兩個 review 階段各自實際使用的 prompt 形狀。

開始前先理解它的呼叫模式

實務上，subagent-driven-development usage 不是一條神奇指令就能搞定。你需要自己扮演 coordinator，流程如下：

1. 從 plan 中取出一個任務
2. 用範圍嚴格收斂的 prompt 派出一個全新的 implementer subagent
3. 要求它回報執行情況
4. 針對實際程式碼執行 spec reviewer
5. 只有在 spec 通過後，才執行 code quality reviewer
6. 接受、要求修改，或重新派發任務

如果你把 review gate 省掉，那其實就不算是照這個 skill 的設計在用。

這個 skill 需要哪些輸入

在派出任何 subagent 之前，先準備好以下資訊：

• 來自 plan 的完整任務文字
• acceptance criteria 或需求條件
• 相關的架構背景
• 工作目錄或 repo 範圍
• 任何相依關係或執行順序註記
• 用來做 review diff 的 baseline commit 或 SHA
• 任務編號與任務名稱，方便追蹤

從原始 templates 的寫法可以明顯看出：你應該把完整任務直接貼進 prompt，而不是叫 subagent「自己去讀 plan file」。

把模糊目標改寫成強韌的 implementer prompt

弱的 prompt 長這樣：

• 「Implement task 4 from the plan.」

更完整的 subagent-driven-development guide prompt 應該包含：

• Task title 和 number
• 完整 task 文字
• 這個任務存在的原因
• repo 裡要在哪些位置動手
• 檔案結構上的限制
• 是否需要測試
• 如果不得不做假設，該如何處理
• 開始 coding 前必須先提問的要求

這種結構很重要，因為這個 skill 的核心是可控的 context，而不是讓 subagent 自主地對整個 repo 做大範圍詮釋。

更好的 task packet 範例

派發 implementer 時，可以用這種結構：

• Task N: [name]
• FULL TEXT of task from plan
• Context: where this fits, dependencies, architecture
• Work from: [directory]
• Requirements: implement exactly what is specified
• If anything is unclear, ask before starting
• Write tests if required by task
• Commit, self-review, and report back

這會比叫執行者自行廣泛探索可靠得多，因為這個 skill 預設 coordinator 必須對任務封裝品質負責。

為什麼 spec review 要先於 quality review

這是很多人評估 subagent-driven-development install 時最值得注意的設計之一：這個順序是刻意安排的。

先跑 spec reviewer，是為了回答：

• 程式碼是否真的實作了被要求的內容？
• 有沒有漏掉需求？
• 有沒有多做沒被要求的部分？
• 有沒有誤解任務？

只有在這之後，才應該執行 code quality reviewer，去檢查可維護性、拆分方式、檔案責任劃分，以及整體變更形狀。如果順序反過來，看起來很漂亮的程式碼反而可能掩蓋 scope 錯誤。

如何正確使用 spec reviewer

spec-reviewer-prompt.md 的語氣非常直接：它明確要求 reviewer 不要相信 implementer 的自述，而是要逐行對照實際程式碼驗證。你在調整這份 template 時，應保留這種基調。reviewer 需要的資訊包括：

• 完整任務需求
• implementer 聲稱完成的內容
• 變更後程式碼的存取權限

重點是獨立驗證，不是禮貌性地確認一下。

如何正確使用 code quality reviewer

這裡的 code quality review 不是一般性的 style 糾察。在這個 skill 裡，它特別強調：

• 每個檔案只承擔一個清楚責任
• 介面定義明確
• 拆分成可理解的單位
• 是否符合原本規劃的檔案結構
• 這個任務是否新增了過大的新檔案，或讓既有檔案明顯膨脹

最後這一點特別實用，因為 subagent 很常靠把太多內容塞進一次變更來「完成」任務。

在真實 repo 內建議怎麼跑這個流程

一個實務可行的 subagent-driven-development usage 迴圈大致如下：

1. 選出下一個彼此獨立的任務
2. 把目前 commit 記錄成 baseline
3. 帶著完整 task 文字派出 implementer
4. 收集對方的摘要與變更檔案
5. 針對需求與實際程式碼執行 spec review
6. 如果 spec 不通過，把具體缺口退回給 implementer
7. 如果 spec 通過，再執行 code quality review
8. 如果品質不通過，要求聚焦修改
9. merge，或移動到下一個任務

這樣可以讓 coordinator 一直掌握順序與驗收主導權。

會影響輸出品質的限制條件

這個 skill 在遵守以下邊界時效果最好：

• 獨立任務比糾纏在一起的任務更適合
• 明確需求比推測需求更有效
• 明確限定 repo 範圍，比「你自己看看再決定」更可靠
• 短週期的小任務，比一次塞進多個大功能更好
• 清楚的升級／回報規則，比默默猜測更穩定

如果你發現某個 subagent 必須同時協調整個 codebase 裡很多變動中的部分，那這個任務多半已經大到不適合這套 workflow。

常見導入錯誤

最大的錯誤，就是嘴上說自己在用 subagent-driven-development skill，實際上卻還是在寫鬆散的 prompts。這個 workflow 只有在你真的仔細封裝 context，並且嚴格執行 review 順序時，才會產生效益。否則你只會承擔 orchestration 的額外成本，卻拿不到品質提升。

subagent-driven-development skill 常見問題

subagent-driven-development 適合初學者嗎？

適合，前提是你已經知道自己要做出的任務是什麼。這套 workflow 很明確，而且提供的 prompt templates 能降低猜測空間。不過它不能取代規劃。如果是還沒有清楚 implementation plan 的初學者，通常會卡住，因為這個 skill 預設任務定義早就存在。

什麼時候不該用 subagent-driven-development？

以下情況建議跳過 subagent-driven-development：

• 你還在探索問題本身
• 任務彼此高度相依
• 需求仍然不穩定
• 必須由同一個人或同一個 agent 持續跨整個系統做整體推理

它是執行模式，不是探索模式。

它和直接叫一個 agent 把全部程式碼寫完有什麼不同？

單一長 prompt 往往會把規劃、實作、驗證與審查全部塞進同一個 context window。這個 skill 則把這些角色拆開。這通常能提升專注度、更容易抓到需求漂移，也能把 coordinator 的 context 留給 orchestration，而不是拿去做 code generation。

這個 skill 需要特殊工具嗎？

不需要。這個 skill folder 沒有附帶任何特殊 script。repository 提供的是 markdown prompt templates，而不是自動化程式。只要你的環境能派出 subagents、也能做 code review 類任務，就能套用這個模式。

subagent-driven-development 只適合大型專案嗎？

不是。小型修改也能用，但它最有價值的情況，還是當 plan 裡有多個彼此獨立的任務，而且漏掉需求的成本高到值得你多做一層 review。

安裝前最值得看的 repository 證據是什麼？

對這個 skill 來說，最關鍵的證據就是 SKILL.md 與三份 prompt templates 所呈現的 workflow 設計。這裡沒有任何 helper scripts 或 resource folders 在背後偷偷做事，所以你的安裝判斷重點應該放在：這套 prompt 結構與 review 紀律，是否符合你目前實際交付程式碼的方式。

如何改進 subagent-driven-development skill

改進 task packet，而不是一味把 prompt 寫更長

想讓 subagent-driven-development skill 的結果更好，應該提升精準度，而不是單純增加字數。最有幫助的補充資訊包括：

• 明確的 acceptance criteria
• 清楚列出的 non-goals
• 只與這個任務相關的 architecture notes
• 檔案或目錄邊界
• 預期行為範例
• 測試要求

這能幫 implementer 保持聚焦，也能讓 spec reviewer 更容易抓出偏移。

把任務邊界切得更銳利

很多失敗都來自切工太差。如果某個 subagent 必須同時協調多個變動中的部分、決定架構，還要自己推斷需求，那就應該把任務拆開。更好的任務應該窄到讓「是否完全照要求實作」這件事可以被輕鬆驗證。

保留「先提問」這一步

implementer template 明確要求執行者在開始前先提問，並且在實作中遇到意外時也要再次提問。這個行為不要拿掉。壓制澄清問題，雖然會讓輸出看起來更快，但可靠度也會一起下降，這正好違背這個 skill 的目的。

用更強的比對輸入提升 review 品質

對 spec reviewer，請提供：

• 完整需求文字
• implementer report
• 變更檔案或 diff 範圍
• 任何明確排除項目

對 code quality reviewer，請提供：

• BASE_SHA
• HEAD_SHA
• 任務摘要
• 相關的 plan 區段

這些具體的比對錨點，能讓 review 不只是主觀意見。

留意這些常見失敗模式

subagent-driven-development for Agent Orchestration 最常見的問題包括：

• implementer 自行推導出額外功能
• task packet 漏掉關鍵限制
• reviewer 太相信 implementer 的摘要
• code quality review 在 spec review 之前就執行
• 任務大到無法乾淨驗證
• 檔案膨脹沒有被控制

這些問題都能透過更好的任務封裝與更嚴格的 gatekeeping 預防。

看完第一次輸出後再迭代

如果第一輪結果不理想，不要立刻從頭全部重來。先判斷是哪一層出了問題：

• spec failure: 需求不清楚、遺漏，或過度實作
• quality failure: 拆分、可維護性，或檔案結構有問題
• coordination failure: 任務切分或 context 封裝方式不對

接著只修那一層。這樣 workflow 才能保持效率。

收緊檔案結構指引

quality template 裡有個很實用的檢查點：確認實作是否遵守預定的檔案結構，以及新建立的檔案是否一開始就過大。如果你在意可維護性，最好在 task packet 裡先把預期的檔案邊界講清楚，而不是事後才期待 reviewer 幫你抓出來。

建立可重用的本地 checklist

如果你會經常使用 subagent-driven-development，建議保留一份簡短的 coordinator checklist：

• plan 已存在
• task 是獨立的
• 完整 task 已貼入
• 約束條件已包含
• baseline SHA 已記錄
• 已要求 implementer 在 coding 前先釐清問題
• spec review 已完成
• quality review 已完成

這種小習慣帶來的一致性，通常比把 prompt 寫得更長還有用。

讓 skill 更貼合你的實際 workflow

這個基礎 skill 故意保持輕量。若要讓它在你的環境裡更有效，可以依照你的技術棧與 review 標準改寫 prompt templates：

• 加入你的 testing commands
• 加入 repo 專屬的架構規則
• 定義什麼情況算 over-engineering
• 指定你偏好的 report 格式
• 補進你們 codebase 常見的失敗模式

這類在地化調整，通常比增加更多理論說明，更能改善 subagent-driven-development usage。