subagent-driven-development

概觀

什麼是 subagent-driven-development？

subagent-driven-development 是一個用來協調代理工作的技能，讓你可以依照實作計畫，把工作拆成一連串獨立任務，並由全新的 subagent 逐一負責。對於每一個任務，你會：

1. 啟動一個專責實作的 implementer subagent。
2. 執行一個負責規格符合性的 spec compliance reviewer subagent。
3. 執行一個負責程式碼品質的 code quality reviewer subagent。

這三者都在嚴格控管的上下文中運作，只專注在當前任務；而你的主要工作階段則保留給協調與決策。

這個技能適合誰？

subagent-driven-development 是為下列開發者與團隊設計的：

• 使用 AI 協作寫碼工具（例如 Claude / claude-code），並希望結果更穩定可靠。
• 依照事先撰寫好的實作計畫作業，且計畫已拆分成清楚的任務。
• 需要在單一 AI 工作階段內，就能有結構化、可重複的程式實作與審查流程。
• 在乎規格正確性與程式碼品質，而不只是「能跑就好」。

特別適合重度使用 GitHub 的工作流程，你可以將 SHA、計畫檔以及 diff 傳入各個 subagent。

它解決哪些問題？

這個技能主要處理使用單一 AI agent 端到端開發時常見的幾個問題：

• 上下文膨脹（context bloat）： 單一 agent 累積過多歷史紀錄，導致注意力分散、失焦。
• 規格飄移（spec drift）： 實作逐漸偏離原本的計畫或需求。
• 審查力道不足： 同一段上下文既負責寫程式又負責審查，容易放過錯誤。

subagent-driven-development 強制採用一種模式：每個任務使用全新的 agent、嚴格限制上下文，並進行兩階段審查（先規格、再品質）。這能提升正確性，讓變更範圍更集中，也更容易針對實作計畫的每一步進行推理與追蹤。

什麼情境下特別適合使用 subagent-driven-development？

在下列情況時特別適合使用這個技能：

• 你已經有一份實作計畫，而且已拆成多個任務。
• 這些任務大致彼此獨立，不需要頻繁的跨任務協調。
• 你打算在當前工作階段內完成整份計畫，而不是分散在好幾天的工作階段。

如果你還沒有計畫，或是任務高度耦合、變化很快，你可能會想先：

• 透過其他技能或人工規劃，先進行腦力激盪或設計實作計畫。
• 在探索階段改用比較自由、單 agent 的工作流程。

使用方式

安裝

1. 將技能加入你的環境

從 obra/superpowers 儲存庫安裝 subagent-driven-development 技能：

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

這會將技能定義與相關提示模板拉進你的 skills-enabled 環境，讓你可以針對計畫中的每個任務協調各自的 subagents。

2. 檢視核心檔案

安裝完成後，開啟儲存庫中的技能目錄（或透過 skills browser）並查看：

• SKILL.md – 高層級說明、適用情境與核心工作流程。
• implementer-prompt.md – implementer subagent 的提示模板。
• spec-reviewer-prompt.md – 規格符合性 reviewer subagent 的提示模板。
• code-quality-reviewer-prompt.md – 程式碼品質 reviewer subagent 的提示模板。

你可以將這些視為範本，複製或調整後整合進你自己的自動化與工具串接中。

準備你的實作計畫

1. 撰寫或優化任務清單

在使用 subagent-driven-development 之前，先準備一份實作計畫，並確保其中的任務：

• 範圍明確、可被驗證與測試。
• 大致彼此獨立。
• 描述足夠詳細，讓 implementer subagent 不需要靠猜測就能著手實作。

每個任務都應該可以直接複製貼上到 implementer 提示中，作為「FULL TEXT of task from plan」。

2. 決定工作目錄與 Git 策略

提示模板預設你採用 Git 為基礎的工作流程，並有明確的工作目錄：

• 選定 implementer 會操作的 directory。
• 決定如何追蹤變更（例如為每個任務設定 BASE_SHA 和 HEAD_SHA）。

你會把這些值傳入規格與程式碼品質 reviewer 的提示中，以便進行精準的審查。

以任務為單位執行工作流程

1. 派遣 implementer subagent

對於每個任務 N，使用 implementer-prompt.md 模板建立一個新的 implementer subagent。

模板中的重點包括：

• 明確告訴 implementer："You are implementing Task N: [task name]"。
• 將任務的完整文字貼到 ## Task Description 區塊。
• 填寫：
  • Context – 這個任務在系統中的定位。
  • directory – 要修改程式碼的路徑。

implementer 會被指示：

1. 若有任何不清楚的地方，在開始前先提出澄清問題。
2. 完整、精準地實作任務規格所要求的內容。
3. 在合適的情況下撰寫並執行測試。
4. 驗證實作是否符合預期。
5. 提交（commit）這次的變更。
6. 產出一份清楚的實作報告。

由於你會為每一個任務建立全新的 subagent，它只會看到你提供的上下文，不會繼承主工作階段裡與任務無關的歷史紀錄。

2. 執行規格符合性審查

當 implementer 完成並回報後，使用 spec-reviewer-prompt.md 派遣一個規格符合性 reviewer subagent。

在這個模板中，你需要：

• 將該任務的需求內容貼到 ## What Was Requested。
• 將 implementer 的報告 貼到 ## What Implementer Claims They Built。

spec reviewer 會被明確指示不要盲信 implementer 的報告，必須：

• 直接閱讀實際的程式碼。
• 逐行對照需求。
• 找出缺少的需求、多做的內容／不必要的工作，以及理解上的誤差。

如果 spec reviewer 發現問題，你就再回頭與 implementer（可以是同一位 worker，或是新的 subagent）合作，補上缺漏後再往下一步走。

3. 執行程式碼品質審查

當規格符合性通過後，使用 code-quality-reviewer-prompt.md 派遣一個程式碼品質 reviewer subagent。

此模板預期會收到類似程式碼審查任務的描述，例如：

Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from implementer's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]

reviewer 會檢查：

• 實作是否乾淨、可維護。
• 檔案責任與介面設計（在可能的情況下，一個檔案聚焦一項清楚的責任）。
• 新增或修改的檔案大小與拆分是否合理。
• 測試涵蓋率，以及是否能獨立理解與測試各單元。

他們會回傳結構化的回饋：優點、問題（Critical / Important / Minor），以及整體評估。

接著你可以決定是否：

• 直接接受這次變更。
• 要求 implementer 進一步 refactor 或做後續修正。

依你的環境調整工作流程

1. 針對你的技術棧客製化提示

implementer-prompt.md、spec-reviewer-prompt.md 和 code-quality-reviewer-prompt.md 裡的模板刻意保持通用性。你可以依照你的：

• 程式語言與框架。
• 測試慣例（例如 pytest、Jest、Go test）。
• 儲存庫結構與命名習慣。

來進行客製化。

即使調整細節，仍建議保留核心結構：每個任務啟動新的 subagent、清楚分隔的區塊，以及明確的角色說明。

2. 自動化重複步驟

當你熟悉這個模式後，可以進一步以腳本或工具進行自動化：

• 將三個 subagent 呼叫（implementer → spec reviewer → code quality reviewer）包成單一指令，對應一個任務。
• 從計畫檔自動產生每個任務對應的提示內容。
• 透過讀取 Git metadata，預先填好 BASE_SHA 與 HEAD_SHA。

這樣可以把 subagent-driven-development 變成團隊可重複使用的工作流程自動化機制。

3. 什麼情況下不適合使用這個技能

在下列情況，你可能需要改採其他做法：

• 任務高度相互依賴，很難被乾淨地切割出來。
• 你尚未擬定清楚的實作計畫。
• 你需要長時間、跨多個工作階段的任務，並且必須保留長期上下文（例如持續好幾天）。

遇到這類情境時，可以優先使用以規劃、架構設計或長期 agent 為主的技能或流程，等到任務可以拆解為離散單元後，再回到 subagent-driven-development 來執行。

常見問題（FAQ）

實際上，「subagent-driven-development」代表什麼樣的作法？

在實務上，subagent-driven-development 的意思是：你不再要求一個全知的 agent 同時負責規劃、實作與審查所有事情，而是改成：

• 在主工作階段負責整體協調與上下文管理。
• 對於每一個任務，建立一個只握有必要資訊的全新 subagent。
• 先讓這個 subagent 完成實作，再用另外兩個 subagents 分別進行審查。

這種作法把關注點切開，讓上下文更容易掌控，也提升實作計畫各步驟的可靠性。

這跟一般單一 agent 的寫碼工作階段有什麼不同？

在單一 agent 模式下，以往的對話紀錄和程式碼變更都會累積在同一個上下文中，容易導致：

• 舊需求與新需求混在一起，產生混淆。
• 寫碼與審查使用同一套推理模式，較難看出自己的盲點。

相較之下，subagent-driven-development 會：

• 為實作與審查設定不同的提示與角色。
• 讓每個 subagent 在啟動時只帶入經過整理的上下文，而不是整段工作階段歷史。
• 強制採用先規格、再品質的審查順序。

這樣往往能得到更精準的實作，以及更誠實、嚴謹的審查結果。

我一定要完全照模板來嗎？

不必。儲存庫中的模板只是示範如何結構化 implementer、spec reviewer 與 code quality reviewer 的提示。建議你：

• 保留整體模式：implementer → spec review → quality review。
• 維持關鍵行為（例如 spec reviewer 必須閱讀真實程式碼，而不是只看報告）。

在這個架構下，你可以自由調整文字、加入專案特有的說明，並整合你的工具與團隊慣例。

可以在沒有 Git 的情況下使用 subagent-driven-development 嗎？

程式碼品質 reviewer 的模板預設會有 BASE_SHA 和 HEAD_SHA 等欄位，這在 Git 工作流程中相當自然。如果你沒有使用 Git：

• 仍然可以採用同樣的核心概念——啟動全新的 subagents 以及兩階段審查。
• 只要用你自己的方式替代 SHA 來指認前後狀態即可（例如檔案封存 ID 或快照路徑）。

這個技能本身不強制你使用 Git，只是提供以 Git 為例的說明與欄位設計。

這個技能有綁定特定的 AI 模型嗎？

儲存庫並沒有硬性綁定某一個模型，但確實是以現代通用程式碼模型為目標設計，例如 Anthropic 的 Claude / claude-code。你應該：

• 選用能閱讀並理解程式碼與測試的模型。
• 確認你的環境支援以自訂提示啟動多個 subagents。

如果你的技術棧有代理工具或任務執行器，可以將這些模板接入那套系統。

我要怎麼判斷什麼時候用 subagent-driven-development，比較適合哪時候用其他 superpowers 技能？

SKILL.md 檔案描述了決策準則：當你已有實作計畫、任務大致彼此獨立，且打算在當前工作階段內完成，就適合使用 subagent-driven-development。若其中任一條件不符合，你可能會想：

• 先用規劃或腦力激盪相關的技能，建立或補強實作計畫。
• 對於高度耦合、跨多個工作階段的任務，選擇其他執行或規劃模式。

在儲存庫中，我應該從哪裡開始看起？

如果你正在評估是否要安裝或採用這個技能，建議先從：

1. SKILL.md – 了解設計理念與高層級工作流程。
2. implementer-prompt.md – 看看 implementer subagents 是如何被設定的。
3. spec-reviewer-prompt.md – 了解規格符合性檢查的細節。
4. code-quality-reviewer-prompt.md – 理解品質與結構檢查的額外要求。

之後，你就可以把這些模板調整成符合自身需求的 agent orchestration 或工作流程自動化設定，完整發揮 subagent-driven-development 的效益。