OpenSpec + Superpowers 協作實戰：3 個銜接點斷了 2 個，無縫串聯翻車了（實戰版）

🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 101 篇，AI 編程最佳實戰「2026」系列第 26

大家好，歡迎來到 術哥無界 | ShugeX ｜ 運維有術。

我是術哥，一名專注於 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫的技術實踐者與開源佈道者！

Talk is cheap, let's explore。無界探索，有術而行。

圖 1：OpenSpec 與 Superpowers 協作全景

說明：本文內容基於 OpenSpec（Fission-AI/OpenSpec）和 Superpowers（obra/superpowers）的源碼分析及實際操作驗證。文中涉及的命令輸出、工具行為和銜接點測試結果均來自實測。文中的配置模板和參數建議僅供參考，實際效果請以你的業務數據和環境測試結果為準。如果有實際使用經驗，歡迎在評論區分享交流。

用 AI 編程助手寫代碼，跑偏是常態。功能做了一半發現方向不對，測試全綠但業務邏輯是錯的——這種事太多了。

問題不在 AI 本身。根源是寫代碼之前沒有把"要做什麼"說清楚。

Superpowers 提供了子代理驅動開發和 TDD 流程，看起來很完整。但翻一遍源碼就發現一個關鍵缺口：它的 spec reviewer 審查基準只是 plan 文件。plan 說"怎麼做"，不說"為什麼做"。沒有事先定義的規格文件，spec reviewer 就像沒有評分標準的裁判——能審，但審不準。

OpenSpec 產出的規格工件（proposal、specs、design、tasks）看起來能補上這個缺口。把規格餵給 Superpowers，讓審查有據可依——思路是對的，但實測下來，兩個工具的自動串聯並不成立。三個核心銜接點裏，兩個驗證失敗，一個根本沒觸發。

這篇文章記錄的是完整的實測過程：哪些跑通了，哪些斷裂了，以及為什麼。

1. 環境準備

你需要裝的東西

兩個工具，各有依賴。

Node.js 環境（OpenSpec 依賴）：

# 檢查 Node.js 版本，需要 >= 20.19.0
node --version

預期輸出類似 v20.19.0 或更高。低於這個版本，先去 Node.js 官網下載 LTS 版本升級。

版本確認沒問題後，全局安裝 OpenSpec CLI：

# 全局安裝 OpenSpec
npm install -g @fission-ai/openspec@latest

安裝完驗證一下：

# 驗證 OpenSpec 是否安裝成功
openspec --version

# 查看可用命令列表
openspec --help

✅ 看到版本號（實測 1.3.1）和命令列表，OpenSpec 就緒。

Superpowers 的安裝方式取決於你用的 AI 編程工具。源碼 README 列出了多個平台的支持。

Claude Code 用戶：

# 在 Claude Code 對話中執行
/plugin install superpowers@claude-plugins-official

安裝完成後，必須執行 reload 才能生效：

# 安裝後必須執行 reload 才能生效
/reload-plugins

實測安裝輸出 ✓ Installed superpowers，執行 reload 後 Superpowers 的 skill 才真正可用。

OpenCode 用戶：

訪問以下地址獲取安裝指令：

https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

其他平台（Cursor、Gemini CLI、OpenAI Codex）的安裝方式可參考 Superpowers 的 GitHub README。不同平台的安裝命令不同，但裝完後 Superpowers 的 skill 功能是通用的。

項目初始化

在項目根目錄執行：

# 進入項目目錄
cd your-project

# 初始化 OpenSpec（--tools 指定你的 AI 編程工具）
openspec init --tools claude
# 或支持多工具：openspec init --tools claude,cursor
# 或全裝：openspec init --tools all

裸跑 openspec init（不帶 --tools）會報錯 Error: No tools detected and no --tools flag provided。必須指定工具類型。

初始化後的目錄結構

openspec init 執行後，項目裏多出兩個目錄：

openspec/
├── specs/              # 主規格目錄（Source of Truth），初始為空
├── changes/            # 變更提案目錄
│   └── archive/        # 歸檔目錄
└── config.yaml         # 項目配置（需手動創建，可選）

.claude/
├── commands/opsx/      # OpenSpec 的 4 個 slash command
│   ├── propose.md
│   ├── apply.md
│   ├── archive.md
│   └── ...
└── skills/             # OpenSpec 的 4 個 skill
    ├── openspec-propose/
    ├── openspec-apply-change/
    ├── openspec-archive-change/
    └── ...

幾個要點：

• specs/ 初始為空，主規格在歸檔後才會出現內容
• changes/ 初始為空，執行 propose 後才生成變更目錄
• .claude/ 是 OpenSpec 在 Claude Code 中的運行載體：4 個 slash command 對應 propose、apply、archive 等操作，4 個 skill 提供對應的執行能力
• config.yaml 不會自動生成，需要手動創建（可選）

可選：配置技術棧

如果項目有特定的技術棧和規則，手動創建 openspec/config.yaml：

# openspec/config.yaml
schema: spec-driven
context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Vitest for unit tests
rules:
  proposal:
    - Include rollback plan

context 字段告訴 AI 你的技術棧，rules 約束每個工件的產出格式。實測中，rules 裏配置 specs: - Use Given/When/Then format for scenarios 並未被 AI 遵循——實際產出的場景格式是 WHEN/THEN（沒有 GIVEN）。如果你希望產出更結構化的場景描述，可以在 propose 時通過對話引導，但別指望 config.yaml 的 rules 來強制。

⏱️ 環境準備大約 5-10 分鐘。

2. 第一步：定義 Spec

這一步實測完全可行。/opsx:propose 一次性產出 proposal.md、specs/、design.md、tasks.md 四個工件。

執行 propose

在 AI 編程助手的對話窗口中執行：

/opsx:propose

執行後，AI 會問你想做什麼類型的變更。你可以這樣描述需求：

創建一個 Todo REST API。用 Express + TypeScript 實現，支持任務的增刪改查（CRUD），數據存內存數組即可。每個任務有 id、title、completed 三個字段。

OpenSpec 會自動從描述中推斷變更名（如 todo-rest-api），然後生成四個工件。

產出物：

• proposal.md — 鎖定意圖、範圍和方法
• specs/ — 增量規格，用 ADDED / MODIFIED / REMOVED 描述行為變更。裏面的場景格式是 WHEN/THEN（不是 GIVEN/WHEN/THEN）
• design.md — 技術設計方案，包含接口定義、數據結構和 Open Questions
• tasks.md — 實現任務清單，粗粒度的任務列表

檢查產出

# 查看當前所有活躍變更
openspec list

# 查看某個變更的 proposal 內容（輸出 proposal.md 全文）
openspec show <change-name>

# 查看工件狀態（JSON 格式，方便腳本處理）
openspec status --change <change-name> --json

openspec show 輸出的是 proposal.md 的完整內容，不是所有工件的彙總。如果想查看全部工件狀態，用 openspec status --change <name> --json。

驗證規格格式

# 驗證變更的規格格式是否合法
openspec validate <change-name>

實測輸出 Change 'todo-rest-api' is valid。✅ 驗證通過，4 個規格工件齊了。

工件之間的依賴關係

OpenSpec 的 4 個工件形成有向無環圖（DAG）：

            proposal（根節點）
                │
    ┌───────────┴───────────┐
    ▼                       ▼
  specs                  design
    │                       │
    └───────────┬───────────┘
                ▼
              tasks
                │
                ▼
            APPLY 執行

proposal 是根節點，定義了意圖；specs 和 design 都依賴 proposal，分別描述"系統應該怎麼表現"和"技術上怎麼實現"；tasks 同時依賴 specs 和 design，是最終的實現清單。

圖 2：OpenSpec 工件依賴關係圖（DAG）

關於 specs/ 裏的場景格式

這一步產出的 specs/ 目錄中，每個場景以 WHEN/THEN 格式描述業務行為。舉個例子：

#### Scenario: 成功創建任務
- **WHEN** 客戶端發送 POST /todos 請求，包含 `{ "title": "買牛奶" }`
- **THEN** 系統返回 201 狀態碼和任務對象

到這一步為止，OpenSpec 的活幹完了。propose 階段完全跑通，產出物質量不錯。 接下來看看把這套規格餵給 Superpowers 會發生什麼。

3. 第二步：Superpowers 閉環開發

這一步的目標：讓 Superpowers 讀取 OpenSpec 產出的工件，走完 brainstorming → writing-plans → subagent-driven-development 全流程。

實測下來，brainstorming 階段可以銜接，writing-plans 和 subagent 階段和 OpenSpec 的工件之間出現了斷裂。 逐個看。

3.1 Brainstorming：手動引導可銜接（✅ 可行）

在 AI 編程助手對話中觸發 Superpowers 的 brainstorming skill：

brainstorming

輸入後，AI 會問你想討論新項目還是重新設計。告訴它：

參考 openspec/changes/todo-rest-api/ 目錄下的 proposal.md 和 specs/ 中的增量規格作為討論基準，不要超出 proposal.md 定義的範圍。

這一步驗證有效——AI 確實讀取了 OpenSpec 工件，並基於 design.md 中的 Open Questions 發起了蘇格拉底式提問。比如：

（Q1: 是否需要時間戳？）需要加時間戳 

（Q2: 是否需要錯誤處理中間件？）需要

但有一個細節要注意：brainstorming 的產出保存在 docs/superpowers/specs/（Superpowers 自己的目錄），不是 OpenSpec 目錄。兩套目錄是獨立的，不會自動同步。

3.2 Writing Plans：不以 tasks.md 為骨架（❌ 斷裂點 1）

brainstorming 完成後，觸發 writing-plans：

writing-plans

輸入後，AI 會自動生成實現計劃，然後詢問選擇哪種執行方式。

但這裏出現了一個問題：即使你在 prompt 中引導"以 openspec/changes//tasks.md 為任務骨架"，writing-plans 仍會自行組織任務結構。實測中，OpenSpec tasks.md 定義了 4 組 11 個子任務，而 writing-plans 自行生成了 7 個任務，結構和粒度完全不同。

這意味着你面對的是兩套獨立的任務追蹤系統：

兩套系統不會自動同步。如果你在意 OpenSpec tasks.md 的完成度，得手動對照檢查。

3.3 Subagent-driven Development：流程正常，但審查基準不在 OpenSpec

這是 Superpowers 的核心機制。觸發子代理驅動開發：

subagent-driven-development

輸入後，流程全自動執行，無需額外交互。子代理的執行流程確實如源碼描述：

1. 讀取 plan，提取所有任務
2. 為每個任務分派實現者子代理
3. 實現者完成 → 分派規格合規審查子代理
4. 分派代碼質量審查子代理
5. 審查不通過 → 實現者修復 → 重新審查
6. 所有任務完成 → 分派最終代碼審查子代理

每個子代理完成後會報告狀態：

源碼中有幾個關鍵約束，別跳過：

• 不要在 main/master 分支直接實現，用獨立分支
• 不要跳過任何審查環節
• 不要在規格合規通過前啓動代碼質量審查
• 子代理不繼承主會話上下文，控制器提供完整信息

圖 3：子代理驅動開發審查流程

3.4 三個銜接點的實測結果

串聯的核心在三個地方。看看實測結果。

銜接點 1：spec reviewer 審的是 plan，不是 OpenSpec specs（❌ 斷裂）

源碼裏 spec reviewer 的設計意圖是對照規格審查實現。草稿原本寫的是"spec reviewer 以 OpenSpec specs/ 為審查基準"——但實測中，spec reviewer 審查的是 writing-plans 生成的 plan 文件中的代碼片段，從未引用過 OpenSpec specs/ 中的 WHEN/THEN 場景。

即使在 prompt 中引導 AI 參考 OpenSpec specs，spec reviewer 仍以 plan 為主。這意味着 OpenSpec 花大力氣產出的場景描述，在審查環節沒有被消費。

銜接點 2：specs/ → TDD 映射未實際觸發（⏳ 未驗證）

理論上，OpenSpec 的 WHEN/THEN 場景可以映射為 TDD 測試用例：

OpenSpec 場景：
- WHEN 客戶端發送 POST /todos 請求，包含 `{ "title": "買牛奶" }`
- THEN 系統返回 201 狀態碼和任務對象

→ 理論上映射為：
test('創建任務返回 201', ...)

但實際執行中，subagent-driven-development 沒有觸發 TDD skill，這個映射沒有發生。所以這只是一個理論上的可能路徑，沒有經過實際驗證。

銜接點 3：tasks.md → plan 的映射不成立（❌ 斷裂）

前面 3.2 節已經說了——writing-plans 有自己的任務組織邏輯，不會以 OpenSpec tasks.md 為骨架。plan 中每個步驟的驗收標準也不是來自 OpenSpec specs/。

圖 4：銜接點實測結果（4 可行 + 4 斷裂 + 1 未驗證）

你在項目中用過類似的子代理開發方案嗎？實測中遇到什麼問題？評論區聊聊。

4. 第三步：驗證和歸檔

這一步的目標：檢查實現成果，歸檔變更。

4.1 OpenSpec 側驗證

/opsx:apply

/opsx:apply 實際執行了 openspec status --json，看到 isComplete: true（含義是工件已創建）就直接判定完成。它不會讀 tasks.md、不會勾選 checkbox、不會對照任務清單檢查每個子任務的完成情況。

所以 apply 通過只說明四個文件存在，不代表實現完整。如果你用了 Superpowers subagent，apply 會結合對話上下文判斷（但這個判斷不可靠）。tasks.md 的完成情況需要你手動檢查。

# 查看工件狀態
openspec status --change <change-name> --json

4.2 Superpowers 側驗證

子代理開發完成後，確保觸發了 verification-before-completion skill。這個 skill 的核心原則是證據先於斷言——沒有實際運行測試的輸出截圖或日誌，不能聲稱"測試通過"。

代碼審查用 requesting-code-review skill 觸發。這個審查檢查代碼質量、測試覆蓋、命名規範等方面。

4.3 歸檔

驗證通過後，直接歸檔：

# 歸檔已完成的變更
openspec archive <change-name>

或者在 AI 助手中執行 /opsx:archive。

/opsx:archive 實際只做了一件事：把 changes/<change-name>/ 移動到 changes/archive/。增量規格不會自動合併到 openspec/specs/ 主目錄——歸檔後 openspec/specs/ 仍然是空的。如果你想更新主規格，需要手動操作。

另外，archive 也不會驗證 tasks.md 的完成度。實測中，11 個 tasks.md 任務都未勾選，但 archive 仍然報告"All tasks complete"。

完整流程一圖看懂

可行路徑：
  openspec init --tools claude        → ✅ 環境搭建
  /opsx:propose → 4 工件              → ✅ 規格產出質量不錯
  brainstorming（手動 prompt 引導）     → ✅ AI 能讀取 OpenSpec 工件
  subagent-driven-development          → ✅ 子代理流程正常運行

斷裂點：
  writing-plans 不以 tasks.md 為骨架   → ❌ 兩套任務追蹤系統
  spec reviewer 不讀 OpenSpec specs    → ❌ 審查基準是 plan 不是 specs
  /opsx:apply 不檢查 tasks.md         → ❌ 只看工件是否存在
  /opsx:archive 不 merge specs        → ❌ 主規格不更新

未驗證：
  specs/ WHEN/THEN → TDD 測試映射     → ⏳ subagent 未觸發 TDD

5. 故障排除

坑 1：子代理審查死循環

症狀：spec reviewer 和 code quality reviewer 都發現問題，實現者修復後重新提交，兩階段審查又發現問題。循環超過 3 輪還沒結束。

源碼依據：subagent-driven-development/SKILL.md 的 Red Flags 部分。

根因：規格不明確。審查者不知道"正確"的標準是什麼，實現者也不知道該修到什麼程度。

解決步驟：

1. 停下來，檢查 spec reviewer 的審查基準。當前它審的是 plan 文件，如果你有更明確的規格（比如 OpenSpec specs/），需要手動引導
2. 確認場景描述是否足夠具體——好的場景應該包含明確的操作動作（WHEN）和預期輸出（THEN）
3. 審查循環超過 3 輪，必須停下來。回到規格把場景改具體，再重新執行

判斷技巧：寫完 WHEN/THEN 後問自己——給一個完全不瞭解項目的人看這段描述，他能直接寫出正確的測試用例嗎？不能，就改到能為止。

坑 2：兩套追蹤系統脱節

症狀：OpenSpec tasks.md 的任務和 Superpowers plan 的任務對不上，apply 說完成了但 tasks.md 裏一堆未勾選。

根因：兩個工具各自維護任務清單，不會自動同步。

解決步驟：

1. writing-plans 執行後，手動對照 OpenSpec tasks.md 檢查一遍
2. 如果 plan 裏的任務和 tasks.md 差異較大，說明 AI 自行添加或跳過了任務
3. apply 聲稱的完成度不可靠，以你自己的檢查為準

坑 3：子代理頻繁報 NEEDS_CONTEXT

症狀：多個子代理返回 NEEDS_CONTEXT 或 BLOCKED，開發進度卡住。

源碼依據：implementer-prompt.md 明確說明子代理不繼承主會話上下文，控制器必須提供完整信息。

根因：傳給子代理的上下文不夠完整。

解決步驟：

1. 檢查 design.md 是否包含足夠的技術細節——接口定義、數據結構、錯誤處理策略、邊界條件
2. 檢查 specs/ 是否覆蓋了正常路徑和異常路徑
3. 在 config.yaml 的 context 字段補充項目背景信息

更新配置後，刷新 Agent 指令：

# 刷新 Agent 指令，使配置生效
openspec update

總結

實測一圈下來，OpenSpec 和 Superpowers 各自都是好工具，但自動串聯不成立。

可行的部分：OpenSpec 的 propose 流程（環境搭建 → 規格產出）完整可靠，4 個工件質量不錯。Superpowers 的子代理開發流程也能正常運行。brainstorming 階段通過手動 prompt 引導，AI 確實能讀取 OpenSpec 工件。

斷裂的部分：writing-plans 不以 OpenSpec tasks.md 為骨架，spec reviewer 不讀 OpenSpec specs，apply 不檢查任務完成度，archive 不合並增量規格。四個斷裂點疊加起來，意味着你心目中"OpenSpec 定義規格 → Superpowers 按規格執行"的流水線，實際上需要大量手動對齊。

如果你只取各自獨立的價值：用 OpenSpec 做需求定義和規格產出，用 Superpowers 做子代理開發——分開用，都是趁手的工具。但別指望它們自動串聯成一條無縫的規格驅動開發流水線。至少目前不行。

補充一句：本次實測用的是 MiniMax 2.7 模型，整體效果不如 GLM 5.1，但勝在性價比，日常湊合用沒問題。算是買不到 GLM 時的一個平替方案。如果你也想試試，可以用這個連結購買，比官網直購便宜 10%：https://platform.minimaxi.com/subscribe/token-plan?code=8nzRbxE4m1&source=link

你身邊有同事也在用 AI 編程助手做開發？轉發給他們看看這個實測結果。關於 AI 工具協作，你踩過什麼坑？評論區聊聊。

好啦，謝謝你觀看我的文章，如果喜歡可以點贊轉發給需要的朋友，我們下一期再見！敬請期待！

掃碼關注，獲取更多 AI 工具的實戰經驗和最佳實踐。不錯過每一篇乾貨！