概覽
brainstorming 技能在做什麼
brainstorming 技能強制一條清楚的規則：先完成設計與規格，實作工作放在後面。啟用後，brainstorming 會引導你先釐清使用者意圖、需求與高階設計，再寫程式碼、建立專案 scaffold，或呼叫任何實作類的技能。
它以協作對話為核心。你從一個粗略的想法開始，透過有針對性的提問，逐步釐清情境與限制，最後收斂成一份明確的設計與規格，讓使用者可以檢視與核准。只有在通過這個明確的「核准閘門」之後，才適合進入建置或重構階段。
誰適合使用 brainstorming
在以下情境時適合使用 brainstorming 技能：
- 你與 Claude 或類似代理一起討論產品功能、元件、UI 流程或架構調整
- 想避免「這太簡單，不需要設計」這種反模式
- 需要在程式碼變更前，留下可重複、可稽核的設計討論紀錄
- 時常建置或調整前端、UI/UX，或高度依賴流程的系統
它很適合個人開發者、產品工程師、設計師，以及想要輕量但一致「設計優先」流程的團隊。
這個技能要解決的問題
brainstorming 技能的設計目標是避免：
- 還沒釐清目標就直接開始寫程式碼
- 隱藏假設在實作到後期才浮現
- UI/UX 變更沒有清楚的使用者旅程或視覺方向就被實作出來
- 規格過於模糊，無法做可靠規劃或指派工作
透過強制設計檢查點，brainstorming 可減少返工、實作錯位與設計債。
什麼情況適合（或不適合）用 brainstorming
非常適合用在：
- 規劃新功能、調整行為、或設計 UI/UX flow
- 想要一個有結構的模板，用來發想、蒐集情境資訊、並完成設計核准
- 在思考方案時，如果有視覺 mockup 或圖表會更有幫助
較不適合用在：
- 純機械式修改（改 typo、重新命名變數、更新常數但不改行為）
- 已經有詳細且被核准的規格，只是在照表操課（這種情況可以改用偏實作導向的技能）
即便是看似微小的工作，例如一個小 config 變更或單一函式工具，也能從短暫的設計流程中獲益；你可以讓這段設計流程維持精簡，但仍然透過 brainstorming 來完成。
如何使用
安裝與設定
1. 安裝 brainstorming 技能
使用 skills CLI，從 obra/superpowers repository 加入 brainstorming 技能：
npx skills add https://github.com/obra/superpowers --skill brainstorming
這會拉下技能定義，以及相關的提示與可選的輔助 script，放在 skills/brainstorming 目錄下。
2. 瀏覽關鍵檔案
安裝後，建議先看一下這些檔案，了解整體流程與可用的 helper：
SKILL.md– 對 brainstorming 流程的核心說明，包括嚴格的「先設計後寫碼」閘門，以及必做步驟的 checklist。spec-document-reviewer-prompt.md– 規格審查子代理的 template prompt，用來檢查規格的完整性、一致性與清晰度。visual-companion.md– 說明如何使用瀏覽器式的 visual companion 來呈現 mockup、圖表與視覺選項。scripts/frame-template.html– visual companion 使用的 HTML frame template，用於建立一致且以 UI 為主的排版。scripts/helper.js– 在 visual companion 中處理選取事件與即時重整的 client-side helper。scripts/server.cjs,scripts/start-server.sh,scripts/stop-server.sh– 啟動與管理 visual companion server 的 scripts。
你不需要修改這些檔案就能開始使用 brainstorming 流程，但先了解有哪些工具，有助於把它整合進你自己的開發環境。
核心 brainstorming 流程
1. 從專案情境開始
每次使用 brainstorming，先圍繞目前專案建立共同背景。SKILL.md 中的 checklist 會強調：
- 檢視相關檔案與文件
- 快速瀏覽近期 commits 取得脈絡
- 找出這次會影響到系統的哪些部分
當你使用 Claude 或其他代理時，提示它 先探索專案情境，而不是一開始就要求修改程式碼。
2. 對於視覺相關問題，提供 visual companion
如果任務包含 UI/UX 或其他高度視覺性的主題，可以另外提供 visual companion 作為獨立步驟。visual-companion.md 中的規則是：
以問題為單位，而不是以整個 session 為單位來決定。問自己：使用者「看」會比「讀」更容易理解嗎？
使用瀏覽器式 companion 的情境包括：
- UI mockup 與排版選項
- 架構與流程圖
- 不同設計方向的並排比較
- 關於間距、階層、視覺細緻度的討論
保持在 terminal（純文字）中的情境則包括：
- 範圍、需求與術語定義
- 概念性取捨與 API / 資料模型的選擇
- 那些回答本質上是「文字」而非「畫面」的釐清問題
3. 一次問一個釐清問題
brainstorming 技能預期的是有紀律的對話，而不是一個巨大無比的單一 prompt。改用一連串聚焦的問題，例如：
- 「這個功能的主要使用者是誰？」
- 「在效能或部署上有什麼限制？」
- 「哪些平台和螢幕尺寸最重要？」
一次問一個問題、等待回覆，逐步修正你對問題的理解。
4. 產出具體的設計與規格
當你掌握足夠的情境後，把這些資訊整合成一份使用者可以真正核准的設計。依任務類型不同，可能會包含：
- 高階目標與成功指標
- 使用者故事或範例流程
- UI 版面描述與視覺方向（可選擇搭配 visual companion）
- 資料結構、介面設計或整合點
- 會影響實作的非功能性需求
將這些內容寫成一份結構化的規格文件，放在你偏好的位置（例如，如果你遵循 repository 慣例，可以放在 docs/superpowers/specs/）。
5. 嚴格執行設計閘門
SKILL.md 中一條關鍵規則，是這個嚴格的閘門：
在你提出設計並經由使用者核准之前，不要呼叫任何實作技能、寫任何程式碼、建立任何專案 scaffold，或採取任何實作行動。
即使工作看起來很簡單也一樣適用。對於非常小的變更，設計內容可能只有幾句話，但它必須存在，而且要明確獲得確認才能往前推進。
使用規格文件審查 template
1. 撰寫你的規格
完成 brainstorming 之後，依照你專案適合的結構撰寫規格，並存成之後能引用的檔案，例如：
docs/superpowers/specs/my-feature-spec.md
2. 啟動規格審查子代理
當規格準備好要驗證時，用 spec-document-reviewer-prompt.md 作為 template 啟動一個規格審查子代理。將 prompt 中的 [SPEC_FILE_PATH] 替換成你的規格檔路徑。
這個 reviewer 會：
- 檢查缺漏的章節、TODO 或「TBD」占位符
- 尋找矛盾之處與不一致的需求
- 標記容易造成錯誤實作的模糊需求
- 確保範圍收斂到足以支持單一、清楚的實作計畫
審查結果會包含一個 Approved | Issues Found 狀態，以及問題清單，每一項都說明為何會影響實作規劃。
3. 持續修訂直到通過
如果 reviewer 找到問題，請更新規格並重新執行審查。一旦規格被核准，你就有了穩固的基礎，可以交給實作相關技能和規劃工具。
使用視覺 brainstorming companion
1. 啟動 visual companion server
從 scripts 目錄中，你可以用以下指令啟動 brainstorm server：
./start-server.sh --project-dir /path/to/your/project
常用選項包括：
--project-dir <path>– 將 session 檔案存到<path>/.superpowers/brainstorm/，而不是/tmp，以便持久保存。--host <bind-host>– 綁定到特定介面（例如在 container 或遠端環境中使用0.0.0.0）。--url-host <display-host>– 控制回傳 URL JSON 中顯示的 hostname。--foreground或--background– 選擇在目前 terminal 中執行，或以背景行程方式執行 server。
啟動後，script 會輸出帶有 session URL 的 JSON。將這個 URL 用瀏覽器打開，即可進入 visual brainstorming 介面。
2. 呈現視覺選項
server 會監看某個目錄中的 HTML 檔案，並永遠提供最新的一個。典型流程如下：
- Claude（或你的代理）使用
frame-template.html作為基底，將 HTML 檔案寫入設定好的screen_dir。 - 當有新檔案產生時，瀏覽器會透過
helper.js自動重新載入。 - 使用者可以在 UI 中點擊不同選項或卡片，這些事件會透過 WebSocket 傳回給代理處理。
這樣就能輕鬆展示：
- 多種版面配置，以可點擊卡片呈現
- 流程圖與狀態機圖
- 色彩、間距或元件變體的視覺比較
3. 結束後停止 server
session 結束時，請用以下指令乾淨地停止 brainstorm server：
./stop-server.sh <session_dir>
對於位在 /tmp 的 session，這同時會清理產生的檔案；而位在 .superpowers/ 下的持久目錄則會被保留，方便你之後回頭查看 mockup 與圖表。
把 brainstorming 整合進你的工作流程
- 作為標準 pre-commit 步驟： 在 merge feature branch 前，要求先完成 brainstorming 並取得已核准的規格。
- 搭配其他技能： 先跑 brainstorming，產出規格，再交給實作、重構或測試類技能接手。
- 針對 UI/UX 工作： 將對話式 brainstorming 與 visual companion 結合，在寫任何 CSS 或元件程式碼之前，就先驗證版面與互動設計的想法。
你可以依現有 repository 調整資料夾路徑、命名與規格格式，但保持核心模式不變：context → questions → design/spec → review → implementation。
常見問題
brainstorming 技能只適合大型或複雜專案嗎？
不是。brainstorming 技能就是為了避免「這太簡單，不需要設計」這種反模式而設計。即便是一個小小的 config 變更或一次性的 utility，也可能藏著關鍵假設。對非常小的任務而言，設計內容也許只是一段精簡描述，但你仍然應該在實作前先把它說清楚並確認。
如果我已經有規格了，可以略過 brainstorming 嗎？
如果你已經有一份完整、最新且已核准的規格，不一定需要再跑一次完整的 brainstorming session。不過，你仍可以使用 spec-document-reviewer-prompt.md 中的規格審查 template，在實作前先對現有規格做一次驗證。如果審查結果顯示有缺漏或模糊之處，就再跑一輪較短的 brainstorming 來補齊。
brainstorming 要如何與實作類技能搭配？
brainstorming 技能是設計在任何實作技能之前使用。它會產出：
- 一份清楚且經使用者核准的設計
- 一份可被審查與反覆修訂的規格文件
只有在通過這個核准閘門之後，才應該啟動寫碼或重構類的技能。這種分工能讓設計意圖更明確，也減少實作過程中來回修正。
一定要用 visual companion 才能從 brainstorming 受益嗎？
不用。visual companion 是選用的。
- 如果你的工作多半是 backend 邏輯、API 或基礎設施，完全可以把 brainstorming 當成純文字的流程來用。
- 如果你做的是 UI/UX、產品設計或前端，搭配
visual-companion.md與scripts/目錄中的工具使用 visual companion，會更容易比較不同選項並收集回饋。
可以依照「視覺是否真的能讓對話更清楚」來決定要不要使用。
如果我無視這個嚴格閘門，直接開始寫程式會怎樣？
忽略嚴格的設計閘門，就等於放棄 brainstorming 的主要價值：在前期捕捉錯位與誤解。可能的結果包括：
- 做出來的功能與使用者期望不符
- UI 實作在收到回饋後需要大幅重做
- 規格落後於程式碼，變成一種文件債
請把這個閘門視為流程規則：在設計寫好、被檢視並明確核准之前，不要寫，也不要要求別人寫任何程式碼。
我可以自訂規格審查的評估標準嗎？
可以。spec-document-reviewer-prompt.md 已定義了幾個分類，例如完整性、一致性、清晰度、範圍及 YAGNI 考量。你可以在維持原本審查流程的前提下，依自己的領域調整這個 template（例如加入安全性、效能或法規遵循等檢查）。
brainstorming 是否綁定特定 framework 或技術堆疊？
不會。brainstorming 技能是與技術堆疊無關的。它專注在情境蒐集、需求釐清、設計表達與視覺探索，而不是特定 framework 的程式碼。你可以把它用在前端應用、後端服務、系統整合或混合型系統上。
我要如何解除安裝或停用 brainstorming 技能？
這個技能只是 obra/superpowers skill set 的一部分。要停止使用它，你可以：
- 在你的 agent 或 skills loader 設定中移除或註解掉相關設定
- 在工作流程與 pipeline 中停止呼叫它
brainstorming 技能本身不會對系統做任何全域修改，所以停用基本上只涉及設定和使用方式的調整。