OpenSpec + Superpowers：一個管寫什麼，一個管怎麼做，6 步實現 AI 規格驅動 TDD 開發（實戰版）
整理版優先睇
OpenSpec 管規格，Superpowers 管執行，組合出 TDD 完整工作流
呢篇文章係術哥（ShugeX）嘅實戰分享，佢係專注AI編程同開源技術嘅實踐者。佢發現好多人用AI編程助手時，成日遇到需求模糊導致AI自由發揮，然後要不斷改嘅循環。佢想解決嘅問題係：點樣令AI準確跟住規格嚟寫代碼，而且每個步驟都係可驗證嘅。佢嘅結論係：用OpenSpec管「寫咩」，Superpowers管「點樣做」，中間用schema.yaml嘅指令做橋樑，就可以實現完整嘅TDD自動化工作流。
術哥分享咗三次迭代嘅經驗。v1完全失敗，因為任務粒度唔夠細，RED同GREEN混埋一齊。v2設計咗4層防護，包括原子化任務、subagent隔離等，喺Mini Markdown項目實測3/4通過。v3將經驗沉澱成可複用嘅中文版Schema，用Todo API項目完整跑通咗propose→apply→archive全流程。
成個方案嘅核心係分工：OpenSpec負責propose階段，生成proposal、specs、design、tasks、plan；Superpowers負責apply階段，用subagent-driven-development原子化執行每個TDD任務。實測12個task耗時約1小時4分鐘，換嚟13個測試全過同95.38%覆蓋率。術哥認為呢個方案用時間換質量，適合追求工程化嘅場景，唔適合趕進度嘅原型開發。
- OpenSpec同Superpowers互補，一個管規格定義，一個管TDD執行，覆蓋需求到實現嘅完整鏈路。
- 成功關鍵係原子化任務：每個task只對應一個TDD階段（RED/GREEN/REFACTOR），禁止RED+GREEN混合。
- v3比v2嘅改進包括：中文Schema、更誠實時間預期、具體化已知問題，同埋完整跑通propose→apply→archive。
- 呢個方案用流程紀律換代碼質量：一個中等功能等1小時，但可達95%+測試覆蓋率同完整變更追溯。
- 實戰行動點：配置一次TDD Schema可複用，propose後一定要人工審查tasks.md確保原子化，apply後要逐個task確認審查完成。
點解要呢兩個工具夾埋用
單用OpenSpec，你可以清楚管好需求——proposal、design、specs、tasks一條龍生成，但去到執行階段，佢只係逐個勾選task，冇TDD強制，冇子代理隔離，亦冇自動審查。AI一步完成成個功能係完全合理，因為一個task可能包含RED同GREEN嘅混合內容。
單獨用Superpowers，TDD紀律好嚴——RED-GREEN-REFACTOR強制循環，子代理隔離執行，兩階段自動審查。但係Superpowers冇spec管理，冇變更追溯，需求全靠對話，換個會話就唔記得。
所以佢哋嘅互補關係好清楚：一個管「寫咩」，一個管「點樣做」，組合埋剛好覆蓋由需求到實現嘅完整鏈路。
v1到v3嘅演進教訓
術哥經歷咗三次迭代，每次都有具體教訓。
- 1 v1完全失敗：任務粒度唔啱（一個task包含完整功能），兩套追蹤系統互不引用，審查審嘅唔係OpenSpec specs。
- 2 v2 4層防護：原子化tasks.md、apply instruction寫死subagent-driven-development、config.yaml context充分、驗證證據。實測3/4通過，但審查只覆蓋前2/26個task。
- 3 v3三個改進：中文版Schema、更誠實時間預期（12個task約1小時4分鐘）、具體化已知問題（Task 8同10被跳過）。
原子化任務係v1到v3最關鍵嘅改變——每個task只能係一個TDD階段，物理約束AI嘅操作空間。
6步實戰流程
成個方案分6步：初始化項目 → 建立TDD Schema → 執行propose → 人工審查 → 執行apply → 人工驗收同歸檔。
Step 1同2係一次性配置，之後每次新功能都可以複用。
Step 2係最關鍵嘅部分，要手動建立schema.yaml、config.yaml同5個模板檔案。schema.yaml定義咗5個artifact（proposal、specs、design、tasks、plans）各自嘅instruction，config.yaml注入項目上下文。
apply:
requires: [plans]
tracks: tasks.md
instruction: |
必須使用 superpowers:subagent-driven-development skill 執行。
禁止使用 executing-plans 或 inline 執行。
執行規則：
1.每個任務是一個原子TDD階段——每個任務派遣一個子代理
2.禁止並行派遣多個實現子代理
3.任務必須按順序執行
每個子代理的證據要求：
-RED任務：必須包含測試失敗輸出
-GREEN任務：必須包含測試通過輸出- propose後一定要人工審查tasks.md：檢查每個task係咪得一個TDD階段，RED同GREEN有冇嚴格交替。
- apply階段用subagent-driven-development，實測12個task要34次子代理調用，約1小時4分鐘。
- apply完成後人工驗收：npm test全部通過，tasks.md所有checkbox已勾選，測試覆蓋率達標。
- 歸檔用 /opsx:archive，會自動加日期前綴搬去 openspec/changes/archive/。
apply期間唔好中斷，否則恢復好麻煩。建議確認網絡穩定同有足夠時間先開始。
已知侷限同應對方法
術哥坦承呢個方案唔係銀彈，實測發現6個已知問題，需要喺人工驗收階段兜底。
- 1 部分task跳過審查：Task 8同10被跳過，應對係apply後對照日誌逐個確認審查報告。
- 2 測試覆蓋率可能不足：15個行為只覆蓋10個，要對照proposal.md嘅WHEN/THEN列表補返。
- 3 AI可能自行調整文件結構：design.md規劃兩個文件，AI合併成一個，判斷偏離是否合理。
- 4 apply階段唔會自動git commit：結束後手動 git add/commit。
- 5 執行時間與需求複雜度不成比例：流程紀律開銷係系統性，即使簡單需求都要三輪子代理。
- 6 子代理模式下code review可能遺漏接口不一致：特別檢查跨文件嘅type/interface定義。
適用場景同進階技巧
呢個方案最適合純函數庫、REST API、CLI工具呢類行為清晰嘅項目。前端UI組件、依賴外部服務嘅功能、時間緊迫嘅原型就唔太啱用。
一次配好TDD Schema，新項目只要複製 openspec/schemas/tdd-driven-v2/ 同 openspec/config.yaml，改context就得。
config.yaml嘅context寫得越詳細，propose階段全自動率越高。核心函數簽名、輸入輸出類型、已有工具函數列表呢啲資訊，可以幫AI一次生成正確proposal。
propose後嘅5分鐘人工審查ROI好高，特別係tasks.md，一錯就會令成個apply跑偏。
OpenSpec + Superpowers：一個管寫乜，一個管點樣做，6 步實現 AI 規格驅動 TDD 開發（實戰版）
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 104 篇，AI 編程最佳實戰「2026」系列第 29
大家好，歡迎嚟到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一個專注於 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫嘅技術實踐者同開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
用 AI 編程助手寫代碼，好多人踩過同一個坑：代碼跑得起，但唔係你想要嘅。
問題出喺邊？唔係 AI 能力唔夠，係你無話畀佢知寫乜、點樣寫先至啱。需求模糊 → AI 自由發揮 → 你不斷改，呢個循環吞噬咗大量時間。
呢篇文章係 OpenSpec + Superpowers TDD 協作方案嘅第三次嘗試（v3），亦係第一次完整跑通 propose → apply → archive 全流程嘅版本。
前兩版嘅故事係咁：
v1 完全失敗。 apply 階段 AI 一次過寫曬所有代碼，跳過咗 RED 階段，測試係寫完實現之後先補嘅。TDD 形同虛設。失敗根因唔係 instruction 措辭，而係任務粒度——一個 task 包含完整功能（RED+GREEN 混合），AI 一步完成係合理嘅。
v2 設計咗 4 層防護。 原子化任務 + subagent 隔離 + 兩階段審查 + 驗證證據，喺 Mini Markdown 項目上拆咗 26 個原子任務，dispatch 咗 27 次 subagent，3 層通過、1 層被 AI 跳過。v2 證明咗原子化任務同 subagent 隔離係有效，但審查覆蓋唔完整（淨係前 2/26 task 有審查），測試覆蓋率 10/15，架構決策偏離 design.md。（詳見上一篇：[《OpenSpec + Superpowers TDD v2：4 層防護疊加 26 個原子任務，27 次 subagent 實測 3/4 通過》]）
v3 做咗三個關鍵修正：將 v2 嘅 4 層防護經驗沉澱成一套可重用嘅中文版 Schema，補充咗 propose 支援自然語言輸入、archive 嘅日期前綴歸檔路徑、以及更誠實嘅時間預期（實測 12 個 task 耗時 1 小時 4 分鐘）。呢一版用 Todo API 項目做驗證，完整跑通咗 6 個步驟：初始化 → 創建 Schema → propose → apply → 人工驗收 → archive。
用一句話概括方案核心：OpenSpec 管「寫乜」，Superpowers 管「點樣做」，橋樑係 schema.yaml 裏面嘅 instruction 文本。
說明：本文內容基於 OpenSpec（Fission-AI/OpenSpec）同 Superpowers（obra/superpowers）嘅源碼分析、官方文檔同三日兩次實戰驗證。v2 喺 Mini Markdown 項目驗證（26 個 task、27 次子代理調用、10/10 測試通過），v3 喺 Todo API 項目驗證（12 個 task、34 次子代理調用、13/13 測試通過、95.38% 覆蓋率）。文中嘅配置模板同參數建議僅供參考，實際效果請以你嘅項目環境同技術棧測試結果為準。如果你有實際使用經驗，歡迎喺評論區分享交流。
你會完成啲乜
✅ 搭建 OpenSpec + Superpowers 嘅 TDD 協作環境 ✅ 配置一套自訂 TDD Schema（完整嘅 schema.yaml、config.yaml、模板文件） ✅ 跑通 propose → apply → archive 完整流程 ✅ 瞭解方案嘅已知侷限同應對策略
環境準備
你需要準備
Node.js 20.19.0 或更高版本 Claude Code（已安裝 Superpowers 插件） OpenSpec v1.3.1 或更高版本 穩定嘅網絡連接 一個等開發嘅項目（純函數庫、REST API 或 CLI 工具效果比較好）
預計時間
⏱️ 完成呢個實戰大約需要 30-45 分鐘（唔計 AI 執行時間）
難度等級
⭐⭐ 中級 - 需要熟悉命令行同基本嘅 TDD 概念
點解需要呢兩個工具？
單獨用 OpenSpec，你可以將需求管理得好清楚——proposal、design、specs、tasks 一條龍生成。但去到執行階段，OpenSpec 嘅 apply 只係逐個勾選 task，無 TDD 強制，無子代理隔離，亦無自動審查。AI 一步完成整個功能係完全合理，因為一個 task 可能已經包含咗 RED+GREEN 混合內容。
單獨用 Superpowers，TDD 紀律好嚴——RED-GREEN-REFACTOR 強制循環，子代理隔離執行，兩階段自動審查。但 Superpowers 無 spec 管理，無變更追溯，需求全靠對話，轉個會話就唔記得了。
兩者互補關係好清晰：
講到底，**一個管"寫乜"，一個管"點樣做"**，組合起來正好覆蓋由需求到實現嘅完整鏈路。
圖 1：OpenSpec 同 Superpowers 互補關係——一個管「寫乜」，一個管「點樣做」
v1→v2→v3 嘅演進脈絡
開頭已經提過，呢個方案經歷咗三次迭代。v3 嘅 Schema 唔係憑空設計，而係喺 v2 實測基礎上做針對性改進。呢度詳細講下每版嘅教訓同修正。
v1 完全失敗（3 個原因）
坑 1：任務粒度唔啱。 一個 task 包含完整功能（RED+GREEN 撈埋一齊），AI 一步完成係合理——佢無做錯嘢，係你無約束佢嘅操作空間。
坑 2：兩套追蹤系統互唔引用。 OpenSpec 嘅 tasks.md 同 Superpowers 嘅 plan 係獨立系統，AI 唔知應該聽邊個。
坑 3：審查審嘅唔係 OpenSpec specs。 Superpowers 嘅 Spec Reviewer 審嘅係自己嘅 plan，唔係 OpenSpec 產出嘅 specs，等於審查同需求脱節。
v2 嘅 4 層防護（3/4 通過）
v2 針對以上三個坑，設計咗 4 層防護：
原子化 tasks.md - 每個 task = 一個 TDD 階段（RED 或 GREEN 或 REFACTOR），物理約束 AI 嘅操作空間 apply instruction 寫死 subagent-driven-development - 27 次 subagent dispatch 實測通過 config.yaml 嘅 context 寫得充足 - propose 全自動完成，無需人工輸入 驗證證據 - subagent 必須報告測試輸出，RED 階段必須見到失敗
v2 喺 Mini Markdown 項目上實測，3 層通過、1 層（審查）被 AI 跳過。但暴露咗新問題：審查只覆蓋前 2/26 個 task，測試覆蓋率 10/15，AI 自行調整咗文件結構。
v3 嘅改進（本文內容）
v3 將 v2 嘅經驗沉澱為三個改進：
中文版 Schema - instruction 全部中文化，降低中文用戶理解門檻 更誠實嘅時間預期 - v2 無提時間，v3 實測 12 個 task 耗時 1 小時 4 分鐘，明確話畀讀者知 已知問題嘅具體化 - v2 話「審查被跳過」，v3 指出係 Task 8 同 Task 10 被跳過；v2 話「git 無 RED-only 提交」，v3 發現係完全無提交
核心思路始終不變：分工而唔係串聯。OpenSpec 只管 propose 階段，Superpowers 只管 apply 階段，橋樑係 schema.yaml 裏面嘅 instruction 文本。
Step 1：初始化項目
先創建項目目錄，初始化基礎環境。
執行命令
# 創建項目目錄
mkdir my-tdd-project && cd my-tdd-project
# 初始化 git
git init
# 根據你的技術棧初始化，這裏以 TypeScript + Jest 為例
npm init -y
npm install --save-dev jest ts-jest @types/jest typescript
# 配置 test script（讓 npm test 指向 jest）
npm pkg set scripts.test="jest"
預期輸出
- Creating OpenSpec structure...
▌ OpenSpec structure created
- Setting up Claude Code...
✔ Setup complete for Claude Code
OpenSpec Setup Complete
Created: Claude Code
4 skills and 4 commands in .claude/
Config: skipped (non-interactive mode)
Getting started:
Start your first change: /opsx:propose "your idea"
驗證點
✅ 檢查 openspec/ 目錄已創建，包含 changes/ 和 specs/ 子目錄
注意：openspec init不會創建 schemas/ 目錄和 config.yaml，呢兩個需要手動創建，陣間會講到。
另外，npm init -y 生成的 package.json 中 scripts.test 默認是 echo "Error: no test specified" && exit 1。上面呢行 npm pkg set 將佢改成 jest，咁樣後面 npm test 就可以直接用。如果跳過呢步，後面驗收階段可以用 npx jest 代替，效果一樣。
Step 2：創建 TDD Schema
呢個係整個方案嘅核心配置步驟。我哋透過自訂 Schema 將 TDD 紀律注入 OpenSpec 嘅 artifact 生成流程。
2.1 創建目錄結構
# 創建 Schema 目錄和模板目錄
mkdir -p openspec/schemas/tdd-driven-v2/templates
2.2 創建 schema.yaml
保存到 openspec/schemas/tdd-driven-v2/schema.yaml：
name: tdd-driven-v2
version:2
description:原子化TDD工作流，子代理隔離執行，證據驅動驗證
artifacts:
-id:proposal
generates:proposal.md
description:變更提案——為什麼做、期望什麼行為
template:proposal.md
instruction:|
創建一份變更提案，說明為什麼要做這個改動。
必須用WHEN/THEN格式列出每一個可測試行為：
-WHEN<函數名>(<輸入>)被調用THEN結果為<期望值>
只描述"期望發生什麼"，不要描述實現細節。
requires:[]
-id:specs
generates:specs/**/*.md
description:行為規格——用場景描述期望行為
template:spec.md
instruction:|
用 GIVEN/WHEN/THEN 格式編寫行為規格：
- 每個場景必須可獨立測試
- 覆蓋：正常路徑、邊界情況、錯誤處理
- 只描述期望行為，不描述實現方式
requires:
-proposal
-id:design
generates:design.md
description:技術設計——怎麼實現、測試策略
template:design.md
instruction:|
編寫技術設計方案，說明如何實現。
必須包含：
-要創建的文件列表（測試文件+源碼文件，給出完整路徑）
-每個測試文件的測試策略（單元測試/集成測試）
-源碼文件與測試文件的對應關係
-測試運行命令
requires:
-proposal
-id:tasks
generates:tasks.md
description:原子化TDD任務列表
template:tasks.md
instruction:|
關鍵要求：將工作拆分為原子化 TDD 任務。
每個任務必須是且僅是一個 TDD 階段（RED / GREEN / REFACTOR）。
必須使用checkbox格式書寫每個任務：
### Feature: [功能名稱]
-[]RED:編寫失敗測試——[測試什麼行為]
-[]GREEN:最小實現——[實現描述，引用對應的RED任務]
-[]REFACTOR:重構清理——[清理描述]（可選）
規則：
1.禁止將RED和GREEN合併到一個任務
2.每個GREEN任務必須引用對應的RED測試
3.每個任務必須使用"- [ ]"checkbox格式
4.任務嚴格交替：RED→GREEN→（可選REFACTOR）
5.每個任務應在2-5分鐘內可完成
requires:
-specs
-design
-id:plans
generates:plan.md
description:執行計劃——每步對應一個任務，附驗證命令
template:plan.md
instruction:|
創建詳細的執行計劃。
每個計劃步驟必須精確對應 tasks.md 中的一個任務。
RED任務需包含：測試文件路徑、斷言內容、預期失敗原因、驗證命令。
GREEN任務需包含：要通過的測試、最小實現描述、驗證命令。
計劃末尾必須追加：
---
## Execution Mode Selection
REQUIRED:Usesuperpowers:subagent-driven-developmentskill.
DONOTuseexecuting-plansorinlineexecution.
requires:
-tasks
apply:
requires:[plans]
tracks:tasks.md
instruction:|
必須使用 superpowers:subagent-driven-development skill 執行。
禁止使用 executing-plans 或 inline 執行。
執行規則：
1.每個任務是一個原子TDD階段——每個任務派遣一個子代理
2.禁止並行派遣多個實現子代理
3.任務必須按順序執行
每個子代理的證據要求：
-RED任務：必須包含測試失敗輸出
如果RED階段報告"所有測試通過"→異常→重新派遣
-GREEN任務：必須包含測試通過輸出
如果GREEN階段報告"測試仍失敗"→不要標記完成→重新派遣
每個任務完成後（必須逐個執行，不可跳過）：
1.Spec審查：子代理是否精確實現了任務要求？
2.代碼質量審查：代碼是否乾淨、有測試、可維護？
3.兩項審查都通過後→標記完成（-[]→-[x]）
4.繼續下一個任務
全部任務完成後：
1.運行完整測試套件
2.驗證所有spec已滿足
3.檢查測試覆蓋率
2.3 創建 config.yaml
保存到 openspec/config.yaml（注意：喺 openspec/ 根目錄，唔係 schemas 裏面）：
schema: tdd-driven-v2
context:|
技術棧：TypeScript + Node.js
測試框架：Jest
測試運行命令：npx jest
項目說明：<替換為你的項目描述>
核心函數簽名：<替換為核心函數簽名>
所有生產代碼必須有對應的測試。
rules:
proposal:
-用WHEN/THEN格式列出每一個可測試行為
-不要描述實現細節
specs:
-每個場景使用GIVEN/WHEN/THEN格式
-每個場景必須可獨立測試
design:
-必須指定精確的測試文件路徑
-必須指定每個文件的測試策略
tasks:
-必須使用checkbox格式"- [ ]"
-每個任務是且僅是一個TDD階段（RED/GREEN/REFACTOR）
-任務嚴格交替RED→GREEN→（可選REFACTOR）
-GREEN任務必須引用對應的RED任務
plans:
-每個計劃步驟精確對應一個任務
-必須指定驗證命令和預期證據
2.4 創建模板文件
保存到 openspec/schemas/tdd-driven-v2/templates/：
模板說明：模板文件使用 HTML 註釋（<!-- -->）標註結構提示，唔係變量佔位符。OpenSpec 唔會「替換」呢啲註釋，而係由 AI 根據 schema.yaml 中的 instruction 字段來生成每個 artifact 嘅實際內容。模板嘅作用係提供結構骨架，等 AI 知道每個 artifact 應該包含邊啲區域。
proposal.md：
# Proposal
## Problem
<!-- 描述要解決的問題 -->
## Testable Behaviors
<!-- WHEN/THEN 格式列出每一個可測試行為 -->
## Acceptance Criteria
<!-- 驗收標準 -->
spec.md：
# Spec
## Scenarios
### Scenario 1: [name]
- GIVEN: [前置條件]
- WHEN: [操作]
- THEN: [期望結果]
design.md：
# Design
## File Structure
<!-- 列出要創建的文件，包括測試文件 -->
## Test Strategy
<!-- 每個 test 文件的測試策略 -->
tasks.md：
# Tasks
## Atomic TDD Task List
<!-- 每個 task 只能是一個 TDD 階段 -->
<!-- 必須使用 checkbox 格式 -->
### [Feature name]
- [ ] RED: ...
- [ ] GREEN: ...
plan.md：
# Execution Plan
## Steps
### Step 1: RED — [description]
- Test file: [path]
- Assertion: [what to test]
- Expected failure: [reason]
- Verify: `npx jest [test-file]`
### Step 2: GREEN — [description]
- Pass test from: Step 1
- Minimal code: [what to implement]
- Verify: `npx jest [test-file]`
2.5 驗證 Schema
# 驗證 schema 格式（會出現 experimental 提示，正常，不影響使用）
openspec schema validate tdd-driven-v2
驗證點
✅ 目錄結構如下：
openspec/
├── schemas/tdd-driven-v2/
│ ├── schema.yaml
│ └── templates/
│ ├── proposal.md
│ ├── spec.md
│ ├── design.md
│ ├── tasks.md
│ └── plan.md
├── config.yaml
├── changes/
└── specs/
到呢度，TDD Schema 配置完成。呢個係整個方案裏面工作量比較大嘅一個步驟，但亦係一次性投入——配好之後，後面每個功能都可以重用。
圖 2：TDD Schema 目錄結構——schema.yaml 定義規則，templates 提供骨架，config.yaml 注入項目上下文
Step 3：執行 propose
準備工夫做完，開始俾 AI 生成規格文檔。
執行命令
喺 Claude Code 輸入：
/opsx:propose <你的功能描述>
輸入格式：支援 kebab-case 名稱（例如 add-todo-priority）或自然語言描述（例如「俾 Todo API 加上任務優先級功能」）。自然語言輸入時，AI 會自動提取 change name。
舉個例子，執行 /opsx:propose 之後輸入你嘅功能描述，可以用自然語言：
俾 Todo API 加上任務優先級功能
AI 會自動提取 change name（本例中係 add-todo-priority），依次調用 openspec instructions <artifact> 獲取每個 artifact 嘅增強指令，然後逐個生成 5 個 artifact。如果你嘅 config.yaml 嘅 context 寫得夠詳細，呢一步係全自動——用戶只輸入一次需求描述，唔使二次互動。
預期行為
如果你嘅 config.yaml 的 context 寫得夠詳細，呢一步係全自動嘅。AI 會喺 2-3 分鐘內生成 5 個 artifact：
proposal.md- 變更提案（WHY + 可測試行為列表）specs/- 行為規格（GIVEN/WHEN/THEN 場景）design.md- 技術設計（文件結構 + 測試策略）tasks.md- 原子化 TDD 任務列表plan.md- 執行計劃（每步映射到具體 task）
propose 之後一定要人工審查
唔好急住執行。花 5 分鐘審查呢三個文件：
1. proposal.md：WHEN/THEN 行為列表係咪完整？有冇遺漏邊界情況？
2. design.md：文件結構同測試策略係咪合理？測試文件路徑係咪正確？
3. tasks.md（最關鍵）：
每個 - [ ]係咪得一個 TDD 階段？RED 同 GREEN 係咪嚴格交替？ 如果唔係，手動修改 tasks.md 再繼續
如果 tasks.md 裏面出現咗「RED+GREEN: 寫測試並實現」呢類合併任務，即係 AI 無遵守原子化約束。手動拆開佢。
REFACTOR 任務：schema 中 REFACTOR 標註為可選，AI 可能唔生成 REFACTOR 任務。如果某個 Feature 確實需要重構清理，可以手動喺 tasks.md 補充。
調試命令
如果生成結果唔理想，可以睇下 AI 實際收到嘅 instruction：
前提：需要先執行 /opsx:propose 創建一個活躍 change，否則會報 No changes found 錯誤。呢啲命令係 propose 之後嘅調試手段。
# 查看 tasks 階段的 instruction
openspec instructions tasks --change <change-name> --json
# 查看 apply 階段的 instruction
openspec instructions apply --change <change-name> --json
驗證點
✅ openspec/changes/<change-name>/ 下生成了 5 個 artifact ✅ tasks.md 嘅每個 task 都係原子化（單個 TDD 階段） ✅ proposal.md 使用 WHEN/THEN 格式列出所有可測試行為
Step 4：執行 apply
人工審查通過之後，俾 AI 開始實現代碼。
執行命令
喺 Claude Code 輸入：
/opsx:apply <change-name>
預期行為
AI 會自動：
讀取 apply instruction 逐個 dispatch subagent 執行每個 TDD task 每個 subagent 完成之後進行兩階段審查（Spec 合規 → 代碼質量） 審查通過後勾選 checkbox，進入下一個 task
apply 階段係全自動，用戶只需等。以 Todo API 加優先級功能嘅實測為例：
輸入：12 個原子化 TDD task（6 × RED+GREEN） 執行：34 次子代理調用（24 次 general-purposeimplementer/spec-reviewer + 10 次superpowers:code-reviewer）結果：13 個測試全部通過，覆蓋率 95.38% 耗時：約 1 小時 4 分鐘
⚠️ 實測耗時遠超預期。核心瓶頸唔係模型推理速度，而係流程紀律開銷——
subagent-driven-development要求每個原子 task 行 implementer → spec-reviewer → code-reviewer 三輪子代理，34 次調用中每次都需要獨立嘅上下文構建。呢個流程開銷同需求複雜度關係唔大——v2 驗證（26 個 task）係 27 次調用，今次（12 個 task）係 34 次調用。對於簡單需求，流程紀律嘅成本唔成比例。如果你趕時間，可以考慮修改plan.md結尾嘅 Execution Mode Selection，改用 inline 模式快速實現。
重要提醒：apply 係長時間運行嘅過程（實測 1 小時+），過程中唔好中斷。中途斷開可能導致部分 task 已完成但 tasks.md 未更新，恢復起嚟好麻煩。建議喺開始 apply 前確認網絡穩定，並有足夠時間等。
apply 結束之後，AI 會輸出一份完成摘要：
## Implementation Complete
**Change:** `add-todo-priority`
**Schema:** `tdd-driven-v2`
**Progress:** 12/12 tasks complete ✓
### Final Test Results
Test Suites: 3 passed, 3 total
Tests: 13 passed, 13 total
Coverage: 95.38%
如果 AI 無用 subagent 模式
如果 AI 直接 inline 執行（跳過 subagent dispatch），手動提醒佢：
請使用 superpowers:subagent-driven-development skill 執行 apply 階段，唔好用 inline 執行。
呢種情況喺上下文窗口比較緊張時可能會出現。
驗證點
✅ AI 使用咗 subagent-driven-development 模式 ✅ 每個 task 有獨立嘅 subagent dispatch ✅ 每個 subagent 報告咗測試輸出（RED 階段有失敗輸出，GREEN 階段有通過輸出）
圖 3：子代理調度與兩階段審查流程——每個 task 行 implementer → spec-reviewer → code-reviewer 三輪子代理
Step 5：人工驗收
AI 執行完，但唔好急住歸檔。驗收呢步唔慳得。
執行驗收命令
# 運行全部測試（如果已在 Step 1 配置了 npm pkg set scripts.test="jest"）
npm test
# 或者直接用 npx（不依賴 package.json 配置）
npx jest
# 檢查測試覆蓋率
npx jest --coverage
注意：如果你喺 Step 1 無更新 package.json 嘅 test script，直接運行 npm test 會報錯。可以用 npx jest 代替，效果一樣。
# 查看 tasks 完成情況
cat openspec/changes/<change-name>/tasks.md
# 查看 git 提交記錄
git log --oneline
驗收檢查清單
逐項檢查：
[ ] npm test或npx jest全部通過[ ] tasks.md所有 checkbox 已勾選[ ] 測試覆蓋率 >= proposal 中嘅行為數量 [ ] 源碼文件結構與 design.md一致（或偏離可接受）[ ] 無 TODO 標記或未完成嘅樁代碼
唔通過嘅話點算
測試未全部通過 → 叫 AI 修復失敗嘅測試，或者手動修復
覆蓋率不足 → 參考 proposal.md 補充遺漏嘅測試用例
文件結構偏離 → 判斷偏離係咪可接受。如果 AI 將兩個文件合併成一個，而且功能正確，可以接受
有未完成嘅樁代碼 → 叫 AI 補全實現，或者標記為下一個 change
Step 6：歸檔
驗收通過之後，歸檔今次變更。
執行命令
/opsx:archive <change-name>
預期行為
AI 會將 openspec/changes/<change-name>/ 移動到 openspec/changes/archive/YYYY-MM-DD-<change-name>/ 目錄下，自動添加日期前綴方便時間排序。
執行 /opsx:archive 之後，AI 會輸出歸檔摘要：
## Archive Complete
**Change:** `add-todo-priority`
**Schema:** `tdd-driven-v2`
**Archived to:** `openspec/changes/archive/2026-05-06-add-todo-priority/`
**Specs:** No delta specs (main specs directory empty)
All artifacts complete. All 12 tasks complete.
驗證點
✅ openspec/changes/archive/ 下出現咗帶日期前綴嘅歸檔目錄（例如 2026-05-06-add-todo-priority/） ✅ 原活躍目錄已清理
關於 Spec 同步：archive 之後 openspec/specs/ 目錄可能仍然係空。呢個係因為 OpenSpec 嘅 spec 同步需要額外配置（例如喺 schema 定義 sync 行為），當前版本嘅 TDD schema 無觸發自動同步。如果你需要將歸檔嘅 specs 累積到項目級知識庫，可以喺 archive 之後手動將 changes/archive/*/specs/ 下嘅文件複製到 openspec/specs/。
下一次 propose：archive 之後目錄已清理，直接運行 /opsx:propose <新功能描述> 就可以創建新嘅 change。已有嘅 TDD Schema（tdd-driven-v2）會被自動重用，唔使重新配置。每個 change 嘅 specs、tasks、plan 都會獨立生成，互不幹擾。
完整流程回顧
將 6 個步驟串埋一齊：
初始化項目 → 創建 TDD Schema → /opsx:propose → 人工審查 → /opsx:apply → 人工驗收 → /opsx:archive
(Step 1) (Step 2) (Step 3) (必須做) (Step 4) (必須做) (Step 6)
對應嘅命令序列：
# Step 1: 初始化
mkdir my-project && cd my-project
git init && npm init -y
npm install --save-dev jest ts-jest @types/jest typescript
npm pkg set scripts.test="jest"
openspec init --tools claude
# Step 2: 創建 Schema（一次性配置）
mkdir -p openspec/schemas/tdd-driven-v2/templates
# 手動創建 schema.yaml、config.yaml 和 5 個模板文件
# Step 3: 生成規格
# 在 Claude Code 中: /opsx:propose "你的功能描述"
# 人工審查 proposal、design、tasks
# Step 4: 執行實現
# 在 Claude Code 中: /opsx:apply <change-name>
# Step 5: 人工驗收
npx jest && npx jest --coverage
# Step 6: 歸檔
# 在 Claude Code 中: /opsx:archive <change-name>
已知問題同應對
老實講，呢個方案唔係銀彈。v2 實測發現咗 6 個已知侷限，需要喺人工驗收階段兜底。
問題 1：部分 task 跳過了審查
AI 會選擇性跳過某啲 task 嘅 spec-reviewer 同 code-reviewer，直接標記完成。跳過嘅唔係「後幾個」，而係分散喺中間——實測中 Task 8 同 Task 10 被跳過。
應對：apply 結束之後，唔好假設所有 task 都經過咗審查。對照 session 日誌或 AI 輸出，確認每個 task 係咪都有審查報告，跳過嘅部分手動補審。
問題 2：測試覆蓋率可能不足
實測中 15 個行為只覆蓋咗 10 個，AI 跳過咗部分邊界情況。
應對：對照 proposal.md 嘅 WHEN/THEN 列表，逐個檢查有冇對應測試，缺嘅補上。
問題 3：AI 可能自行調整文件結構
例如你喺 design.md 裏面規劃咗兩個文件，AI 合併成一個。呢個唔一定錯，但偏離咗設計。
應對：判斷偏離係咪合理。如果功能正確、代碼質量無問題，可以接受。
問題 4：apply 階段唔產生 git 提交
實測中 apply 結束之後 git log 無任何提交記錄。AI 喺子代理模式下唔做 git add/commit。
應對：apply 結束之後手動驗收並提交：
git add -A
git commit -m "feat: implement <change-name> via OpenSpec + Superpowers TDD workflow"
問題 5：執行時間同需求複雜度不成比例
subagent-driven-development 嘅流程紀律開銷係系統性嘅。12 個 task 實測 64 分鐘，26 個 task 實測約 90 分鐘。即使簡單需求（例如「俾 interface 加一個字段」），每個 task 仍需三輪子代理審查。本質係用「流程紀律」換「代碼質量」。
應對：
對於簡單需求，可以修改 plan.md結尾嘅 Execution Mode Selection，使用 inline 模式而唔係 subagent-driven-development或者只喺關鍵 task 上啓用審查，跳過簡單嘅 CRUD task apply 結束之後人工驗收係唔可以慳，呢個係兜底環節
問題 6（接口一致性）：子代理模式下嘅 code review 可能會遺漏接口定義不一致嘅問題。實測中 todo.model.ts 和 todo.service.ts 各自定義咗唔同嘅 Todo 接口（model 缺少 createdAt 字段），code reviewer 無發現。
應對：apply 結束之後，特別檢查跨文件嘅接口/類型定義係咪一致。如果多個文件引用同一數據結構，確認佢哋引用嘅係同一個 type/interface 定義，而唔係各自重新定義。
適用場景分析
呢個方案唔係所有場景都適合。
適合：
純函數庫、工具函數 REST API（CRUD 類） CLI 工具 數據轉換/處理邏輯
要小心啲：
前端 UI 組件（測試行為好難用 WHEN/THEN 表達） 依賴外部服務嘅功能（數據庫、第三方 API、文件系統） 時間緊迫嘅原型開發（Schema 配置 + 審查需要額外時間）
進階技巧
技巧一：重用 Schema
TDD Schema 配好一次就可以重用。新建項目時只需要將 openspec/schemas/tdd-driven-v2/ 和 openspec/config.yaml 複製過去，改一下 config.yaml 裏面嘅技術棧信息就得。
技巧二：config.yaml 嘅 context 越詳細越好
context 字段寫得越詳細，propose 階段嘅全自動率越高。核心函數簽名、輸入輸出類型、已有嘅工具函數列表 - 呢啲信息都可以幫 AI 一次生成正確嘅 proposal，慳返多輪修改。
技巧三：propose 之後審查係 ROI 好高嘅 5 分鐘
唔好 skip 咗 propose 之後嘅人工審查。特別係 tasks.md，一旦原子化約束未生效，後續成個 apply 階段都會走偏。5 分鐘嘅人工審查可以慳返 30 分鐘嘅返工。
總結
OpenSpec + Superpowers 嘅 TDD 協作方案，核心思路就一句話：等 OpenSpec 將需求拆細，等 Superpowers 將執行管嚴。
三次迭代，一次比一次清醒：v1 失敗教會咗三個教訓（任務粒度一定要原子化、兩套系統唔可以各自為戰、審查一定要對齊需求）；v2 用 4 層防護驗證咗原子化任務同 subagent 隔離嘅有效性（3/4 通過）；v3 喺呢個基礎上沉澱為可重用嘅中文版 Schema，完整跑通咗 propose → apply → archive 全流程。
呢個方案用時間換質量——一個中等功能可能要等 1 小時，但換嚟 95%+ 嘅測試覆蓋率同完整嘅變更追溯。如果你趕進度，佢可能唔係最優選；如果你追求工程化，佢值得一試。
如果你都喺度用 OpenSpec 或 Superpowers，歡迎喺評論區傾下你嘅使用體驗。
好啦，多謝你睇我嘅文章，如果鍾意可以點讚轉發俾有需要嘅朋友，我哋下一期再見！敬請期待！
掃碼關注，獲取更多 AI 工具嘅實戰經驗同最佳實踐。唔好錯過每一篇乾貨！
OpenSpec + Superpowers：一個管寫什麼，一個管怎麼做，6 步實現 AI 規格驅動 TDD 開發（實戰版）
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 104 篇，AI 編程最佳實戰「2026」系列第 29
大家好，歡迎來到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一名專注於 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫的技術實踐者與開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
用 AI 編程助手寫代碼，很多人踩過同一個坑：代碼跑起來了，但不是你想要的。
問題出在哪？不是 AI 能力不夠，是你沒告訴它寫什麼、怎麼寫才算對。需求模糊 → AI 自由發揮 → 你反覆改，這個循環吞噬了大量時間。
這篇文章是 OpenSpec + Superpowers TDD 協作方案的第三次嘗試（v3），也是第一次完整跑通 propose → apply → archive 全流程的版本。
前兩版的故事是這樣的：
v1 完全失敗。 apply 階段 AI 一口氣寫完所有代碼，跳過了 RED 階段，測試是寫完實現後補的。TDD 形同虛設。失敗根因不在 instruction 措辭，在任務粒度——一個 task 包含完整功能（RED+GREEN 混合），AI 一步完成是合理的。
v2 設計了 4 層防護。 原子化任務 + subagent 隔離 + 兩階段審查 + 驗證證據，在 Mini Markdown 項目上拆了 26 個原子任務，dispatch 了 27 次 subagent，3 層通過、1 層被 AI 跳過。v2 證明了原子化任務和 subagent 隔離是有效的，但審查覆蓋不完整（僅前 2/26 task 有審查），測試覆蓋率 10/15，架構決策偏離 design.md。（詳見上一篇：[《OpenSpec + Superpowers TDD v2：4 層防護疊加 26 個原子任務，27 次 subagent 實測 3/4 通過》]）
v3 做了三個關鍵修正：把 v2 的 4 層防護經驗沉澱為一套可複用的中文版 Schema，補充了 propose 支持自然語言輸入、archive 的日期前綴歸檔路徑、以及更誠實的時間預期（實測 12 個 task 耗時 1 小時 4 分鐘）。這一版用 Todo API 項目做驗證，完整跑通了 6 個步驟：初始化 → 創建 Schema → propose → apply → 人工驗收 → archive。
用一句話概括方案核心：OpenSpec 管「寫什麼」，Superpowers 管「怎麼做」，橋樑是 schema.yaml 裏的 instruction 文本。
說明：本文內容基於 OpenSpec（Fission-AI/OpenSpec）和 Superpowers（obra/superpowers）的源碼分析、官方文檔和三天兩次實戰驗證。v2 在 Mini Markdown 項目驗證（26 個 task、27 次子代理調用、10/10 測試通過），v3 在 Todo API 項目驗證（12 個 task、34 次子代理調用、13/13 測試通過、95.38% 覆蓋率）。文中的配置模板和參數建議僅供參考，實際效果請以你的項目環境和技術棧測試結果為準。如果你有實際使用經驗，歡迎在評論區分享交流。
你將完成什麼
✅ 搭建 OpenSpec + Superpowers 的 TDD 協作環境 ✅ 配置一套自定義 TDD Schema（完整的 schema.yaml、config.yaml、模板文件） ✅ 跑通 propose → apply → archive 完整流程 ✅ 瞭解方案的已知侷限和應對策略
環境準備
你需要準備
Node.js 20.19.0 或更高版本 Claude Code（已安裝 Superpowers 插件） OpenSpec v1.3.1 或更高版本 穩定的網絡連接 一個待開發的項目（純函數庫、REST API 或 CLI 工具效果較好）
預計時間
⏱️ 完成本實戰大約需要 30-45 分鐘（不含 AI 執行時間）
難度等級
⭐⭐ 中級 - 需要熟悉命令行和基本的 TDD 概念
為什麼需要這兩個工具？
單獨用 OpenSpec，你能把需求管得很清楚——proposal、design、specs、tasks 一條龍生成。但到執行階段，OpenSpec 的 apply 只是逐個勾選 task，沒有 TDD 強制，沒有子代理隔離，也沒有自動審查。AI 一步完成整個功能是完全合理的，因為一個 task 可能就包含了 RED+GREEN 混合內容。
單獨用 Superpowers，TDD 紀律很嚴——RED-GREEN-REFACTOR 強制循環，子代理隔離執行，兩階段自動審查。但 Superpowers 沒有 spec 管理，沒有變更追溯，需求全靠對話，換個會話就忘了。
兩者互補關係很清晰：
說到底，**一個管"寫什麼"，一個管"怎麼做"**，組合起來正好覆蓋從需求到實現的完整鏈路。
圖 1：OpenSpec 和 Superpowers 互補關係——一個管「寫什麼」，一個管「怎麼做」
v1→v2→v3 的演進脈絡
開頭已經提過，這個方案經歷了三次迭代。v3 的 Schema 不是憑空設計的，而是在 v2 實測基礎上做了針對性改進。這裏展開講講每版的教訓和修正。
v1 完全失敗（3 個原因）
坑 1：任務粒度不對。 一個 task 包含完整功能（RED+GREEN 混在一起），AI 一步完成是合理的——它沒有做錯什麼，是你沒約束它的操作空間。
坑 2：兩套追蹤系統互不引用。 OpenSpec 的 tasks.md 和 Superpowers 的 plan 是獨立系統，AI 不知道該聽誰的。
坑 3：審查審的不是 OpenSpec specs。 Superpowers 的 Spec Reviewer 審的是自己的 plan，不是 OpenSpec 產出的 specs，等於審查和需求脱節。
v2 的 4 層防護（3/4 通過）
v2 針對以上三個坑，設計了 4 層防護：
原子化 tasks.md - 每個 task = 一個 TDD 階段（RED 或 GREEN 或 REFACTOR），物理約束 AI 的操作空間 apply instruction 寫死 subagent-driven-development - 27 次 subagent dispatch 實測通過 config.yaml 的 context 寫得充分 - propose 全自動完成，無需人工輸入 驗證證據 - subagent 必須報告測試輸出，RED 階段必須看到失敗
v2 在 Mini Markdown 項目上實測，3 層通過、1 層（審查）被 AI 跳過。但暴露了新的問題：審查只覆蓋前 2/26 個 task，測試覆蓋率 10/15，AI 自行調整了文件結構。
v3 的改進（本文內容）
v3 把 v2 的經驗沉澱為三個改進：
中文版 Schema - instruction 全部中文化，降低中文用戶理解門檻 更誠實的時間預期 - v2 沒提時間，v3 實測 12 個 task 耗時 1 小時 4 分鐘，明確告知讀者 已知問題的具體化 - v2 說"審查被跳過"，v3 指出是 Task 8 和 Task 10 被跳過；v2 說"git 無 RED-only 提交"，v3 發現是完全沒有提交
核心思路始終不變：分工而非串聯。OpenSpec 只管 propose 階段，Superpowers 只管 apply 階段，橋樑是 schema.yaml 裏的 instruction 文本。
Step 1：初始化項目
先創建項目目錄，初始化基礎環境。
執行命令
# 創建項目目錄
mkdir my-tdd-project && cd my-tdd-project
# 初始化 git
git init
# 根據你的技術棧初始化，這裏以 TypeScript + Jest 為例
npm init -y
npm install --save-dev jest ts-jest @types/jest typescript
# 配置 test script（讓 npm test 指向 jest）
npm pkg set scripts.test="jest"
預期輸出
- Creating OpenSpec structure...
▌ OpenSpec structure created
- Setting up Claude Code...
✔ Setup complete for Claude Code
OpenSpec Setup Complete
Created: Claude Code
4 skills and 4 commands in .claude/
Config: skipped (non-interactive mode)
Getting started:
Start your first change: /opsx:propose "your idea"
驗證點
✅ 檢查 openspec/ 目錄已創建，包含 changes/ 和 specs/ 子目錄
注意：openspec init不會創建 schemas/ 目錄和 config.yaml，這兩個需要手動創建，接下來會講到。
另外，npm init -y 生成的 package.json 中 scripts.test 默認是 echo "Error: no test specified" && exit 1。上面這行 npm pkg set 把它改成了 jest，這樣後面 npm test 就能直接用。如果跳過這步，後面驗收階段可以用 npx jest 代替，效果一樣。
Step 2：創建 TDD Schema
這是整個方案的核心配置步驟。我們通過自定義 Schema 把 TDD 紀律注入 OpenSpec 的 artifact 生成流程。
2.1 創建目錄結構
# 創建 Schema 目錄和模板目錄
mkdir -p openspec/schemas/tdd-driven-v2/templates
2.2 創建 schema.yaml
保存到 openspec/schemas/tdd-driven-v2/schema.yaml：
name: tdd-driven-v2
version:2
description:原子化TDD工作流，子代理隔離執行，證據驅動驗證
artifacts:
-id:proposal
generates:proposal.md
description:變更提案——為什麼做、期望什麼行為
template:proposal.md
instruction:|
創建一份變更提案，說明為什麼要做這個改動。
必須用WHEN/THEN格式列出每一個可測試行為：
-WHEN<函數名>(<輸入>)被調用THEN結果為<期望值>
只描述"期望發生什麼"，不要描述實現細節。
requires:[]
-id:specs
generates:specs/**/*.md
description:行為規格——用場景描述期望行為
template:spec.md
instruction:|
用 GIVEN/WHEN/THEN 格式編寫行為規格：
- 每個場景必須可獨立測試
- 覆蓋：正常路徑、邊界情況、錯誤處理
- 只描述期望行為，不描述實現方式
requires:
-proposal
-id:design
generates:design.md
description:技術設計——怎麼實現、測試策略
template:design.md
instruction:|
編寫技術設計方案，說明如何實現。
必須包含：
-要創建的文件列表（測試文件+源碼文件，給出完整路徑）
-每個測試文件的測試策略（單元測試/集成測試）
-源碼文件與測試文件的對應關係
-測試運行命令
requires:
-proposal
-id:tasks
generates:tasks.md
description:原子化TDD任務列表
template:tasks.md
instruction:|
關鍵要求：將工作拆分為原子化 TDD 任務。
每個任務必須是且僅是一個 TDD 階段（RED / GREEN / REFACTOR）。
必須使用checkbox格式書寫每個任務：
### Feature: [功能名稱]
-[]RED:編寫失敗測試——[測試什麼行為]
-[]GREEN:最小實現——[實現描述，引用對應的RED任務]
-[]REFACTOR:重構清理——[清理描述]（可選）
規則：
1.禁止將RED和GREEN合併到一個任務
2.每個GREEN任務必須引用對應的RED測試
3.每個任務必須使用"- [ ]"checkbox格式
4.任務嚴格交替：RED→GREEN→（可選REFACTOR）
5.每個任務應在2-5分鐘內可完成
requires:
-specs
-design
-id:plans
generates:plan.md
description:執行計劃——每步對應一個任務，附驗證命令
template:plan.md
instruction:|
創建詳細的執行計劃。
每個計劃步驟必須精確對應 tasks.md 中的一個任務。
RED任務需包含：測試文件路徑、斷言內容、預期失敗原因、驗證命令。
GREEN任務需包含：要通過的測試、最小實現描述、驗證命令。
計劃末尾必須追加：
---
## Execution Mode Selection
REQUIRED:Usesuperpowers:subagent-driven-developmentskill.
DONOTuseexecuting-plansorinlineexecution.
requires:
-tasks
apply:
requires:[plans]
tracks:tasks.md
instruction:|
必須使用 superpowers:subagent-driven-development skill 執行。
禁止使用 executing-plans 或 inline 執行。
執行規則：
1.每個任務是一個原子TDD階段——每個任務派遣一個子代理
2.禁止並行派遣多個實現子代理
3.任務必須按順序執行
每個子代理的證據要求：
-RED任務：必須包含測試失敗輸出
如果RED階段報告"所有測試通過"→異常→重新派遣
-GREEN任務：必須包含測試通過輸出
如果GREEN階段報告"測試仍失敗"→不要標記完成→重新派遣
每個任務完成後（必須逐個執行，不可跳過）：
1.Spec審查：子代理是否精確實現了任務要求？
2.代碼質量審查：代碼是否乾淨、有測試、可維護？
3.兩項審查都通過後→標記完成（-[]→-[x]）
4.繼續下一個任務
全部任務完成後：
1.運行完整測試套件
2.驗證所有spec已滿足
3.檢查測試覆蓋率
2.3 創建 config.yaml
保存到 openspec/config.yaml（注意：在 openspec/ 根目錄，不是 schemas 裏面）：
schema: tdd-driven-v2
context:|
技術棧：TypeScript + Node.js
測試框架：Jest
測試運行命令：npx jest
項目說明：<替換為你的項目描述>
核心函數簽名：<替換為核心函數簽名>
所有生產代碼必須有對應的測試。
rules:
proposal:
-用WHEN/THEN格式列出每一個可測試行為
-不要描述實現細節
specs:
-每個場景使用GIVEN/WHEN/THEN格式
-每個場景必須可獨立測試
design:
-必須指定精確的測試文件路徑
-必須指定每個文件的測試策略
tasks:
-必須使用checkbox格式"- [ ]"
-每個任務是且僅是一個TDD階段（RED/GREEN/REFACTOR）
-任務嚴格交替RED→GREEN→（可選REFACTOR）
-GREEN任務必須引用對應的RED任務
plans:
-每個計劃步驟精確對應一個任務
-必須指定驗證命令和預期證據
2.4 創建模板文件
保存到 openspec/schemas/tdd-driven-v2/templates/：
模板說明：模板文件使用 HTML 註釋（<!-- -->）標註結構提示，不是變量佔位符。OpenSpec 不會"替換"這些註釋，而是由 AI 根據 schema.yaml 中的 instruction 字段來生成每個 artifact 的實際內容。模板的作用是提供結構骨架，讓 AI 知道每個 artifact 應該包含哪些區域。
proposal.md：
# Proposal
## Problem
<!-- 描述要解決的問題 -->
## Testable Behaviors
<!-- WHEN/THEN 格式列出每一個可測試行為 -->
## Acceptance Criteria
<!-- 驗收標準 -->
spec.md：
# Spec
## Scenarios
### Scenario 1: [name]
- GIVEN: [前置條件]
- WHEN: [操作]
- THEN: [期望結果]
design.md：
# Design
## File Structure
<!-- 列出要創建的文件，包括測試文件 -->
## Test Strategy
<!-- 每個 test 文件的測試策略 -->
tasks.md：
# Tasks
## Atomic TDD Task List
<!-- 每個 task 只能是一個 TDD 階段 -->
<!-- 必須使用 checkbox 格式 -->
### [Feature name]
- [ ] RED: ...
- [ ] GREEN: ...
plan.md：
# Execution Plan
## Steps
### Step 1: RED — [description]
- Test file: [path]
- Assertion: [what to test]
- Expected failure: [reason]
- Verify: `npx jest [test-file]`
### Step 2: GREEN — [description]
- Pass test from: Step 1
- Minimal code: [what to implement]
- Verify: `npx jest [test-file]`
2.5 驗證 Schema
# 驗證 schema 格式（會出現 experimental 提示，正常，不影響使用）
openspec schema validate tdd-driven-v2
驗證點
✅ 目錄結構如下：
openspec/
├── schemas/tdd-driven-v2/
│ ├── schema.yaml
│ └── templates/
│ ├── proposal.md
│ ├── spec.md
│ ├── design.md
│ ├── tasks.md
│ └── plan.md
├── config.yaml
├── changes/
└── specs/
到這裏，TDD Schema 配置完成。這是整個方案裏工作量比較大的一個步驟，但也是一次性投入——配好之後，後續每個功能都可以複用。
圖 2：TDD Schema 目錄結構——schema.yaml 定義規則，templates 提供骨架，config.yaml 注入項目上下文
Step 3：執行 propose
準備工作做完了，開始讓 AI 生成規格文檔。
執行命令
在 Claude Code 中輸入：
/opsx:propose <你的功能描述>
輸入格式：支持 kebab-case 名稱（如 add-todo-priority）或自然語言描述（如"給 Todo API 加上任務優先級功能"）。自然語言輸入時，AI 會自動提取 change name。
舉個例子，執行 /opsx:propose 後輸入你的功能描述，可以用自然語言：
給 Todo API 加上任務優先級功能
AI 會自動提取 change name（本例中為 add-todo-priority），依次調用 openspec instructions <artifact> 獲取每個 artifact 的增強指令，然後逐個生成 5 個 artifact。如果你的 config.yaml 的 context 寫得足夠詳細，這一步是全自動的——用戶只輸入一次需求描述，無需二次交互。
預期行為
如果你的 config.yaml 的 context 寫得足夠詳細，這一步是全自動的。AI 會在 2-3 分鐘內生成 5 個 artifact：
proposal.md- 變更提案（WHY + 可測試行為列表）specs/- 行為規格（GIVEN/WHEN/THEN 場景）design.md- 技術設計（文件結構 + 測試策略）tasks.md- 原子化 TDD 任務列表plan.md- 執行計劃（每步映射到具體 task）
propose 後必須人工審查
別急着執行。花 5 分鐘審查這三個文件：
1. proposal.md：WHEN/THEN 行為列表是否完整？有沒有遺漏的邊界情況？
2. design.md：文件結構和測試策略是否合理？測試文件路徑是否正確？
3. tasks.md（最關鍵）：
每個 - [ ]是否只有一個 TDD 階段？RED 和 GREEN 是否嚴格交替？ 如果不是，手動修改 tasks.md 再繼續
如果 tasks.md 裏出現了"RED+GREEN: 寫測試並實現"這種合併任務，說明 AI 沒遵守原子化約束。手動拆開它。
REFACTOR 任務：schema 中 REFACTOR 標註為可選，AI 可能不生成 REFACTOR 任務。如果某個 Feature 確實需要重構清理，可以手動在 tasks.md 中補充。
調試命令
如果生成結果不理想，可以查看 AI 實際收到的 instruction：
前提：需要先執行 /opsx:propose 創建一個活躍 change，否則會報 No changes found 錯誤。這些命令是 propose 之後的調試手段。
# 查看 tasks 階段的 instruction
openspec instructions tasks --change <change-name> --json
# 查看 apply 階段的 instruction
openspec instructions apply --change <change-name> --json
驗證點
✅ openspec/changes/<change-name>/ 下生成了 5 個 artifact ✅ tasks.md 的每個 task 都是原子化的（單個 TDD 階段） ✅ proposal.md 使用 WHEN/THEN 格式列出所有可測試行為
Step 4：執行 apply
人工審查通過後，讓 AI 開始實現代碼。
執行命令
在 Claude Code 中輸入：
/opsx:apply <change-name>
預期行為
AI 會自動：
讀取 apply instruction 逐個 dispatch subagent 執行每個 TDD task 每個 subagent 完成後進行兩階段審查（Spec 合規 → 代碼質量） 審查通過後勾選 checkbox，進入下一個 task
apply 階段是全自動的，用戶只需等待。以 Todo API 加優先級功能的實測為例：
輸入：12 個原子化 TDD task（6 × RED+GREEN） 執行：34 次子代理調用（24 次 general-purposeimplementer/spec-reviewer + 10 次superpowers:code-reviewer）結果：13 個測試全部通過，覆蓋率 95.38% 耗時：約 1 小時 4 分鐘
⚠️ 實測耗時遠超預期。核心瓶頸不是模型推理速度，而是流程紀律開銷——
subagent-driven-development要求每個原子 task 走 implementer → spec-reviewer → code-reviewer 三輪子代理，34 次調用中每次都需要獨立的上下文構建。這個流程開銷與需求複雜度關聯不大——v2 驗證（26 個 task）是 27 次調用，本次（12 個 task）是 34 次調用。對於簡單需求，流程紀律的成本不成比例。如果你趕時間，可以考慮修改plan.md末尾的 Execution Mode Selection，改用 inline 模式快速實現。
重要提醒：apply 是長時間運行的過程（實測 1 小時+），過程中不要中斷。中途中斷可能導致部分 task 已完成但 tasks.md 未更新，恢復起來很麻煩。建議在開始 apply 前確認網絡穩定，並且有足夠的時間等待。
apply 結束後，AI 會輸出一份完成摘要：
## Implementation Complete
**Change:** `add-todo-priority`
**Schema:** `tdd-driven-v2`
**Progress:** 12/12 tasks complete ✓
### Final Test Results
Test Suites: 3 passed, 3 total
Tests: 13 passed, 13 total
Coverage: 95.38%
如果 AI 沒用 subagent 模式
如果 AI 直接 inline 執行（跳過了 subagent dispatch），手動提醒它：
請使用 superpowers:subagent-driven-development skill 執行 apply 階段，不要使用 inline 執行。
這種情況在上下文窗口比較緊張時可能出現。
驗證點
✅ AI 使用了 subagent-driven-development 模式 ✅ 每個 task 有獨立的 subagent dispatch ✅ 每個 subagent 報告了測試輸出（RED 階段有失敗輸出，GREEN 階段有通過輸出）
圖 3：子代理調度與兩階段審查流程——每個 task 走 implementer → spec-reviewer → code-reviewer 三輪子代理
Step 5：人工驗收
AI 執行完了，但別急着歸檔。驗收這步不能省。
執行驗收命令
# 運行全部測試（如果已在 Step 1 配置了 npm pkg set scripts.test="jest"）
npm test
# 或者直接用 npx（不依賴 package.json 配置）
npx jest
# 檢查測試覆蓋率
npx jest --coverage
注意：如果你在 Step 1 沒有更新 package.json 的 test script，直接運行 npm test 會報錯。可以用 npx jest 代替，效果一樣。
# 查看 tasks 完成情況
cat openspec/changes/<change-name>/tasks.md
# 查看 git 提交記錄
git log --oneline
驗收檢查清單
逐項檢查：
[ ] npm test或npx jest全部通過[ ] tasks.md所有 checkbox 已勾選[ ] 測試覆蓋率 >= proposal 中的行為數量 [ ] 源碼文件結構與 design.md一致（或偏離可接受）[ ] 無 TODO 標記或未完成的樁代碼
不通過時怎麼辦
測試沒全過 → 讓 AI 修復失敗的測試，或手動修復
覆蓋率不足 → 參考 proposal.md 補充遺漏的測試用例
文件結構偏離 → 判斷偏離是否可接受。如果 AI 把兩個文件合併成一個，且功能正確，可以接受
有未完成的樁代碼 → 讓 AI 補全實現，或標記為下一個 change
Step 6：歸檔
驗收通過後，歸檔這次變更。
執行命令
/opsx:archive <change-name>
預期行為
AI 將 openspec/changes/<change-name>/ 移動到 openspec/changes/archive/YYYY-MM-DD-<change-name>/ 目錄下，自動添加日期前綴便於時間排序。
執行 /opsx:archive 後，AI 會輸出歸檔摘要：
## Archive Complete
**Change:** `add-todo-priority`
**Schema:** `tdd-driven-v2`
**Archived to:** `openspec/changes/archive/2026-05-06-add-todo-priority/`
**Specs:** No delta specs (main specs directory empty)
All artifacts complete. All 12 tasks complete.
驗證點
✅ openspec/changes/archive/ 下出現了帶日期前綴的歸檔目錄（如 2026-05-06-add-todo-priority/） ✅ 原活躍目錄已清理
關於 Spec 同步：archive 後 openspec/specs/ 目錄可能仍為空。這是因為 OpenSpec 的 spec 同步需要額外配置（如在 schema 中定義 sync 行為），當前版本的 TDD schema 沒有觸發自動同步。如果你需要將歸檔的 specs 累積到項目級知識庫，可以在 archive 後手動將 changes/archive/*/specs/ 下的文件複製到 openspec/specs/。
下一次 propose：archive 後目錄已清理，直接運行 /opsx:propose <新功能描述> 即可創建新的 change。已有的 TDD Schema（tdd-driven-v2）會被自動複用，無需重新配置。每個 change 的 specs、tasks、plan 都會獨立生成，互不干擾。
完整流程回顧
把 6 個步驟串起來：
初始化項目 → 創建 TDD Schema → /opsx:propose → 人工審查 → /opsx:apply → 人工驗收 → /opsx:archive
(Step 1) (Step 2) (Step 3) (必須做) (Step 4) (必須做) (Step 6)
對應的命令序列：
# Step 1: 初始化
mkdir my-project && cd my-project
git init && npm init -y
npm install --save-dev jest ts-jest @types/jest typescript
npm pkg set scripts.test="jest"
openspec init --tools claude
# Step 2: 創建 Schema（一次性配置）
mkdir -p openspec/schemas/tdd-driven-v2/templates
# 手動創建 schema.yaml、config.yaml 和 5 個模板文件
# Step 3: 生成規格
# 在 Claude Code 中: /opsx:propose "你的功能描述"
# 人工審查 proposal、design、tasks
# Step 4: 執行實現
# 在 Claude Code 中: /opsx:apply <change-name>
# Step 5: 人工驗收
npx jest && npx jest --coverage
# Step 6: 歸檔
# 在 Claude Code 中: /opsx:archive <change-name>
已知問題和應對
說實話，這個方案不是銀彈。v2 實測發現了 6 個已知侷限，需要在人工驗收階段兜底。
問題 1：部分 task 跳過了審查
AI 會選擇性跳過某些 task 的 spec-reviewer 和 code-reviewer，直接標記完成。跳過的不是"後幾個"，而是分散在中間——實測中 Task 8 和 Task 10 被跳過。
應對：apply 結束後，不要假設所有 task 都經過了審查。對照 session 日誌或 AI 輸出，確認每個 task 是否都有審查報告，跳過的部分手動補審。
問題 2：測試覆蓋率可能不足
實測中 15 個行為只覆蓋了 10 個，AI 跳過了部分邊界情況。
應對：對照 proposal.md 的 WHEN/THEN 列表，逐個檢查是否有對應測試，缺的補上。
問題 3：AI 可能自行調整文件結構
比如你在 design.md 裏規劃了兩個文件，AI 合併成了一個。這不一定錯，但偏離了設計。
應對：判斷偏離是否合理。如果功能正確、代碼質量沒問題，可以接受。
問題 4：apply 階段不產生 git 提交
實測中 apply 結束後 git log 沒有任何提交記錄。AI 在子代理模式下不做 git add/commit。
應對：apply 結束後手動驗收並提交：
git add -A
git commit -m "feat: implement <change-name> via OpenSpec + Superpowers TDD workflow"
問題 5：執行時間與需求複雜度不成比例
subagent-driven-development 的流程紀律開銷是系統性的。12 個 task 實測 64 分鐘，26 個 task 實測約 90 分鐘。即使簡單需求（如"給 interface 加一個字段"），每個 task 仍需三輪子代理審查。本質是用"流程紀律"換"代碼質量"。
應對：
對於簡單需求，可以修改 plan.md末尾的 Execution Mode Selection，使用 inline 模式而非 subagent-driven-development或者只在關鍵 task 上啓用審查，跳過簡單的 CRUD task apply 結束後人工驗收是不可省的，這是兜底環節
問題 6（接口一致性）：子代理模式下的 code review 可能遺漏接口定義不一致的問題。實測中 todo.model.ts 和 todo.service.ts 各自定義了不同的 Todo 接口（model 缺少 createdAt 字段），code reviewer 未發現。
應對：apply 結束後，特別檢查跨文件的接口/類型定義是否一致。如果多個文件引用同一數據結構，確認它們引用的是同一個 type/interface 定義，而不是各自重新定義。
適用場景分析
這個方案不是所有場景都適合。
適合：
純函數庫、工具函數 REST API（CRUD 類） CLI 工具 數據轉換/處理邏輯
需要謹慎：
前端 UI 組件（測試行為難以用 WHEN/THEN 表達） 依賴外部服務的功能（數據庫、第三方 API、文件系統） 時間緊迫的原型開發（Schema 配置 + 審查需要額外時間）
進階技巧
技巧一：複用 Schema
TDD Schema 配好一次就能複用。新建項目時只需要把 openspec/schemas/tdd-driven-v2/ 和 openspec/config.yaml 複製過去，改一下 config.yaml 裏的技術棧信息就行。
技巧二：config.yaml 的 context 越詳細越好
context 字段寫得越詳細，propose 階段的全自動率越高。核心函數簽名、輸入輸出類型、已有的工具函數列表 - 這些信息都能幫助 AI 一次生成正確的 proposal，省去多輪修改。
技巧三：propose 後審查是 ROI 很高的 5 分鐘
別跳過 propose 後的人工審查。特別是 tasks.md，一旦原子化約束沒生效，後續整個 apply 階段都會跑偏。5 分鐘的人工審查能省下 30 分鐘的返工。
總結
OpenSpec + Superpowers 的 TDD 協作方案，核心思路就一句話：讓 OpenSpec 把需求拆細，讓 Superpowers 把執行管嚴。
三次迭代，一次比一次清醒：v1 失敗教會了三個教訓（任務粒度必須原子化、兩套系統不能各自為戰、審查必須對齊需求）；v2 用 4 層防護驗證了原子化任務和 subagent 隔離的有效性（3/4 通過）；v3 在此基礎上沉澱為可複用的中文版 Schema，完整跑通了 propose → apply → archive 全流程。
這個方案用時間換質量——一箇中等功能可能要等 1 小時，但換來了 95%+ 的測試覆蓋率和完整的變更追溯。如果你在趕進度，它可能不是最優選；如果你在追求工程化，它值得一試。
如果你也在用 OpenSpec 或 Superpowers，歡迎在評論區聊聊你的使用體驗。
好啦，謝謝你觀看我的文章，如果喜歡可以點贊轉發給需要的朋友，我們下一期再見！敬請期待！
掃碼關注，獲取更多 AI 工具的實戰經驗和最佳實踐。不錯過每一篇乾貨！