OpenSpec管"做什麼"，Superpowers管"怎麼做"。裝了不會配合？我用一個真實項目走完流程，踩過的坑你不用再踩
寫在前面
你可能已經讀過這兩篇文章：
一篇講Superpowers——14個工作流Skill讓AI編程助手守規矩。
一篇講OpenSpec——規範驅動開發，讓AI不再憑感覺寫代碼。
但你裝了兩個框架之後，大概率會遇到這些問題：
OpenSpec生成了規範文檔，Superpowers的brainstorming又開始問需求，兩個在重複勞動。
Superpowers的TDD說"先寫測試"，OpenSpec的tasks.md裏已經列好了實現步驟，AI該聽誰的。
用了一段時間發現：OpenSpec管好了"做什麼"，但AI實現的時候還是亂寫代碼；Superpowers管好了"怎麼做"，但做出來的東西和需求對不上。
這兩個框架不是替代關係，是互補關係。 OpenSpec解決"做什麼"，Superpowers解決"怎麼做"。但它們不會自動配合——你需要一個銜接層。
OpenSpec是Fission-AI開發的開源SDD框架，核心理念是"規範是source of truth，代碼是規範的派生產物"——在AI寫代碼之前，先對齊"做什麼"和"技術方案選型"。它專門為已有代碼庫的項目設計，通過增量規範（delta spec）描述變更而非重寫整個規範。Superpowers是Jesse Vincent開發的工作流框架，140,000+ GitHub星標，核心理念是"給AI可組合的Skill工作流，而不是模糊的建議"。一個管方向，一個管執行。
這篇文章，我用一個真實項目走一遍完整流程：給一個已有的Go微服務添加JWT認證。不是從零開始，而是在已有的代碼和規範上疊加新功能——這是最常見的開發場景。我會把每一步的輸入輸出、踩坑和調整都寫出來。
一、先搞清楚分工：誰管什麼
很多人把OpenSpec和Superpowers搞混，以為它們是競爭關係。實際上它們解決的是完全不同的問題：
| | |
|---|
| | |
| proposal.md、specs、design.md、tasks.md | |
| | |
| | |
| | |
一句話總結：OpenSpec確保方向對，Superpowers確保執行對。
缺少任何一個會怎樣？
只有OpenSpec：規範寫得好好的，AI實現時跳測試、不做審查、一次性提交500行——規範對了但代碼質量爛只有Superpowers：TDD做得好、審查做得好，但做出來的東西和需求對不上——代碼質量好了但方向錯了二、完整實戰：給Go微服務添加JWT認證
場景設定
項目背景：
第1步：OpenSpec explore — 先搞清楚方向
不要上來就propose。先explore，和AI討論技術方案。
/opsx:explore
你和AI的對話：
你：我們需要給移動端加JWT認證
AI：讓我看看現有的認證方案……你目前用的是session認證，存在服務端內存裏。JWT認證有三種方案：
你：用JWT + 黑名單吧，需要能主動踢人
AI：好。另外幾個問題：token過期時間？刷新token要不要？黑名單存哪？
你：30分鐘過期，要刷新token，黑名單用Redis
AI：明確了。運行 /opsx:propose add-jwt-auth 開始
踩坑1：直接propose不explore。 我第一次用時跳過了explore，結果AI生成的proposal選了純JWT方案，沒有黑名單，和需求對不上。來回改了3次。explore花5分鐘，省了30分鐘的返工。（explore的詳細用法和適用場景，之前講OpenSpec的文章已經展開過，這裏不重複。）
第2步：OpenSpec propose — 生成規範文檔
/opsx:propose add-jwt-auth
AI生成4個文檔：
proposal.md — 為什麼要做，範圍是什麼：
# 提案：添加JWT認證
## 動機
移動端無法使用session認證，需要無狀態token方案。
## 範圍
- 添加JWT簽發和驗證
- 添加刷新token機制
- 添加token黑名單（Redis）
- 修改登錄接口返回token
## 排除範圍
- 不修改現有session認證邏輯
- 不修改前端Web端代碼
- 不添加OAuth2第三方登錄
- 不修改數據庫用戶表結構
踩坑2：proposal的"排除範圍"寫得不夠細。 我第一次寫的時候沒寫"不修改前端Web端代碼"，AI在實現的時候順手把Web端的登錄也改了。加上排除範圍後，AI就像有了圍欄，不會"好心"幫你多做。（"不做什麼比做什麼更重要"這個原則之前講OpenSpec時詳細說過，這裏強調的是：和Superpowers組合使用時，排除範圍還會被spec-compliance-check Skill引用，寫不寫直接影響審查能不能抓到違規。）
specs/ — 增量規範：
# 新增需求
## 需求：JWT簽發
系統MUST在用戶登錄成功後簽發access token和refresh token。
### 場景：有效憑證登錄
- 假設 用戶持有有效的用戶名和密碼
- 當 用戶提交登錄請求
- 則 返回access token（30分鐘過期）和refresh token（7天過期）
- 且 返回格式包含三個字段：
- access_token：訪問令牌
- refresh_token：刷新令牌
- expires_in：過期時間（秒）
### 場景：無效憑證登錄
- 假設 用戶持有無效憑證
- 當 用戶提交登錄請求
- 則 返回401狀態碼
- 且 不簽發任何token
## 修改需求
## 刪除需求
design.md — 技術方案：
# 設計方案：添加JWT認證
## 技術方案
使用golang-jwt庫簽發和驗證token。中間件模式攔截請求，
驗證Authorization頭。黑名單使用Redis SET存儲已失效的token。
## 架構決策
- access token 30分鐘過期，refresh token 7天過期
- 黑名單用Redis SET，key為jti（JWT ID），TTL等於token剩餘有效期
- 中間件模式，不修改現有路由註冊邏輯
- 刷新token時輪換（refresh token用一次就失效，簽發新的）
tasks.md — 實現步驟：
# 任務清單
- [ ] 1.1 添加JWT依賴（golang-jwt）
- [ ] 1.2 定義token結構和常量
- [ ] 2.1 實現JWT簽發函數
- [ ] 2.2 實現JWT驗證函數
- [ ] 3.1 實現Redis黑名單
- [ ] 3.2 實現token失效邏輯
- [ ] 4.1 實現認證中間件
- [ ] 4.2 修改登錄接口返回token
- [ ] 5.1 實現刷新token接口
- [ ] 5.2 實現刷新token輪換
踩坑3：tasks.md的粒度和Superpowers的plan不匹配。 OpenSpec的tasks是需求視角的拆分，Superpowers的plan是實現視角的拆分：
OpenSpec的task: "實現JWT簽發函數"——說什麼Superpowers的plan: "1.寫失敗測試 2.運行測試 3.寫最小實現 4.運行測試 5.提交"——怎麼做這兩個不矛盾，但需要正確銜接——後面第4步會講。
第3步：審核規範文檔
這一步沒有框架幫你，必須你自己做。
審核清單：
specs的場景是否覆蓋了邊界情況（token過期、token被黑名單、併發刷新）tasks.md是否遺漏了步驟（安全測試、性能測試）我發現的問題： specs裏沒有覆蓋"併發刷新同一個refresh token"的場景。這是一個安全漏洞——如果攻擊者拿到refresh token，可以在原用戶刷新的同時也刷新，獲得多個有效token。我補充了這個場景：
### 場景：併發刷新
- 假設 同一個refresh token被同時使用兩次
- 當 第二次使用該refresh token
- 則 返回401狀態碼
- 且 原refresh token被加入黑名單
第4步：關鍵銜接——讓兩個框架聽同一個指揮
這是整篇文章最關鍵的一步，也是兩個框架的"斷層"所在。
問題在哪？ OpenSpec的tasks.md告訴你"做什麼"，但不說"怎麼做"。Superpowers的writing-plans告訴你"怎麼做"，但不知道"做什麼"。兩個框架各管一段，中間缺了銜接。
還有一個容易忽略的問題：OpenSpec的apply去哪了？ OpenSpec自己的流程是explore、propose、apply、sync、archive，apply是讓AI按照tasks.md實現代碼。但如果你用Superpowers來執行，apply這一步就被Superpowers的TDD流程替代了——Superpowers做得更好，因為它有測試紀律、代碼審查、驗證機制。
所以聯合工作流中，跳過OpenSpec的apply，用Superpowers的執行流程替代。 跳過apply後，tasks.md中的勾選狀態需要手動更新（每完成一個task，在tasks.md中把- [ ]改為- [x]），或者通過openspec-superpowers-bridge Skill自動更新。
怎麼銜接？ 把OpenSpec的產物餵給Superpowers：
把OpenSpec生成的design.md和specs/作為上下文告訴AI："基於OpenSpec的tasks.md，用Superpowers的planning流程拆成可執行的計劃"Superpowers會把每個task拆成TDD步驟具體操作： 如果你用Claude Code，在對話中輸入：
請閲讀以下OpenSpec規範文檔，然後基於這些規範使用Superpowers的
writing-plans流程拆分實現計劃：
1. 讀取 openspec/changes/add-jwt-auth/design.md 作為技術方案
2. 讀取 openspec/changes/add-jwt-auth/specs/ 下的所有場景作為測試依據
3. 讀取 openspec/changes/add-jwt-auth/tasks.md 作為任務列表
4. 讀取 openspec/changes/add-jwt-auth/proposal.md 的排除範圍作為審查依據
每個task拆成Superpowers plan的粒度：
1. 寫失敗測試
2. 運行測試
3. 寫最小實現
4. 運行測試
5. 重構
6. 提交
如果你用Cursor或其他工具，打開這些文件讓AI讀取後，再執行/superpowers:writing-plans。
粒度轉換示例： AI會把OpenSpec的task 2.1"實現JWT簽發函數"拆成：
寫失敗測試：TestJWTSign_ValidCredentials_ReturnsToken運行測試，確認失敗（undefined: SignToken）寫最小實現：func SignToken(userID string, expiry time.Duration) (string, error)踩坑4：直接讓Superpowers開始實現，不喂OpenSpec的規範。 如果不把specs和design.md給Superpowers，AI會按自己的理解實現，可能和OpenSpec對齊的方案不一致。比如design.md決定用Redis SET存黑名單，AI可能自己選了內存map。銜接的關鍵：把OpenSpec的design.md作為Superpowers brainstorming的輸入。
另一個容易踩的坑：brainstorming和explore重複勞動。 OpenSpec的explore已經討論過需求和技術方案了，Superpowers的brainstorming又會重新問一遍。解法：如果OpenSpec的explore和propose已經完成，跳過Superpowers的brainstorming階段，直接進入planning階段。把proposal.md和design.md作為brainstorming的等效輸出。
如果你已經跑了apply怎麼辦？ apply會讓AI直接按tasks.md實現代碼，但實現過程沒有TDD、沒有代碼審查、沒有驗證機制。兩種處理方式：
如果apply生成的代碼可以用，保留代碼，但後續每個task補上Superpowers的代碼審查和verify如果apply生成的代碼質量不行，用git reset回退，重新用Superpowers的TDD流程實現第5步：Superpowers執行 — TDD實現每個task
這一步完全交給Superpowers的紀律流程。每個task走：
派新代理實現（subagent-driven-development）代理內部走TDD（test-driven-development）踩坑5：審查代理沒有OpenSpec的規範上下文。 Superpowers的代碼審查默認只看代碼質量（由requesting-code-review Skill觸發，自動派一個全新代理審查），不檢查實現是否和OpenSpec的規範一致。我寫了一個自定義Skill來解決這個問題：
---
name: spec-compliance-check
description: Use when 完成代碼實現後，在代碼審查之前，檢查實現是否符合OpenSpec規範
---
# 規範合規審查
## 鐵律
任何實現必須與openspec/specs/中的規範一致。不一致就是bug。
## 審查步驟
1. 讀取 openspec/specs/ 下的主規範（檢查本次實現是否違反了已有需求）
2. 讀取本次變更對應的openspec/changes/下的delta規範
3. 逐條檢查每個"假設/當/則"場景是否有對應實現
4. 檢查design.md中提到的架構決策是否被遵守
5. 檢查proposal.md的排除範圍是否被違反
## 常見問題
- "AI順手多改了代碼"：檢查排除範圍
- "實現方式和design.md不一致"：這是bug，不是優化
- "場景沒有覆蓋"：測試不完整
這個Skill的關鍵在於：它把OpenSpec的規範文檔變成了Superpowers審查流程的一部分。 沒有這個Skill，審查代理只看代碼質量，不看規範合規。
第6步：OpenSpec verify — 驗證實現和規範的一致性
每個task完成後，Superpowers會做代碼審查。但代碼審查通過不等於規範合規。
/opsx:verify
（注：verify屬於OpenSpec的擴展工作流，需要通過openspec config profile切換到擴展配置才能使用。）
verify從三個維度檢查：
| | |
|---|
| | Superpowers審查看代碼，verify看規範 |
| | Superpowers審查看質量，verify看語義 |
| | |
實測發現的問題： verify發現task 4.1"實現認證中間件"的實現用了內存map存黑名單，和design.md的Redis方案不一致。代碼審查沒發現這個問題，因為代碼本身質量沒問題——只是和規範不一致。spec-compliance-check Skill也沒抓到，因為這個task是在安裝Skill之前實現的。
踩坑6：verify和代碼審查二選一。 兩個都要做。代碼審查看質量，verify看合規。它們檢查的東西不一樣，互補不替代。代碼審查關注"代碼寫得好不好"（命名、結構、錯誤處理），verify關注"代碼做了該做的事嗎"（規範合規、場景覆蓋、架構一致）。一個代碼質量滿分但和規範不一致的實現，代碼審查會通過，verify不會。正確順序：
代碼質量審查（Superpowers的requesting-code-review Skill自動派一個全新代理審查）規範合規審查（spec-compliance-check Skill）OpenSpec verify（從規範維度全面驗證）先確保代碼寫得對，再確保代碼和規範一致，最後從規範維度全面驗證。
第7步：OpenSpec archive — 歸檔並更新主規範
所有task完成，verify通過後：
/opsx:archive
兩件事：
把delta specs合併到主規範（openspec/specs/auth/spec.md更新了JWT認證的需求）歸檔的意義： 下次加功能時，AI讀到的主規範已經包含了JWT認證的信息。不會出現"AI不知道項目已經有JWT認證，又實現了一套session認證"的問題。
踩坑7：歸檔前沒跑全量測試。 我有一次在verify通過後直接archive，結果後來發現verify只檢查了規範合規，沒跑測試套件。Superpowers的verification-before-completion要求"跑過命令才能說搞定了"，但OpenSpec的archive沒有這個檢查。我的做法：在archive之前，加一步Superpowers的verification。 具體來說，按項目類型跑全量測試：Go項目用go test ./...，Node.js項目用npm test，Python項目用pytest。或者直接觸發Superpowers的verification-before-completion Skill，它會要求你提供當前對話中運行的測試結果。
第8步：Superpowers收尾
驗證通過後，finishing-a-development-branch給你4個選項：
測試不過不能合併——這條鐵律保底。
三、完整流程一覽
把8步串起來，完整的聯合工作流：
需求階段（OpenSpec主導）：
explore — 和AI討論技術方案（5-10分鐘）propose — 生成proposal、specs、design、tasks（10-15分鐘）人工審核 — 檢查規範文檔的完整性（5-10分鐘）銜接階段（你主導）：
喂上下文 — 把OpenSpec的design.md和specs給Superpowers，讓planning基於規範拆分（跳過OpenSpec的apply，用Superpowers替代）實現階段（Superpowers主導）：
TDD實現 — 每個task走RED-GREEN-REFACTOR循環驗證階段（兩者配合）：
OpenSpec verify + Superpowers verification — 先跑測試確保代碼能工作，再跑verify確保實現和規範一致OpenSpec archive + Superpowers收尾 — 歸檔更新主規範，合併或創建PR核心原則：OpenSpec的產物是Superpowers的輸入，Superpowers的輸出是OpenSpec驗證的對象。
當流程出問題時怎麼辦？
verify不通過 — 回到對應的task，用Superpowers的systematic-debugging找根因，修復後重新跑verifyspec-compliance-check發現不合規 — 先判斷是代碼錯了還是規範過時了：代碼錯了就修代碼，規範過時了就修改design.md並重新跑proposedesign.md的決策不合理 — 回到第3步人工審核，修改design.md，然後重新走銜接層讓Superpowers基於新方案規劃tasks.md粒度太粗或太細 — 粗粒度task會被Superpowers的planning自動拆細，細粒度task可以在銜接時合併（相鄰的task 1.1和1.2合併為一個plan task）實現過程中需要修改規範 — 先暫停Superpowers的執行，回到OpenSpec修改design.md（必要時重跑propose），修改後的delta specs需要重新審核，然後重新走銜接層讓Superpowers基於新方案規劃。已完成的task如果不受影響則保留，受影響的task需要用Superpowers的systematic-debugging評估影響範圍並修改。如果只是微調而不需要重新propose，可以用/opsx:sync把變更中的delta specs同步到主規範，無需歸檔多個變更並行推進 — 每個變更用獨立的git worktree開發，每個worktree裏只有一個OpenSpec變更在推進。Superpowers的dispatching-parallel-agents可以在不同worktree上並行工作，但不要在同一個worktree上同時推進多個OpenSpec變更，否則spec-compliance-check會混淆不同變更的規範邊界四、7個坑的完整清單
| | | |
|---|
| | | |
| | | |
| | OpenSpec說"做什麼"，Superpowers說"怎麼做" | |
| | | 把design.md餵給brainstorming |
| | | 自定義spec-compliance-check Skill |
| | | |
| | | archive前加Superpowers的verification |
五、自定義Skill：讓兩個框架自動配合
上面7個坑，有5個可以通過自定義Skill自動解決。我寫了一個銜接Skill：
把這兩個Skill放在Claude Code的Skills目錄下：
~/.claude/skills/spec-compliance-check/SKILL.md~/.claude/skills/openspec-superpowers-bridge/SKILL.md如果你用Cursor，放在.cursor/rules/目錄下。
---
name: openspec-superpowers-bridge
description: Use when 開始實現OpenSpec的tasks，在brainstorming和planning之前自動加載。當用戶說"開始實現"、"apply tasks"或提到OpenSpec變更時觸發
---
# OpenSpec-Superpowers銜接規範
## 鐵律
實現任何OpenSpec task之前，必須先加載對應的規範文檔。沒有規範上下文的實現就是盲寫代碼。
## 執行步驟
1. 讀取 openspec/specs/ 下的主規範（瞭解已有約束）和 openspec/changes/ 下最新的未歸檔變更目錄中的所有文檔（如果不確定當前變更目錄，運行 `ls openspec/changes/` 查看未歸檔的變更文件夾。如果只有一個，那就是當前變更。如果有多個，詢問用戶確認）
2. 如果OpenSpec的explore和propose已經完成，跳過Superpowers的brainstorming階段，直接進入planning階段
3. 把 design.md 作為 Superpowers planning 的輸入
4. 把 specs/ 中的場景轉換為 TDD 測試用例
5. 把 tasks.md 中的每個任務拆成 Superpowers plan 的粒度
6. 每個任務完成後，用 spec-compliance-check 審查規範合規
7. 全部任務完成後，運行 /opsx:verify
8. verify 通過後，運行 Superpowers verification（跑測試命令）
9. 兩個驗證都通過，才能 /opsx:archive
## 場景到測試的轉換規則
OpenSpec的"假設/當/則"場景映射為測試用例，每個場景至少需要兩個測試：
1. 正常路徑測試：假設對應setup，當對應action，則對應assertion
2. 錯誤路徑測試：假設對應異常條件，當對應action，則對應錯誤assertion
3. 邊界值測試：如果場景涉及數值、時間等邊界，額外添加
## 審查的雙重檢查
每次代碼審查必須包含兩個維度：
1. 代碼質量（Superpowers默認審查）
2. 規範合規（spec-compliance-check Skill）
## 常見問題
- "AI沒讀design.md就實現了"：檢查銜接Skill是否觸發
- "tasks粒度太粗"：自動拆成TDD步驟
- "verify通過了但測試沒跑"：archive前強制跑測試
這個Skill直接解決了7個坑中的5個：
自動加載規範上下文 — 解決坑4（實現方式和design.md不一致）跳過brainstorming避免重複 — 解決explore和brainstorming重複勞動的問題場景轉測試用例 — 解決坑3（tasks和plan粒度不匹配），讓OpenSpec的規範直接變成Superpowers TDD的輸入雙重驗證 — 解決坑6（verify和代碼審查二選一）和坑7（archive前沒跑測試）spec-compliance-check — 解決坑5（審查不檢查規範合規）未自動解決的：坑1（需要人先explore）和坑2（需要人寫排除範圍），這兩個需要人在流程中主動把關。
六、什麼時候該用哪個
不是所有項目都需要兩個框架一起上。
只用OpenSpec就夠了：
只用Superpowers就夠了：
需求明確但不需要長期規範的小功能（比如寫個數據遷移腳本）兩個都用：
團隊協作的項目（規範保證方向一致，紀律保證質量一致）長期維護的項目（規範隨項目增長，紀律保證代碼質量不退化）複雜功能開發（設計階段防止方向錯，TDD防止實現錯）已有代碼庫的項目（現有代碼+新功能，規範防止AI"好心"多改，紀律防止AI偷懶跳步）判斷標準：代碼要活多久 + 有多少人碰代碼。 活1天1個人碰，兩個都不用。活1個月3個人碰，兩個都用。
從單框架過渡到雙框架：
如果你已經在用OpenSpec：在下一個新功能中加入Superpowers的TDD和代碼審查，不需要一次用上全部14個Skill，先加3條鐵律（沒設計不寫代碼、沒測試不寫代碼、沒驗證不說完成）如果你已經在用Superpowers：在下一個複雜功能前先用OpenSpec的explore和propose生成規範文檔，不需要一次用上完整流程，先加規範對齊這一步七、效果對比：4種組合的數據一覽
用同一個項目（Go微服務添加JWT認證）做對比（以下數據來自作者個人經驗，僅供參考）：
兩個框架組合的最大價值不是各自的價值相加，是消除"方向對了但做錯了"和"做對了但方向錯了"這兩個最常見的失敗模式。
數據說明： "AI多做功能"這行，Superpowers比"兩個都不用"好，是因為brainstorming階段會問清楚需求邊界；但Superpowers沒有排除範圍機制，所以AI還是可能"好心"多做。加了OpenSpec的排除範圍後，spec-compliance-check能自動檢測違規，所以能到0次。返工次數指因方向錯誤或質量不達標需要返工的次數，不含正常的小調整。
寫在最後
OpenSpec和Superpowers的組合，本質上是給AI編程加了兩個維度的約束：
橫向約束（OpenSpec）：AI做的事情和你的需求一致縱向約束（Superpowers）：AI做事情的方式符合工程標準沒有橫向約束，AI可能做出一個完美但不需要的功能。沒有縱向約束，AI可能做出一個需要但質量不合格的功能。
兩個約束都有，才是真正的"對的事情，用對的方式做出來"。
3條起步規則：
先explore再propose——別讓AI猜需求把design.md餵給Superpowers——別讓AI猜方案3分鐘上手
兩個框架都裝好後，按這個順序走你的第一個聯合任務：
審核四份文檔（proposal、specs、design、tasks）對AI說："讀取 openspec/changes/ 目錄下的規範，用Superpowers的writing-plans拆計劃"每個task完成後：代碼審查、spec-compliance-check、/opsx:verify跑全量測試（go test ./... 或項目對應命令）/opsx:archive Superpowers收尾合併第4步是關鍵——如果你只記住一件事，記住這個：把OpenSpec的規範文檔餵給Superpowers，不要讓Superpowers空手上陣。
掃碼關注「AI智聞說」，每天3分鐘掌握AI新知識
