AI 編程進階：三件套 OpenSpec 定方向，Superpowers 帶節奏，Agent Skills 守紀律，打造可預測的工程化工作流

AI 編程三件套

一套令 AI 編程由「撞彩」變成「可複製」嘅三件套工作流

開篇：AI 編程嘅「三體問題」

2026 年，AI 編程助手已經唔係新鮮事。Claude Code、Codex CLI、Cursor、Gemini CLI……每個工具都識幫你寫 Code。但用過嘅人都知一個殘酷嘅現實：

叫 AI 寫 100 行 Code 好易，叫 AI 高質量咁完成一個完整功能，好難。

問題出喺邊？三個致命短板：

1. 需求漂移 —— AI 喺 Chat 記錄度揾需求，傾嚇傾嚇就唔記得最初想做咩
2. 流程失控 —— AI 一嚟就寫 Code，冇設計、冇測試、冇審查，寫完就走
3. 紀律缺失 —— AI 今日用呢個風格寫，聽日轉第二個方式寫，Code 質素好似過山車咁

呢三個問題，啱啱對應咗三個 Open Source 項目嘅解決方案：

三個工具各自解決一個問題，組合埋一齊就係一套 AI 編程嘅「鐵三角」工作流。

本文會由零開始，帶你搭建呢套完整工作流。

第一章：認識三位主角

1.1 OpenSpec —— 用文檔定 AI

• GitHub: Fission-AI/OpenSpec
• Stars: 43.2k ⭐
• 最新版本: v1.3.1 (2026-04-21)
• 維護者: Fission AI (61 位貢獻者)
• 支援工具: 25+ AI 編程助手（Claude Code、Codex、Cursor、Gemini CLI、Copilot 等）

核心哲學：

喺人機之間先達成共識，再叫 AI 寫 Code。

OpenSpec 嘅本質係一個輕量級規範驅動開發 (Spec-Driven Development, SDD) 框架。佢唔係瀑布模型嗰啲又長又臭嘅需求文檔，而係一個「寫 Code 前先對齊預期」嘅輕量協議。

工作原理：

你說：/opsx:propose "添加暗黑模式"

AI 自動生成：
├── proposal.md     ← 為什麼要做，要改什麼
├── specs/          ← 需求場景和驗收標準
├── design.md       ← 技術方案
└── tasks.md        ← 實現任務清單

你審閲確認後：
/opsx:apply        ← AI 按 tasks.md 逐條實現

完成後：
/opsx:archive      ← 歸檔到 archive/，更新 specs

關鍵特性：

• Fluid, not rigid — 隨時可以更新任何文檔，冇嚴格嘅階段門禁
• Iterative, not waterfall — 支援漸進式疊代
• Built for brownfield — 唔止新 Project，舊 Project 都一樣用得
• Scalable — 由個人 Project 到企業級都得

OpenSpec 嘅核心命令：

對比競品：

• vs. GitHub Spec Kit：OpenSpec 更輕量，唔需要 Python 環境同嚴格嘅階段門禁
• vs. AWS Kiro：OpenSpec 唔鎖死 IDE，唔限制 Model
• vs. 唔用工具：就咁用 AI 就係賭運氣

1.2 Superpowers —— 用流程帶 AI

• GitHub: obra/superpowers
• Stars: 169k ⭐
• 最新版本: v5.0.7 (2026-03-31)
• 作者: Jesse Vincent (Prime Radiant)
• 支援平台: Claude Code、Codex CLI、Codex App、Cursor、OpenCode、Copilot CLI、Gemini CLI

核心哲學：

AI 唔應該「自由發揮」，而應該跟隨一套經過驗證嘅軟件工程流程。

Superpowers 唔係一個簡單嘅「提示詞合集」，佢係一套完整嘅軟件開發方法論，透過可組合嘅技能 (Skills) 驅動 AI 按照工程最佳實踐工作。

完整工作流：

1. brainstorming          ← 需求澄清與設計（Socratic 問答式）
   ↓
2. using-git-worktrees   ← 創建隔離開發環境（獨立 worktree + 新分支）
   ↓
3. writing-plans          ← 編寫詳細實現計劃（每個任務 2-5 分鐘）
   ↓
4. subagent-driven-dev    ← 子 Agent 並行開發（每個任務一個 agent）
   或 executing-plans     ← 批量執行（帶人工檢查點）
   ↓
5. test-driven-dev        ← 強制 RED-GREEN-REFACTOR 循環
   ↓
6. requesting-code-review ← 代碼審查（按嚴重程度分級）
   ↓
7. finishing-branch       ← 收尾：驗證測試、合併/PR/廢棄決策

關鍵設計理念（注意：以下都係「AI 行為約束」，唔係文件系統級鈎子）：

• 根據上下文主動選用 — Superpowers 將 Skill 嘅中繼資料注入 AGENTS.md 上下文，AI 模型執行任務時會按語義匹配主動調用對應 Skill；漏咗嘅話人可以顯式指定（例如「請先用 brainstorming 技能釐清」）
• 子 Agent 驅動開發 — 每個任務可以派發獨立子 Agent 執行，帶兩階段審查（規格一致性 + Code 質量）；主 Agent 仍然負責編排決策同失敗回收
• TDD 優先（唔係系統級強制） — test-driven-development Skill 引導 AI 先寫失敗測試再寫實現；如果發現已經有實現代碼違規，Superpowers 會指示模型撤回並按 RED-GREEN 順序補返。要做到「唔可以繞過」就要疊埋 git pre-commit / CI 閘門
• YAGNI + DRY 內置 — 工程最佳實踐以 Skill 形式提供畀 AI 參照，仍然以模型遵從為主，超大改動建議人嚟審

技能分類（共 15+ 個）：

安裝方式（按平台）：

# Claude Code (官方市場)
/plugin install superpowers@claude-plugins-official

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

# Codex CLI
/plugins → 搜索 superpowers → Install

# OpenCode
Fetch and follow instructions from
https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

1.3 Agent Skills —— 用紀律管 AI

• GitHub: addyosmani/agent-skills
• Stars: 24.3k ⭐
• 作者: Addy Osmani (Google Chrome 團隊工程總監)
• 技能數量: 20+ 個
• 核心創新: 7 命令技能生命週期管理

核心哲學：

AI Agent 需要「可編程嘅紀律」——唔係每次都手動提示，而係將最佳實踐編碼成可複用、可版本控制嘅技能。

Agent Skills 嘅定位係 SDLC 全流程覆蓋：由需求分析到生產部署，每個階段都有對應嘅技能嚟規範 AI 嘅行為。

7 命令技能生命週期：

init → verify → install → on → off → update → uninstall

呢個係 Agent Skills 最獨特嘅創新——唔係畀你一堆提示詞範本，而係提供一套完整嘅技能管理命令。你可以好似管理 npm 套件咁管理 AI 行為規則。

20 個技能分類：

關鍵約束示例：

# code-structure 技能的約束
- 每個源文件不超過 500 行
- 每個函數不超過 50 行
- 超過限制 → AI 必須自動拆分

# test-coverage 技能的約束
- 分支覆蓋率不低於 80%
- 不達標 → 不允許提交代碼
- 自動生成覆蓋率報告

安裝與使用：

# 初始化技能庫
agent-skills init

# 驗證技能格式
agent-skills verify

# 安裝所有技能
agent-skills install

# 啓用特定技能
agent-skills on test-coverage code-structure

# 停用（不想用的）
agent-skills off design-security

# 更新到最新
agent-skills update

# 卸載
agent-skills uninstall

第二章：三者點樣完美結合

2.1 關係模型

三個工具唔係競爭關係，而係工程流水線上嘅三個工位：

一句話總結：

• OpenSpec 管「講清楚」—— 喺你同 AI 之間建立一份書面契約
• Superpowers 管「做啱嘢」—— 確保 AI 每一步都行啱流程
• Agent Skills 管「做得好」—— 確保 AI 產出嘅 Code 符合工程標準

2.2 組合原則

三者組合時有三個關鍵原則：

原則一：層次分明，各司其職

原則二：順序執行，唔可以跳步

❌ 跳過 OpenSpec 直接寫 Code → 需求漂移
❌ 跳過 Superpowers 直接實現 → 流程混亂
❌ 跳過 Agent Skills 直接提交 → 質量失控

✅ 三步都做到 → 需求清晰、流程規範、質量可控

原則三：工具互補，避免衝突

• OpenSpec 嘅 tasks.md 係 Superpowers 中 writing-plans 的輸入
• Superpowers 嘅 subagent-driven-development 執行 Agent Skills 嘅紀律約束
• Agent Skills 嘅 production-ready 檢查 OpenSpec 嘅 spec 係咪被滿足

第三章：完整工作流實戰

3.1 總體流程圖

下面用「總覽 + 三個閘門子圖」表達同一條主鏈路：

• 總覽圖只回答：Step 1~8 嘅順序（唔展開回退細節）。
• 子圖只回答：當需求、評審、安全卡住時，返去邊度/停喺邊度（閉環要顯式）。

3.1.1 主鏈路總覽

3.1.2 閘門子圖 1：需求確認（/opsx:propose）

3.1.3 閘門子圖 2：Code 評審通過（requesting-code-review）

3.1.4 閘門子圖 3：安全失敗回退（security-* + 修復）

3.2 分步詳解：邊個喺咩時候做咩

本節用一份真實需求貫穿 8 步，所有 OpenSpec 製品片段都來自呢個倉庫 source/live-app-openspec-demo/openspec/changes/feat-live-share-third-party/，可以直接對照睇完整檔案。

真實輸入：產品需求表（節錄）

呢份需求最似真實業務文檔：欄位散、口徑模糊、隱含前提多。下面示範三件套點樣將佢一步步變成可執行、可驗收嘅工程產物。

▶ Step 1：需求對齊（OpenSpec 主導）

誰來做：人（發起）+ AI（生成）+ 人（審閲確認）

# 人在 AI 編碼助手中輸入
/opsx:propose "新增直播間分享到第三方渠道：微信/朋友圈/QQ/QQ 空間/微博，含底部面板、第三方授權期間直播保活、主播頭像 + 標題/兜底模板"

# ↑ OpenSpec 規則觸發，AI 不會寫代碼，
#   而是生成 4 類製品（proposal/spec/design/tasks）。

AI 自動生成（真實路徑，同呢個倉庫一致）：

source/live-app-openspec-demo/openspec/changes/feat-live-share-third-party/
├── proposal.md   ← 為什麼做、要改什麼、影響面
├── specs/
│   └── third-party-live-share/
│       └── spec.md   ← ADDED Requirements + Scenario
├── design.md     ← 關鍵工程決策、Open Questions
└── tasks.md      ← 實現清單（按編排/渠道/素材/保活/驗證 5 塊）

proposal.md 關鍵片段（真實檔案）：

# Change: feat-live-share-third-party

## Why
直播是拉新與迴流的高轉化場景，但用戶在房間內分享連結到主流社交渠道時，
常遇到「渠道未安裝」「授權跳轉後直播被誤停」「分享素材與直播間信息不一致」等問題。
產品需求表已明確分享渠道、面板交互與保活要求，需要以規範驅動方式在實現前對齊驗收口徑。

## What Changes
- 在直播房間內提供「分享」入口，彈出底部縱向渠道列表
  （微信、朋友圈、QQ、QQ 空間、微博），透明蒙層，點擊空白區域關閉面板。
- 選擇渠道前檢測目標 App 是否已安裝且滿足 SDK 最低版本；
  不滿足時給出可理解提示並可引導至應用商店（策略可配置）。
- 分享鏈路中不因進入第三方授權/編輯頁而主動停止直播推流或播放；
  用戶從第三方返回後仍停留在原直播間且狀態一致。
- 分享卡片縮略圖使用主播頭像；分享文案優先使用直播間標題，
  缺失時使用系統固定模板。

spec.md 關鍵片段（真實檔案，OpenSpec ADDED Requirements 語法）：

# Spec: third-party-live-share

## ADDED Requirements

### Requirement: 分享面板展示與關閉
用戶在直播房間內 MUST 能通過「分享」入口打開分享面板；
面板 MUST 自屏幕底部以縱向列表展示可選渠道；
MUST 顯示透明蒙層；
用戶點擊蒙層空白區域 MUST 關閉面板並恢復直播 UI 焦點。

#### Scenario: 打開與關閉面板
**WHEN** 用戶已進入直播間且直播進行中並點擊「分享」
**THEN** 系統 MUST 自底部展示包含微信、朋友圈、QQ、QQ 空間、微博的渠道列表
**AND** 系統 MUST 展示透明蒙層
**WHEN** 用戶點擊蒙層空白區域
**THEN** 系統 MUST 關閉分享面板並恢復直播房間交互焦點

### Requirement: 授權與分享期間直播保活
在用戶進入第三方授權、編輯或發佈流程期間，宿主 App MUST NOT 主動向音視頻模塊
發送「停止直播/停止推流」指令；除非操作系統強殺或用戶顯式結束直播，
直播核心狀態 MUST 與進入分享流程前保持一致。

#### Scenario: 跳轉第三方後返回
**WHEN** 用戶完成第三方側分享或取消並返回宿主 App
**THEN** 用戶 MUST 仍停留在原直播間
**AND** 直播狀態 MUST 與進入第三方前一致（未誤觸結束直播）

留意需求表裏面嗰句模糊嘅話：「保持 app 背景執行，直播狀態」。 spec 將佢翻譯成 MUST/MUST NOT 嘅可驗證條款：宿主禁止主動調用「停止直播」， 否則就係規格違反——呢一步消除咗最常見嘅「按需求理解嘅差異」.

⏱️ 呢一步耗時：人 5 分鐘審閲 + AI 30 秒生成 ✅ 完成標誌：你話「proposal/spec 我睇過，可以進入釐清」 ⚠️ 注意：呢個倉庫 README.md 裏面有真實 CLI 全過程，可以直接復刻： npx @fission-ai/openspec validate feat-live-share-third-party 必須返回 Change ... is valid。

▶ Step 2：需求釐清（Superpowers 主導 + Agent Skills 約束）

誰來做：AI 喺載入 brainstorming skill 之後主動進入 Socratic 模式向人反問；人淨係喺被問嘅時候回覆。 前提：Superpowers 已安裝兼且 skill 嘅中繼資料注入咗 AGENTS.md/系統上下文，否則 AI 仍然會直接進入實現。

需求表裏面啲「模糊詞」呢個時候會被 Superpowers 嘅 brainstorming 捉出嚟反問：

AI（Socratic 模式）：在進入實現前，先把以下口徑鎖住，否則 spec 會留歧義：

Q1. 「保持 app 後台運行」=  a) 宿主進程不被殺  /  b) 不向直播域發送停止指令？
    （決定保活策略與是否需要前台服務）
Q2. 「分享渠道列表」中微信與朋友圈是否合併到同一 SDK 入口（scene）？
Q3. 微博是否走官方 SDK，還是允許降級到系統 ACTION_SEND？
    （影響 design.md 與 tasks.md 的渠道矩陣）
Q4. 標題為空時的「系統固定模板」文案是什麼？誰審？
Q5. 縮略圖加載失敗的佔位圖由誰提供，圓角/尺寸是否在 UI 規範？

呢啲問題最終被沉澱到 design.md 的 Open Questions 中（真實檔案片段）：

## Open Questions
- 微博最終走「官方 SDK」還是「系統分享面板降級」——需產品 + 法務確認後回填到 spec.md
  （可能觸發 **MODIFIED** 塊）。

Agent Skills 嘅 req-clarify 喺背後約束：最多 3 輪釐清，超咗就強制總結並落到 Open Questions，避免無限討論。

⏱️ 呢一步耗時：人 5-10 分鐘回答 + AI 推理 1-2 分鐘 ✅ 完成標誌：design.md 含 Decisions + Open Questions，你話「確認」

▶ Step 3：分支隔離（Superpowers 主導）

誰來做：AI 調用 using-git-worktrees skill 執行（前提：倉庫已經係 git 倉庫兼且 using-git-worktrees skill 喺上下文中）

# AI 在 IDE Agent 模式下執行以下命令（不是 OS 鈎子，是 AI 調 bash）
git worktree add -b feat/live-share-third-party ../app-live-share
cd ../app-live-share

# 跑一次 baseline 防止髒狀態污染
./gradlew :app:assembleDebug
./gradlew test

呢一步非常關鍵——佢建立咗一個完全隔離嘅 workspace：

• 微信、QQ、微博三個 SDK 接入互不幹擾，可以分子任務並行開發；
• 多 ROM 兼容性迴歸（小米/華為/OPPO/vivo）失敗時，直接刪 worktree，主分支零污染；
• baseline 行通之後，後續 TDD 失敗實係新 Code 引入嘅，唔會同老問題混淆。

⏱️ 呢一步耗時：AI 執行命令 ~30 秒；baseline 編譯 + 測試取決於工程規模（數分鐘到十幾分鐘）

▶ Step 4：計劃制定（Superpowers 主導 + OpenSpec 提供輸入）

誰來做：AI 調用 writing-plans skill 生成計劃（前提：上一步已經生成嘅 tasks.md 喺倉庫內可讀）

Superpowers 嘅 writing-plans 讀取 OpenSpec 生成嘅 tasks.md（呢個倉庫真實檔案），將粗粒度任務細化為可執行計劃：

# Tasks: feat-live-share-third-party

## 1. 編排與 UI 骨架
- [ ] 1.1 定義 RoomContext 與 ShareCoordinator 入口 API
- [ ] 1.2 實現底部渠道面板 + 透明蒙層 + 點擊空白 dismiss（含無障礙焦點順序）
- [ ] 1.3 在直播間工具欄接入「分享」入口並埋點 share_panel_open

## 2. 渠道註冊與檢測
- [ ] 2.1 定義 ShareChannel 接口及 ShareChannelRegistry 註冊表
- [ ] 2.2 實現微信渠道：canShare（安裝 + 版本）與 share（SDK 調用佔位）
- [ ] 2.3 實現朋友圈渠道：與微信 SDK 的能力分支（scene / 類型）對齊
- [ ] 2.4 實現 QQ 與 QQ 空間渠道：安裝檢測與 SDK 喚起佔位
- [ ] 2.5 實現微博渠道：按設計「Open Questions」結論落地 SDK 或降級方案

## 3. 分享內容與網絡
- [ ] 3.1 實現 SharePayloadFactory：標題兜底模板、標題長度與截斷策略
- [ ] 3.2 主播頭像異步加載、緩存、失敗佔位圖與圓角裁切規範

## 4. 生命週期與保活
- [ ] 4.1 審計分享全鏈路：確保無任何路徑調用「停止直播/停止推流」除非用戶顯式結束
- [ ] 4.2 覆蓋從第三方返回後的 Activity / 棧恢復（多廠商 ROM 手動矩陣，記錄結果）

## 5. 驗證與發佈
- [ ] 5.1 按 specs/third-party-live-share/spec.md 中各 Scenario 編寫測試用例並執行
- [ ] 5.2 日誌與崩潰脱敏審計（無 token、無敏感 query）

每條任務都係「精確檔案/接口 + 驗收口徑」，唔係「寫一個分享功能」。 Agent Skills 嘅 req-breakdown 喺呢度約束：每個任務可以獨立驗證、可以獨立回滾。

⏱️ 呢一步耗時：AI 推理 1-2 分鐘（產出細化計劃文檔）

▶ Step 5：子 Agent 並行開發（Superpowers + Agent Skills 雙管齊下）

誰來做：主 Agent 編排 + 子 Agent 執行（人喺合併衝突、SDK 鑑權失敗、ROM 兼容迴歸卡住等場景下需要介入）

design.md 的 Decisions 已經將工程邊界劃好，子 Agent 拎到嘅係清晰約束（真實片段）：

## Decisions
1. 編排層命名與職責
   - Decision：引入 ShareCoordinator，持有 RoomContext
     （roomId、title、anchorAvatarUrl、streamStateHandle）。
   - Rationale：避免在 Fragment/ViewController 內散落 if (wechat) … ，便於單測與埋點。
2. 渠道抽象
   - Decision：ShareChannel 接口：id、displayName、icon、
     canShare(context) -> Result、share(context, payload)。
3. 保活策略
   - Decision：直播推流/播放的啓停 ONLY 由直播域 API 控制；
     分享流程禁止調用「結束直播」。

Superpowers 嘅 subagent-driven-development 將 5 大任務切成多個子 Agent：

每個子 Agent 行兩階段審查：規格一致性（必須對齊 spec.md 嘅 MUST 條款）+ Code 質量（命名/結構/異常）。

同時 Agent Skills 提供以下行為約束（仍然屬於模型遵從層，唔係檔案級強制）：

• code-structure：建議單檔案 ≤ 500 行、單函數 ≤ 50 行（避免「ShareCoordinator 一個檔案 2000 行」）；
• test-driven-development：每個 canShare() 行為先寫失敗測試再寫實現；
• code-documentation：ShareChannel 接口嘅所有公開方法必須有註釋。

要將呢三條變成「唔可以繞過」，需要將同樣嘅檢查複製到 pre-commit 與 CI（如 detekt / ktlint / 行數 lint / 文檔覆蓋率檢查），AI 行為 + CI 閘門雙保險先算真正強制。

⏱️ 呢一步耗時：15-30 分鐘（多渠道適配並行；含子 Agent 推理 + 編譯，唔包真機迴歸）

▶ Step 6：測試 + 審查（Superpowers 主導 + Agent Skills 量化）

誰來做：AI 調用 test-driven-development + requesting-code-review skill 執行（人審閲關鍵檢查點；CI 上同步行同一組測試與覆蓋率門檻先可以真正阻斷唔達標合入）

最關鍵嘅一條 spec：「分享期間直播保活」。Superpowers 嘅 TDD 用一段失敗測試將佢鎖死：

// 真實場景驅動的失敗測試（節選）
@Test
fun `分享流程期間不得向直播域發送停止指令`() {
    val streamSpy = StreamControlSpy()
    val coordinator = ShareCoordinator(streamControl = streamSpy)

    coordinator.present(roomContext)
    coordinator.onChannelSelected(ChannelId.WECHAT)
    // 模擬喚起微信授權頁 → 返回宿主
    coordinator.onReturnFromThirdParty()

    assertThat(streamSpy.stopInvocations).isEqualTo(0)   // RED ❌（還沒接保活策略）
}

行一遍：

$ ./gradlew :share:test# RED ❌
> 1 test failed:
  分享流程期間不得向直播域發送停止指令

# Superpowers 引導 AI 寫最少代碼（保活策略）後
$ ./gradlew :share:test# GREEN ✅
$ ./gradlew :share:test --rerun-tasks   # 再跑一遍，全綠

$ git commit -m "feat(share): keep stream alive across third-party flow"

之後係 Superpowers 嘅 requesting-code-review（按嚴重度分級）：

🔴 CRITICAL：無
🟡 WARNING：ShareCoordinator 在 onChannelSelected 時未對 RoomContext 做空檢查
🟢 INFO：建議把「微博 SDK 必選 / 可降級」抽成 BuildConfig 開關
📊 測試覆蓋率：分支 86%（≥ 80% ✅）

Agent Skills：

• test-coverage：要求分支覆蓋 ≥ 80%（AI 行為約束；要做到「唔達標禁止提交」就要將覆蓋率門檻配置到 CI，例如 jacoco + coverage-check 工作流）；
• test-quality：必須覆蓋 spec 裏面嘅 4 個核心 Scenario（打開/關閉、未安裝、版本不足、跳轉返回）。

⏱️ 呢一步耗時：5-10 分鐘（AI 行測試 + 自審）+ 人審閲 3 分鐘

▶ Step 7：安全檢查（Agent Skills 主導）

誰來做：AI 調用 security-* skills 執行（前提：Agent Skills 已 install 兼且對應 skill 已 enable；同一組檢查應同步入 CI 先可以唔繞過）

返去 spec.md 嘅真實條款：

### Requirement: 隱私與日誌
系統 MUST NOT 在日誌或崩潰報告中打印第三方 access_token、refresh_token
或可用於識別用戶的敏感授權字段。

Agent Skills 將佢落實成 3 個安全閘門：

security-secrets       → 掃描倉庫與崩潰日誌：0 access_token / refresh_token ✅
security-dependencies  → 微信/QQ/微博 SDK 已知漏洞：0 high / 0 critical ✅
security-api           → 分享請求審計：URL 不攜帶 token；UA 不含用戶 ID ✅

任何一項失敗 → AI 停低並報告；要做到「唔可以繞過嘅阻斷」就要將呢 3 項檢查同步落到 CI（如 gitleaks / trivy / OWASP Dependency-Check），同 3.1.4 嘅安全失敗閘門子圖配套生效。

⏱️ 呢一步耗時：1-2 分鐘（AI 觸發 skill 掃描；CI 上完整行可能更長）

▶ Step 8：驗證 + 收尾（三方協作）

誰來做：AI 主導 + 人最終確認

8a. OpenSpec 驗證：

$ npx @fission-ai/openspec validate feat-live-share-third-party
Change 'feat-live-share-third-party' is valid
Progress: 4/4 artifacts complete

/opsx:verify 會逐條對照 specs/third-party-live-share/spec.md 嘅 Scenario：

✅ Scenario: 打開與關閉面板
✅ Scenario: 目標 App 未安裝
✅ Scenario: SDK 版本不滿足
✅ Scenario: 跳轉第三方後返回
✅ Scenario: 標題缺失時的兜底
✅ Scenario: 調試日誌脱敏

8b. Agent Skills 生產就緒檢查：

✅ 單測/集成測全綠     ✅ 分支覆蓋 ≥ 80%
✅ 無 token/秘密泄漏    ✅ ROM 兼容矩陣已記錄
✅ 文案/標題兜底生效    ✅ 回滾開關：feature flag share_panel.enabled

8c. Superpowers 收尾（finishing-a-development-branch）：

All tasks complete. What would you like to do?
1. Merge branch
2. Create PR              ← 選擇
3. Keep branch
4. Discard branch

8d. OpenSpec 歸檔：

/opsx:archive
# 歸檔到：openspec/changes/archive/2026-04-27-feat-live-share-third-party/
# specs/third-party-live-share/ 主規格自動更新為「已發佈」狀態

⏱️ 呢一步耗時：2 分鐘（CLI 歸檔 + AI 觸發）+ 人決策 1 分鐘

⚠️ 邊界聲明：三件套係「行為約束」，唔係「系統級強制」

為咗避免讀者將上面 8 步當做「裝咗就搞掂」嘅銀彈，需要講清楚三件套嘅真實強度：

實務建議：

1. 關鍵質量門檻同時落兩層：例如「分支覆蓋率 ≥ 80%」同時寫入 test-coverage skill（叫 AI 寫 Code 時主動達標），亦配置到 CI（唔達標禁止合併）；
2. secrets / SDK 安全必須以 CI 閘門為準：gitleaks / trivy / OWASP Dependency-Check 等接入流水線，AI 嘅 security-* skill 只係早期發現；
3. AI 漏選 skill 時人要顯式指定：發現 AI 直接跳到寫 Code，明確話「請先用 brainstorming 釐清」或者「按 test-driven-development 先寫 RED 測試」；
4. 唔可以繞過嘅事唔好交畀 skill：刪除生產數據、改 migrations/、改 prod 配置、改 main 分支，呢啲用 git hook / 倉庫保護規則鎖住。

一句話：OpenSpec 嘅 validate 係程序性強制；Superpowers 與 Agent Skills 係 AI 行為約束。 將三者按強度分層，再用 CI 兜底，先係工程化、可靠交付嘅形態。

3.3 完整流程時間估算

時間口徑說明：以下"AI 推理"指模型喺 IDE Agent 模式下生成 + 調用 CLI 嘅累計耗時（唔包真機迴歸 / 真實 SDK 聯調 / CI 排隊）；分享到第三方呢啲含多 SDK 接入嘅場景實際可能更長。

其中人真正需要投入嘅時間：約 10-15 分鐘（主要喺 Step 1 審閲 spec 同 Step 6 審查關鍵檢查點）

第四章：安裝配置指南

4.1 環境準備

# 前置要求
node --version  # ≥ 20.19.0 (OpenSpec 要求)
git --version   # ≥ 2.30

4.2 安裝 OpenSpec

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

# 進入項目目錄，初始化
cd your-project
openspec init

# 生成 AGENTS.md（AI 助手的操作指南）
# 之後在 AI 編碼助手中即可使用 /opsx:* 命令

# 升級新版本
npm install -g @fission-ai/openspec@latest
openspec update   # 刷新 AI 指令

OpenSpec 支援嘅工具列表（部分）：

Claude Code · Codex CLI · Codex App · Cursor · Gemini CLI · Copilot · Windsurf · Cline · Roo Code · Amazon Q · CodeRabbit · Auggie · CoStrict · Amp · IBM Bob · CodeBuddy · Coffin · Factory · Qoder · Kilo Code · OpenCode · Qwen Code · Qoder · Trae

完整列表見：docs/supported-tools.md

4.3 安裝 Superpowers

根據你嘅 AI 編碼工具選擇安裝方式：

# Claude Code（推薦路徑）
/plugin install superpowers@claude-plugins-official

# 或者通過 Superpowers 自己的市場
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# GitHub Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

# 更新
# Claude Code 插件通常自動更新
# Gemini CLI:
gemini extensions update superpowers

安裝驗證：啟動 AI 編碼工具之後，隨便講一句「我想做一個新功能」，如果 AI 開始反問你嘅需求而唔係直接寫 Code，就代表 Superpowers 已生效。

4.4 安裝 Agent Skills

# 克隆倉庫
git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

# 初始化技能庫（生成默認配置）
agent-skills init

# 驗證技能格式（確保所有 SKILL.md 語法正確）
agent-skills verify

# 安裝所有技能到 AI 工作目錄
agent-skills install

# 啓用你需要的技能
agent-skills on test-coverage code-structure code-documentation \
           design-architect design-api \
           security-dependencies security-secrets \
           production-ready

# 停用暫時不需要的技能（減少上下文消耗）
agent-skills off design-security code-incident-review

# 更新技能到最新版本
agent-skills update

注意：技能會消耗 AI 嘅上下文視窗（token）。建議初期只啟用 5-8 個最核心嘅技能，後續按需要逐步添加。

第五章：實戰演練 —— 完整案例

等我哋用一個教學向嘅完整案例嚟串起成條鏈路（同第三章「分享直播到第三方」嘅真實 spec 可對照閲讀；本章側重對話與步驟嘅樣貌）。

口徑：下文嘅「自動」指 AI 喺已安裝 OpenSpec 指令、Superpowers 與相關 skill 已注入上下文時嘅典型表現，屬於模型行為而非系統鈎子；唔可以繞過嘅質量門檻仍然應該以 CLI 與 CI 閘門 為準，見第三章「邊界聲明」。

背景

你維護一個 React + TypeScript 嘅 Dashboard 項目。用戶反映希望增加「數據導出為 CSV」功能。

全流程實際操作

5.1 發起提案

👤 你（在 Claude Code 中）：
/opsx:propose "Dashboard 數據導出為 CSV 功能"

🤖 AI（OpenSpec 指令生效）：
正在生成提案…
✓ proposal.md 已創建
✓ specs/csv-export/spec.md 已創建
✓ design.md 已創建
✓ tasks.md 已創建

5.2 審閲 + 確認

# specs/csv-export/spec.md

## Scenario: 用戶在 Dashboard 中導出選中數據
Given 用戶在 Dashboard 頁面，已選中 3 條記錄
When 用戶點擊 "導出 CSV" 按鈕
Then 瀏覽器下載一個 CSV 文件
And 文件包含選中的 3 條記錄
And 文件名格式為 export-YYYY-MM-DD.csv

## Scenario: 未選中任何記錄時導出
Given 用戶在 Dashboard 頁面，未選中任何記錄
When 用戶點擊 "導出 CSV" 按鈕
Then 顯示 Toast 提示 "請先選擇要導出的數據"
And 不觸發下載

👤 你：確認提案，並補充一個場景：導出超過 10000 條時顯示進度條

🤖 AI：已添加 Scenario: 大數據量導出顯示進度

5.3 Superpowers 介入（需求釐清）

🤖 AI（加載了 brainstorming 等 skill 時，通常會先問清楚）：

在開始實現前，我想確認幾個細節：

1. CSV 文件編碼用什麼？UTF-8 還是 UTF-8 BOM（Excel 兼容）？
2. 需要支持自定義導出字段嗎？還是所有可見列都導出？
3. 數據中的逗號和換行符如何處理？
4. 是否需要後台異步導出（大文件場景）？

5.4 分支隔離 + 計劃制定

🤖 AI（在 using-git-worktrees、writing-plans 等技能可用時）：

✓ 創建 worktree: /tmp/project-csv-export
✓ 切換到新分支: feature/csv-export
✓ Clean test baseline: 42 tests passing

（基於 OpenSpec 的 tasks.md，細化實現計劃）

📋 實現計劃：

Task 1: 創建 CSV 工具函數 (約 3 min)
  - 文件: src/utils/csv.ts
  - 包含: escapeCSV, generateCSV, downloadCSV

Task 2: 添加導出按鈕 (約 2 min)
  - 文件: src/components/DashboardToolbar.tsx
  - 添加 "導出 CSV" 按鈕 + 未選中時禁用邏輯

Task 3: 集成到 Dashboard (約 3 min)
  - 文件: src/pages/Dashboard.tsx
  - 獲取選中數據 → 調用 generateCSV → 觸發下載

Task 4: 大數據量進度條 (約 4 min)
  - 文件: src/components/ExportProgress.tsx
  - 進度條組件 + Web Worker 異步處理

Task 5: 單元測試 (約 3 min)
  - 文件: src/utils/csv.test.ts
  - 覆蓋: 正常導出、空數據、特殊字符、10000+ 條

5.5 子 Agent 並行開發

🤖 AI（subagent-driven-development 可並行派發子任務，主 Agent 負責合併與解決衝突）：

[Agent-1] 處理 Task 1: CSV 工具函數
  ✓ 寫入 src/utils/csv.ts (87 行)
  📏 code-structure: 文件 87 行 ≤ 500，函數最大 22 行 ≤ 50（為 AI 行為約束，合入時建議 CI 再跑同樣規則）
  🔍 審查 1 (規格): 符合 spec
  🔍 審查 2 (質量): 代碼清晰，無明顯問題

[Agent-2] 處理 Task 2: 導出按鈕
  ✓ 寫入 src/components/DashboardToolbar.tsx
  …

[Agent-3] 處理 Task 5: 單元測試
  ✓ RED: 先失敗再實現（TDD）
  ✓ GREEN: 14 個測試全部 PASS
  📊 test-coverage: 分支覆蓋率 91%（以本地/CI 報告為準）

全部 5 個任務完成

5.6 測試 + 審查

🤖 AI：

🧪 運行全部測試…
  56 tests passing（原 42 + 新 14）

🔍 代碼審查:
  🟡 WARNING: csv.ts 的 escapeCSV 建議增加 null/undefined 處理
  → 已修正

🔒 安全檢查（security-* 已 enable 時）:
  依賴/秘密/API 掃描無阻斷項則繼續

5.7 驗證 + 收尾

👤 你：/opsx:verify

🤖 AI：對照 spec csv-export
  各 Scenario 與實現一致則標記通過

👤 你：需要創建 PR

/opsx:archive
  將變更按團隊規範歸檔；主 spec 隨團隊流程更新

總耗時：約 40 分鐘量級嘅演示口徑（人實際投入因審 spec、撳合併而異）

第六章：進階技巧與最佳實踐

6.1 跳過某啲步驟嘅藝術

唔係每個變更都需要全套流程。教你判斷：

6.2 模型選擇建議

• 規劃階段（/opsx:propose 等）：傾向高推理、長上下文的模型，減少 spec 歧義
• 實現階段（/opsx:apply）：可以在質量唔跌嘅前提下用成本更低嘅模型
• 子 Agent：通常繼承主會話模型；並行時注意 token 同合併成本

6.3 上下文視窗管理

Agent Skills 會消耗 token，建議：

# 初期：只啓用最核心的 5-8 個技能
agent-skills on \
  test-coverage \
  code-structure \
  code-documentation \
  security-secrets \
  production-ready

# 需求階段再加
agent-skills on req-clarify req-breakdown

# 需求完成後關閉（釋放上下文）
agent-skills off req-clarify req-breakdown

OpenSpec 亦建議喺實現前清理無關對話，保持可驗證嘅乾淨上下文。

6.4 團隊協作模式

關鍵：OpenSpec 嘅文檔層可以做團隊書面契約；

Superpowers 幫手將實現過程拆成可並行嘅子任務；

Agent Skills 主要降低風格與低級問題嘅反覆拉扯

——合入前仍然應該保留 Code Review 與 CI（同第三章邊界聲明一致，尤其係安全與業務關鍵路徑）。

第七章：與手動編碼嘅效率對比

下面用同一條功能線做量級對比，數字係教學示意，以你團隊真實工時為準；「三件套」行嘅優勢在於可預測、可歸檔、可迴歸，而唔止係快。

核心差異唔係「永遠更快」，而係：

• 可預測性：同樣流程行多幾次，質量方差更細
• 可追溯性：關鍵決策有 proposal / spec 可以查
• 可複製性：換功能、換人，同一套檢查清單仍可用

第八章：常見問題

Q1: 呢三個工具必須一齊用咩？

不必須。可以漸進式採用：

Phase 1: 先用 OpenSpec（先解決需求對齊）
Phase 2: + Superpowers（加流程與協作節奏）
Phase 3: + Agent Skills（加質量與約束）

由 OpenSpec 開始通常最自然——佢壓住嘅係需求漂移呢個根本問題。

Q2: 細項目都需要咁重嘅流程咩？

對唔夠 100 行嘅細改動，可以簡化但建議保留底線：

• OpenSpec：至少寫清「改咩、點解」
• Superpowers：盡量唔好畀 TDD/驗證被跳過大段
• Agent Skills：至少保留 test-coverage、security-secrets 等同你風險匹配嘅子集

Q3: Agent Skills 同 Superpowers 嘅技能有咩分別？

簡單說：Superpowers 更偏「推進方式」，Agent Skills 更偏「結果似咩樣」；二者疊埋時，流程優先、紀律落在每一步嘅產出上；衝突時以團隊規範與 CI 為準。

Q4: 遇到 AI 唔按要求做咁點算？

Q5: 如何處理 Agent Skills 同 Superpowers 嘅潛在衝突？

通常唔矛盾：一個管「步驟與拆分」，一個管「每一步嘅 Code 形態」。如果真係有張力（例如並行 vs 順序），以團隊合入規範與 CI 為最終裁判，喺文檔中固定一種打法。

總結：AI 編程嘅「鐵三角」

開始使用嘅建議路徑

Week 1: 安裝 OpenSpec，在幾個小功能上試用 propose → apply → verify → archive
Week 2: 安裝 Superpowers，體會「先問再寫」與任務拆分的差異
Week 3: 安裝 Agent Skills，只開少量核心，觀察覆蓋率與結構約束
Week 4: 用三件套跑通一箇中等功能，並把關鍵檢查項同步到 CI

最後嘅忠告

呢啲工具唔係銀彈。佢哋可以幫你：

• 叫 AI 喺你寫清嘅邊界裏發揮
• 讓過程可重複、可審計（尤其係 OpenSpec 歸檔）
• 讓代碼更易測、更易審（Skills + 人審 + CI）

佢哋替代唔到：業務判斷、系統取捨、最終合入與線上責任。

更好嘅工作流 = 人定方向 + 流程管過程 + 紀律（含 CI）保質量。

三件套令結果由「撞彩」更接近「可複製」；方向盤仍然喺人手裏。

你可以點樣做下一步

• 如果未試過：用本文第五章嘅 CSV 導出 行一遍，再對照第三章 feat-live-share-third-party 睇「真實 spec 似咩樣」.
• 如果已經喺團隊使用：將第三章「邊界聲明」貼入內部 wiki，同 Code Review、CI 清單 對齊，避免將 Skills 當成「免審金牌」.

參考資源

• OpenSpec: https://github.com/Fission-AI/OpenSpec | https://openspec.dev
• Superpowers: https://github.com/obra/superpowers
• Agent Skills: https://github.com/addyosmani/agent-skills

截稿與 Star 等數據易變，以各倉庫 Release / 官方說明為準。

AI 編程三件套

一套讓 AI 編程從「碰運氣」變成「可複製」的三件套工作流

開篇：AI 編程的「三體問題」

2026 年，AI 編程助手已經不再是新鮮事。Claude Code、Codex CLI、Cursor、Gemini CLI……每個工具都能幫你寫代碼。但用過的人都知道一個殘酷的現實：

讓 AI 寫 100 行代碼容易，讓 AI 高質量地完成一個完整功能，難。

問題出在哪？三個致命短板：

1. 需求漂移 —— AI 在聊天記錄裏找需求，聊着聊着就忘了最初要做什麼
2. 流程失控 —— AI 上來就寫代碼，沒有設計、沒有測試、沒有審查，寫完就跑
3. 紀律缺失 —— AI 今天用這個風格寫，明天換那個方式寫，代碼質量像過山車

這三個問題，恰好對應了三個開源項目的解決方案：

三個工具各自解決一個問題，組合起來就是一套 AI 編程的「鐵三角」工作流。

本文將從零開始，帶你搭建這套完整工作流。

第一章：認識三位主角

1.1 OpenSpec —— 用文檔定 AI

• GitHub: Fission-AI/OpenSpec
• Stars: 43.2k ⭐
• 最新版本: v1.3.1 (2026-04-21)
• 維護者: Fission AI (61 位貢獻者)
• 支持工具: 25+ AI 編程助手（Claude Code、Codex、Cursor、Gemini CLI、Copilot 等）

核心哲學：

在人機之間先達成共識，再讓 AI 寫代碼。

OpenSpec 的本質是一個輕量級規範驅動開發 (Spec-Driven Development, SDD) 框架。它不是瀑布模型那種又臭又長的需求文檔，而是一個「在寫代碼前先對齊預期」的輕量協議。

工作原理：

你說：/opsx:propose "添加暗黑模式"

AI 自動生成：
├── proposal.md     ← 為什麼要做，要改什麼
├── specs/          ← 需求場景和驗收標準
├── design.md       ← 技術方案
└── tasks.md        ← 實現任務清單

你審閲確認後：
/opsx:apply        ← AI 按 tasks.md 逐條實現

完成後：
/opsx:archive      ← 歸檔到 archive/，更新 specs

關鍵特性：

• Fluid, not rigid — 隨時可更新任何文檔，沒有嚴格的階段門禁
• Iterative, not waterfall — 支持漸進式迭代
• Built for brownfield — 不只是新項目，老項目同樣適用
• Scalable — 從個人項目到企業級都行

OpenSpec 的核心命令：

對比競品：

• vs. GitHub Spec Kit：OpenSpec 更輕量，不需要 Python 環境和嚴格的階段門禁
• vs. AWS Kiro：OpenSpec 不鎖定 IDE，不限制模型
• vs. 不用工具：裸用 AI 就是賭運氣

1.2 Superpowers —— 用流程帶 AI

• GitHub: obra/superpowers
• Stars: 169k ⭐
• 最新版本: v5.0.7 (2026-03-31)
• 作者: Jesse Vincent (Prime Radiant)
• 支持平台: Claude Code、Codex CLI、Codex App、Cursor、OpenCode、Copilot CLI、Gemini CLI

核心哲學：

AI 不應該「自由發揮」，而應該遵循一套經過驗證的軟件工程流程。

Superpowers 不是一個簡單的「提示詞合集」，它是一套完整的軟件開發方法論，通過可組合的技能 (Skills) 驅動 AI 按照工程最佳實踐工作。

完整工作流：

1. brainstorming          ← 需求澄清與設計（Socratic 問答式）
   ↓
2. using-git-worktrees   ← 創建隔離開發環境（獨立 worktree + 新分支）
   ↓
3. writing-plans          ← 編寫詳細實現計劃（每個任務 2-5 分鐘）
   ↓
4. subagent-driven-dev    ← 子 Agent 並行開發（每個任務一個 agent）
   或 executing-plans     ← 批量執行（帶人工檢查點）
   ↓
5. test-driven-dev        ← 強制 RED-GREEN-REFACTOR 循環
   ↓
6. requesting-code-review ← 代碼審查（按嚴重程度分級）
   ↓
7. finishing-branch       ← 收尾：驗證測試、合併/PR/廢棄決策

關鍵設計理念（注意：以下均屬「AI 行為約束」，不是文件系統級鈎子）：

• 基於上下文主動選用 — Superpowers 把 skill 元數據注入到 AGENTS.md 上下文，AI 模型在執行任務時按語義匹配主動調用對應 skill；漏選時人可顯式指定（例如「請先用 brainstorming 技能澄清」）
• 子 Agent 驅動開發 — 每個任務可派發獨立子 Agent 執行，帶兩階段審查（規格一致性 + 代碼質量）；主 Agent 仍負責編排決策與失敗回收
• TDD 優先（非系統級強制） — test-driven-development skill 引導 AI 先寫失敗測試再寫實現；若發現違規已生成的實現代碼，Superpowers 會指示模型撤回並按 RED-GREEN 順序補上。要做到「不可繞過」需疊加 git pre-commit / CI 閘門
• YAGNI + DRY 內建 — 工程最佳實踐以 skill 形式提供給 AI 參照，仍以模型遵從為主，超大改動建議人審

技能分類（共 15+ 個）：

安裝方式（按平台）：

# Claude Code (官方市場)
/plugin install superpowers@claude-plugins-official

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

# Codex CLI
/plugins → 搜索 superpowers → Install

# OpenCode
Fetch and follow instructions from
https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

1.3 Agent Skills —— 用紀律管 AI

• GitHub: addyosmani/agent-skills
• Stars: 24.3k ⭐
• 作者: Addy Osmani (Google Chrome 團隊工程總監)
• 技能數量: 20+ 個
• 核心創新: 7 命令技能生命週期管理

核心哲學：

AI Agent 需要「可編程的紀律」——不是每次手動提示，而是把最佳實踐編碼為可複用、可版本控制的技能。

Agent Skills 的定位是 SDLC 全流程覆蓋：從需求分析到生產部署，每個階段都有對應的技能來規範 AI 的行為。

7 命令技能生命週期：

init → verify → install → on → off → update → uninstall

這是 Agent Skills 最獨特的創新——不是給你一堆提示詞模板，而是提供一套完整的技能管理命令。你可以像管理 npm 包一樣管理 AI 行為規則。

20 個技能分類：

關鍵約束示例：

# code-structure 技能的約束
- 每個源文件不超過 500 行
- 每個函數不超過 50 行
- 超過限制 → AI 必須自動拆分

# test-coverage 技能的約束
- 分支覆蓋率不低於 80%
- 不達標 → 不允許提交代碼
- 自動生成覆蓋率報告

安裝與使用：

# 初始化技能庫
agent-skills init

# 驗證技能格式
agent-skills verify

# 安裝所有技能
agent-skills install

# 啓用特定技能
agent-skills on test-coverage code-structure

# 停用（不想用的）
agent-skills off design-security

# 更新到最新
agent-skills update

# 卸載
agent-skills uninstall

第二章：三者如何完美結合

2.1 關係模型

三個工具不是競爭關係，而是工程流水線上的三個工位：

一句話總結：

• OpenSpec 管「說清楚」—— 在你和 AI 之間建立一份書面契約
• Superpowers 管「做對事」—— 確保 AI 每一步都走對流程
• Agent Skills 管「做得好」—— 確保 AI 產出的代碼符合工程標準

2.2 組合原則

三者組合時有三個關鍵原則：

原則一：層次分明，各司其職

原則二：順序執行，不可跳躍

❌ 跳過 OpenSpec 直接寫代碼 → 需求漂移
❌ 跳過 Superpowers 直接實現 → 流程混亂
❌ 跳過 Agent Skills 直接提交 → 質量失控

✅ 三步都做到 → 需求清晰、流程規範、質量可控

原則三：工具互補，避免衝突

• OpenSpec 的 tasks.md 是 Superpowers 中 writing-plans 的輸入
• Superpowers 的 subagent-driven-development 執行 Agent Skills 的紀律約束
• Agent Skills 的 production-ready 檢查 OpenSpec 的 spec 是否被滿足

第三章：完整工作流實操

3.1 總體流程圖

下面用「總覽 + 三個閘門子圖」表達同一條主鏈路：

• 總覽圖只回答：Step 1~8 的順序（不展開回退細節）。
• 子圖只回答：當需求、評審、安全卡住時，回到哪裏/停在哪裏（閉環要顯式）。

3.1.1 主鏈路總覽

3.1.2 閘門子圖 1：需求確認（/opsx:propose）

3.1.3 閘門子圖 2：代碼評審通過（requesting-code-review）

3.1.4 閘門子圖 3：安全失敗回退（security-* + 修復）

3.2 分步詳解：誰在什麼時候做什麼

本節用一份真實需求貫穿 8 步，所有 OpenSpec 製品片段均來自本倉庫 source/live-app-openspec-demo/openspec/changes/feat-live-share-third-party/，可直接對照查看完整文件。

真實輸入：產品需求表（節選）

這份需求最像真實業務文檔：字段散、口徑模糊、隱含前提多。下面演示三件套如何把它一步步變成可執行、可驗收的工程產物。

▶ Step 1：需求對齊（OpenSpec 主導）

誰來做：人（發起）+ AI（生成）+ 人（審閲確認）

# 人在 AI 編碼助手中輸入
/opsx:propose "新增直播間分享到第三方渠道：微信/朋友圈/QQ/QQ 空間/微博，含底部面板、第三方授權期間直播保活、主播頭像 + 標題/兜底模板"

# ↑ OpenSpec 規則觸發，AI 不會寫代碼，
#   而是生成 4 類製品（proposal/spec/design/tasks）。

AI 自動生成（真實路徑，與本倉庫一致）：

source/live-app-openspec-demo/openspec/changes/feat-live-share-third-party/
├── proposal.md   ← 為什麼做、要改什麼、影響面
├── specs/
│   └── third-party-live-share/
│       └── spec.md   ← ADDED Requirements + Scenario
├── design.md     ← 關鍵工程決策、Open Questions
└── tasks.md      ← 實現清單（按編排/渠道/素材/保活/驗證 5 塊）

proposal.md 關鍵片段（真實文件）：

# Change: feat-live-share-third-party

## Why
直播是拉新與迴流的高轉化場景，但用戶在房間內分享連結到主流社交渠道時，
常遇到「渠道未安裝」「授權跳轉後直播被誤停」「分享素材與直播間信息不一致」等問題。
產品需求表已明確分享渠道、面板交互與保活要求，需要以規範驅動方式在實現前對齊驗收口徑。

## What Changes
- 在直播房間內提供「分享」入口，彈出底部縱向渠道列表
  （微信、朋友圈、QQ、QQ 空間、微博），透明蒙層，點擊空白區域關閉面板。
- 選擇渠道前檢測目標 App 是否已安裝且滿足 SDK 最低版本；
  不滿足時給出可理解提示並可引導至應用商店（策略可配置）。
- 分享鏈路中不因進入第三方授權/編輯頁而主動停止直播推流或播放；
  用戶從第三方返回後仍停留在原直播間且狀態一致。
- 分享卡片縮略圖使用主播頭像；分享文案優先使用直播間標題，
  缺失時使用系統固定模板。

spec.md 關鍵片段（真實文件，OpenSpec ADDED Requirements 語法）：

# Spec: third-party-live-share

## ADDED Requirements

### Requirement: 分享面板展示與關閉
用戶在直播房間內 MUST 能通過「分享」入口打開分享面板；
面板 MUST 自屏幕底部以縱向列表展示可選渠道；
MUST 顯示透明蒙層；
用戶點擊蒙層空白區域 MUST 關閉面板並恢復直播 UI 焦點。

#### Scenario: 打開與關閉面板
**WHEN** 用戶已進入直播間且直播進行中並點擊「分享」
**THEN** 系統 MUST 自底部展示包含微信、朋友圈、QQ、QQ 空間、微博的渠道列表
**AND** 系統 MUST 展示透明蒙層
**WHEN** 用戶點擊蒙層空白區域
**THEN** 系統 MUST 關閉分享面板並恢復直播房間交互焦點

### Requirement: 授權與分享期間直播保活
在用戶進入第三方授權、編輯或發佈流程期間，宿主 App MUST NOT 主動向音視頻模塊
發送「停止直播/停止推流」指令；除非操作系統強殺或用戶顯式結束直播，
直播核心狀態 MUST 與進入分享流程前保持一致。

#### Scenario: 跳轉第三方後返回
**WHEN** 用戶完成第三方側分享或取消並返回宿主 App
**THEN** 用戶 MUST 仍停留在原直播間
**AND** 直播狀態 MUST 與進入第三方前一致（未誤觸結束直播）

注意需求表裏那行模糊的話：「保持 app 後台運行，直播狀態」。 spec 把它翻譯成 MUST/MUST NOT 的可驗證條款：宿主禁止主動調用「停止直播」， 否則就是規格違反——這一步消除了最常見的「按需求理解的差異」。

⏱️ 這一步耗時：人 5 分鐘審閲 + AI 30 秒生成 ✅ 完成標誌：你說「proposal/spec 我看過了，可以進入澄清」 ⚠️ 注意：本倉庫 README.md 裏有真實 CLI 全過程，可直接復刻： npx @fission-ai/openspec validate feat-live-share-third-party 必須返回 Change ... is valid。

▶ Step 2：需求澄清（Superpowers 主導 + Agent Skills 約束）

誰來做：AI 在加載 brainstorming skill 後主動進入 Socratic 模式向人反問；人只在被詢問時回覆。 前提：Superpowers 已安裝且 skill 元數據注入到 AGENTS.md/系統上下文，否則 AI 仍會直接進入實現。

需求表裏那些「模糊詞」此時會被 Superpowers 的 brainstorming 抓出來反問：

AI（Socratic 模式）：在進入實現前，先把以下口徑鎖住，否則 spec 會留歧義：

Q1. 「保持 app 後台運行」=  a) 宿主進程不被殺  /  b) 不向直播域發送停止指令？
    （決定保活策略與是否需要前台服務）
Q2. 「分享渠道列表」中微信與朋友圈是否合併到同一 SDK 入口（scene）？
Q3. 微博是否走官方 SDK，還是允許降級到系統 ACTION_SEND？
    （影響 design.md 與 tasks.md 的渠道矩陣）
Q4. 標題為空時的「系統固定模板」文案是什麼？誰審？
Q5. 縮略圖加載失敗的佔位圖由誰提供，圓角/尺寸是否在 UI 規範？

這些問題最終被沉澱到 design.md 的 Open Questions 中（真實文件片段）：

## Open Questions
- 微博最終走「官方 SDK」還是「系統分享面板降級」——需產品 + 法務確認後回填到 spec.md
  （可能觸發 **MODIFIED** 塊）。

Agent Skills 的 req-clarify 在背後約束：最多 3 輪澄清，超了就強制總結並落到 Open Questions，避免無限討論。

⏱️ 這一步耗時：人 5-10 分鐘回答 + AI 推理 1-2 分鐘 ✅ 完成標誌：design.md 含 Decisions + Open Questions，你說「確認」

▶ Step 3：分支隔離（Superpowers 主導）

誰來做：AI 調用 using-git-worktrees skill 執行（前提：倉庫已是 git 倉庫且 using-git-worktrees skill 在上下文裏）

# AI 在 IDE Agent 模式下執行以下命令（不是 OS 鈎子，是 AI 調 bash）
git worktree add -b feat/live-share-third-party ../app-live-share
cd ../app-live-share

# 跑一次 baseline 防止髒狀態污染
./gradlew :app:assembleDebug
./gradlew test

這一步非常關鍵——它創建了一個完全隔離的 workspace：

• 微信、QQ、微博三個 SDK 接入互不干擾，可以分子任務並行開發；
• 多 ROM 兼容性迴歸（小米/華為/OPPO/vivo）失敗時，直接刪 worktree，主分支零污染；
• baseline 跑通後，後續 TDD 失敗一定是新代碼引入的，不會和老問題混淆。

⏱️ 這一步耗時：AI 調命令 ~30 秒；baseline 編譯 + 測試取決於工程規模（數分鐘到十幾分鍾）

▶ Step 4：計劃制定（Superpowers 主導 + OpenSpec 提供輸入）

誰來做：AI 調用 writing-plans skill 生成計劃（前提：上一步已生成的 tasks.md 在倉庫內可讀）

Superpowers 的 writing-plans 讀取 OpenSpec 生成的 tasks.md（本倉庫真實文件），把粗粒度任務細化為可執行計劃：

# Tasks: feat-live-share-third-party

## 1. 編排與 UI 骨架
- [ ] 1.1 定義 RoomContext 與 ShareCoordinator 入口 API
- [ ] 1.2 實現底部渠道面板 + 透明蒙層 + 點擊空白 dismiss（含無障礙焦點順序）
- [ ] 1.3 在直播間工具欄接入「分享」入口並埋點 share_panel_open

## 2. 渠道註冊與檢測
- [ ] 2.1 定義 ShareChannel 接口及 ShareChannelRegistry 註冊表
- [ ] 2.2 實現微信渠道：canShare（安裝 + 版本）與 share（SDK 調用佔位）
- [ ] 2.3 實現朋友圈渠道：與微信 SDK 的能力分支（scene / 類型）對齊
- [ ] 2.4 實現 QQ 與 QQ 空間渠道：安裝檢測與 SDK 喚起佔位
- [ ] 2.5 實現微博渠道：按設計「Open Questions」結論落地 SDK 或降級方案

## 3. 分享內容與網絡
- [ ] 3.1 實現 SharePayloadFactory：標題兜底模板、標題長度與截斷策略
- [ ] 3.2 主播頭像異步加載、緩存、失敗佔位圖與圓角裁切規範

## 4. 生命週期與保活
- [ ] 4.1 審計分享全鏈路：確保無任何路徑調用「停止直播/停止推流」除非用戶顯式結束
- [ ] 4.2 覆蓋從第三方返回後的 Activity / 棧恢復（多廠商 ROM 手動矩陣，記錄結果）

## 5. 驗證與發佈
- [ ] 5.1 按 specs/third-party-live-share/spec.md 中各 Scenario 編寫測試用例並執行
- [ ] 5.2 日誌與崩潰脱敏審計（無 token、無敏感 query）

每條任務都是「精確文件/接口 + 驗收口徑」，不是「寫一個分享功能」。 Agent Skills 的 req-breakdown 在此約束：每個任務可獨立驗證、可獨立回滾。

⏱️ 這一步耗時：AI 推理 1-2 分鐘（產出細化計劃文檔）

▶ Step 5：子 Agent 並行開發（Superpowers + Agent Skills 雙管齊下）

誰來做：主 Agent 編排 + 子 Agent 執行（人在合併衝突、SDK 鑑權失敗、ROM 兼容迴歸卡住等場景下需要介入）

design.md 的 Decisions 已經把工程邊界劃好，子 Agent 拿到的是清晰約束（真實片段）：

## Decisions
1. 編排層命名與職責
   - Decision：引入 ShareCoordinator，持有 RoomContext
     （roomId、title、anchorAvatarUrl、streamStateHandle）。
   - Rationale：避免在 Fragment/ViewController 內散落 if (wechat) … ，便於單測與埋點。
2. 渠道抽象
   - Decision：ShareChannel 接口：id、displayName、icon、
     canShare(context) -> Result、share(context, payload)。
3. 保活策略
   - Decision：直播推流/播放的啓停 ONLY 由直播域 API 控制；
     分享流程禁止調用「結束直播」。

Superpowers 的 subagent-driven-development 把 5 大任務切成多個子 Agent：

每個子 Agent 跑兩階段審查：規格一致性（必須對齊 spec.md 的 MUST 條款）+ 代碼質量（命名/結構/異常）。

同時 Agent Skills 提供以下行為約束（仍屬模型遵從層，不是文件級強制）：

• code-structure：建議單文件 ≤ 500 行、單函數 ≤ 50 行（避免「ShareCoordinator 一個文件 2000 行」）；
• test-driven-development：每個 canShare() 行為先寫失敗測試再寫實現；
• code-documentation：ShareChannel 接口的所有公開方法必須有註釋。

要把這三條變成「不可繞過」，需要把同樣的檢查複製到 pre-commit 與 CI（如 detekt / ktlint / 行數 lint / 文檔覆蓋率檢查），AI 行為 + CI 閘門雙保險才算真正強制。

⏱️ 這一步耗時：15-30 分鐘（多渠道適配並行；含子 Agent 推理 + 編譯，不含真機迴歸）

▶ Step 6：測試 + 審查（Superpowers 主導 + Agent Skills 量化）

誰來做：AI 調用 test-driven-development + requesting-code-review skill 執行（人審閲關鍵檢查點；CI 上同步跑同一組測試與覆蓋率門檻才能真正阻斷不達標合入）

最關鍵的一條 spec：「分享期間直播保活」。Superpowers 的 TDD 用一段失敗測試把它鎖死：

// 真實場景驅動的失敗測試（節選）
@Test
fun `分享流程期間不得向直播域發送停止指令`() {
    val streamSpy = StreamControlSpy()
    val coordinator = ShareCoordinator(streamControl = streamSpy)

    coordinator.present(roomContext)
    coordinator.onChannelSelected(ChannelId.WECHAT)
    // 模擬喚起微信授權頁 → 返回宿主
    coordinator.onReturnFromThirdParty()

    assertThat(streamSpy.stopInvocations).isEqualTo(0)   // RED ❌（還沒接保活策略）
}

跑一遍：

$ ./gradlew :share:test# RED ❌
> 1 test failed:
  分享流程期間不得向直播域發送停止指令

# Superpowers 引導 AI 寫最少代碼（保活策略）後
$ ./gradlew :share:test# GREEN ✅
$ ./gradlew :share:test --rerun-tasks   # 再跑一遍，全綠

$ git commit -m "feat(share): keep stream alive across third-party flow"

之後是 Superpowers 的 requesting-code-review（按嚴重度分級）：

🔴 CRITICAL：無
🟡 WARNING：ShareCoordinator 在 onChannelSelected 時未對 RoomContext 做空檢查
🟢 INFO：建議把「微博 SDK 必選 / 可降級」抽成 BuildConfig 開關
📊 測試覆蓋率：分支 86%（≥ 80% ✅）

Agent Skills：

• test-coverage：要求分支覆蓋 ≥ 80%（AI 行為約束；要做到「不達標禁止提交」需把覆蓋率門檻配置到 CI，例如 jacoco + coverage-check 工作流）；
• test-quality：必須覆蓋 spec 裏的 4 個核心 Scenario（打開/關閉、未安裝、版本不足、跳轉返回）。

⏱️ 這一步耗時：5-10 分鐘（AI 跑測試 + 自審）+ 人審閲 3 分鐘

▶ Step 7：安全檢查（Agent Skills 主導）

誰來做：AI 調用 security-* skills 執行（前提：Agent Skills 已 install 且對應 skill 已 enable；同一組檢查應同步進 CI 才能不可繞過）

回到 spec.md 的真實條款：

### Requirement: 隱私與日誌
系統 MUST NOT 在日誌或崩潰報告中打印第三方 access_token、refresh_token
或可用於識別用戶的敏感授權字段。

Agent Skills 把它落成 3 個安全閘門：

security-secrets       → 掃描倉庫與崩潰日誌：0 access_token / refresh_token ✅
security-dependencies  → 微信/QQ/微博 SDK 已知漏洞：0 high / 0 critical ✅
security-api           → 分享請求審計：URL 不攜帶 token；UA 不含用戶 ID ✅

任意一項失敗 → AI 停下並報告；要做到「不可繞過的阻斷」需把這 3 項檢查同步落到 CI（如 gitleaks / trivy / OWASP Dependency-Check），與 3.1.4 的安全失敗閘門子圖配套生效。

⏱️ 這一步耗時：1-2 分鐘（AI 觸發 skill 掃描；CI 上完整跑可能更長）

▶ Step 8：驗證 + 收尾（三方協作）

誰來做：AI 主導 + 人最終確認

8a. OpenSpec 驗證：

$ npx @fission-ai/openspec validate feat-live-share-third-party
Change 'feat-live-share-third-party' is valid
Progress: 4/4 artifacts complete

/opsx:verify 會逐條對照 specs/third-party-live-share/spec.md 的 Scenario：

✅ Scenario: 打開與關閉面板
✅ Scenario: 目標 App 未安裝
✅ Scenario: SDK 版本不滿足
✅ Scenario: 跳轉第三方後返回
✅ Scenario: 標題缺失時的兜底
✅ Scenario: 調試日誌脱敏

8b. Agent Skills 生產就緒檢查：

✅ 單測/集成測全綠     ✅ 分支覆蓋 ≥ 80%
✅ 無 token/秘密泄漏    ✅ ROM 兼容矩陣已記錄
✅ 文案/標題兜底生效    ✅ 回滾開關：feature flag share_panel.enabled

8c. Superpowers 收尾（finishing-a-development-branch）：

All tasks complete. What would you like to do?
1. Merge branch
2. Create PR              ← 選擇
3. Keep branch
4. Discard branch

8d. OpenSpec 歸檔：

/opsx:archive
# 歸檔到：openspec/changes/archive/2026-04-27-feat-live-share-third-party/
# specs/third-party-live-share/ 主規格自動更新為「已發佈」狀態

⏱️ 這一步耗時：2 分鐘（CLI 歸檔 + AI 觸發）+ 人決策 1 分鐘

⚠️ 邊界聲明：三件套是「行為約束」，不是「系統級強制」

為了避免讀者把上面 8 步當成「裝上就萬事大吉」的銀彈，需要把三件套的真實強度講清楚：

實務建議：

1. 關鍵質量門檻同時落兩層：例如「分支覆蓋率 ≥ 80%」既寫進 test-coverage skill（讓 AI 寫代碼時主動達標），也配置到 CI（不達標禁止合併）；
2. secrets / SDK 安全必須以 CI 閘門為準：gitleaks / trivy / OWASP Dependency-Check 等接入流水線，AI 的 security-* skill 只是早期發現；
3. AI 漏選 skill 時人要顯式指定：發現 AI 直接跳到寫代碼，明確說「請先用 brainstorming 澄清」或「按 test-driven-development 先寫 RED 測試」；
4. 不可繞過的事不要交給 skill：刪除生產數據、改 migrations/、改 prod 配置、改 main 分支，這些用 git hook / 倉庫保護規則鎖住。

一句話：OpenSpec 的 validate 是程序性強制；Superpowers 與 Agent Skills 是 AI 行為約束。 把三者按強度分層，再用 CI 兜底，才是工程化、可靠交付的形態。

3.3 完整流程時間估算

時間口徑說明：以下"AI 推理"指模型在 IDE Agent 模式下生成 + 調用 CLI 的累計耗時（不含真機迴歸 / 真實 SDK 聯調 / CI 排隊）；分享到第三方這種含多 SDK 接入的場景實際可能更長。

其中人真正需要投入的時間：約 10-15 分鐘（主要在 Step 1 審閲 spec 和 Step 6 審查關鍵檢查點）

第四章：安裝配置指南

4.1 環境準備

# 前置要求
node --version  # ≥ 20.19.0 (OpenSpec 要求)
git --version   # ≥ 2.30

4.2 安裝 OpenSpec

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

# 進入項目目錄，初始化
cd your-project
openspec init

# 生成 AGENTS.md（AI 助手的操作指南）
# 之後在 AI 編碼助手中即可使用 /opsx:* 命令

# 升級新版本
npm install -g @fission-ai/openspec@latest
openspec update   # 刷新 AI 指令

OpenSpec 支持的工具列表（部分）：

Claude Code · Codex CLI · Codex App · Cursor · Gemini CLI · Copilot · Windsurf · Cline · Roo Code · Amazon Q · CodeRabbit · Auggie · CoStrict · Amp · IBM Bob · CodeBuddy · Coffin · Factory · Qoder · Kilo Code · OpenCode · Qwen Code · Qoder · Trae

完整列表見：docs/supported-tools.md

4.3 安裝 Superpowers

根據你的 AI 編碼工具選擇安裝方式：

# Claude Code（推薦路徑）
/plugin install superpowers@claude-plugins-official

# 或者通過 Superpowers 自己的市場
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# GitHub Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

# 更新
# Claude Code 插件通常自動更新
# Gemini CLI:
gemini extensions update superpowers

安裝驗證：啓動 AI 編碼工具後，隨便說一句「我想做一個新功能」，如果 AI 開始反問你的需求而不是直接寫代碼，就說明 Superpowers 已生效。

4.4 安裝 Agent Skills

# 克隆倉庫
git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

# 初始化技能庫（生成默認配置）
agent-skills init

# 驗證技能格式（確保所有 SKILL.md 語法正確）
agent-skills verify

# 安裝所有技能到 AI 工作目錄
agent-skills install

# 啓用你需要的技能
agent-skills on test-coverage code-structure code-documentation \
           design-architect design-api \
           security-dependencies security-secrets \
           production-ready

# 停用暫時不需要的技能（減少上下文消耗）
agent-skills off design-security code-incident-review

# 更新技能到最新版本
agent-skills update

注意：技能會消耗 AI 的上下文窗口（token）。建議初期只啓用 5-8 個最核心的技能，後續根據需要逐步添加。

第五章：實戰演練 —— 完整案例

讓我們用一個教學向的完整案例來串起整條鏈路（與第三章「分享直播到第三方」的真實 spec 可對照閲讀；本章側重對話與步驟的樣貌）。

口徑：下文中的「自動」指 AI 在已安裝 OpenSpec 指令、Superpowers 與相關 skill 已注入上下文時的典型表現，屬於模型行為而非系統鈎子；不可繞過的質量門檻仍應以 CLI 與 CI 閘門 為準，見第三章「邊界聲明」。

背景

你維護一個 React + TypeScript 的 Dashboard 項目。用戶反饋希望增加「數據導出為 CSV」功能。

全流程實際操作

5.1 發起提案

👤 你（在 Claude Code 中）：
/opsx:propose "Dashboard 數據導出為 CSV 功能"

🤖 AI（OpenSpec 指令生效）：
正在生成提案…
✓ proposal.md 已創建
✓ specs/csv-export/spec.md 已創建
✓ design.md 已創建
✓ tasks.md 已創建

5.2 審閲 + 確認

# specs/csv-export/spec.md

## Scenario: 用戶在 Dashboard 中導出選中數據
Given 用戶在 Dashboard 頁面，已選中 3 條記錄
When 用戶點擊 "導出 CSV" 按鈕
Then 瀏覽器下載一個 CSV 文件
And 文件包含選中的 3 條記錄
And 文件名格式為 export-YYYY-MM-DD.csv

## Scenario: 未選中任何記錄時導出
Given 用戶在 Dashboard 頁面，未選中任何記錄
When 用戶點擊 "導出 CSV" 按鈕
Then 顯示 Toast 提示 "請先選擇要導出的數據"
And 不觸發下載

👤 你：確認提案，並補充一個場景：導出超過 10000 條時顯示進度條

🤖 AI：已添加 Scenario: 大數據量導出顯示進度

5.3 Superpowers 介入（需求澄清）

🤖 AI（加載了 brainstorming 等 skill 時，通常會先問清楚）：

在開始實現前，我想確認幾個細節：

1. CSV 文件編碼用什麼？UTF-8 還是 UTF-8 BOM（Excel 兼容）？
2. 需要支持自定義導出字段嗎？還是所有可見列都導出？
3. 數據中的逗號和換行符如何處理？
4. 是否需要後台異步導出（大文件場景）？

5.4 分支隔離 + 計劃制定

🤖 AI（在 using-git-worktrees、writing-plans 等技能可用時）：

✓ 創建 worktree: /tmp/project-csv-export
✓ 切換到新分支: feature/csv-export
✓ Clean test baseline: 42 tests passing

（基於 OpenSpec 的 tasks.md，細化實現計劃）

📋 實現計劃：

Task 1: 創建 CSV 工具函數 (約 3 min)
  - 文件: src/utils/csv.ts
  - 包含: escapeCSV, generateCSV, downloadCSV

Task 2: 添加導出按鈕 (約 2 min)
  - 文件: src/components/DashboardToolbar.tsx
  - 添加 "導出 CSV" 按鈕 + 未選中時禁用邏輯

Task 3: 集成到 Dashboard (約 3 min)
  - 文件: src/pages/Dashboard.tsx
  - 獲取選中數據 → 調用 generateCSV → 觸發下載

Task 4: 大數據量進度條 (約 4 min)
  - 文件: src/components/ExportProgress.tsx
  - 進度條組件 + Web Worker 異步處理

Task 5: 單元測試 (約 3 min)
  - 文件: src/utils/csv.test.ts
  - 覆蓋: 正常導出、空數據、特殊字符、10000+ 條

5.5 子 Agent 並行開發

🤖 AI（subagent-driven-development 可並行派發子任務，主 Agent 負責合併與解決衝突）：

[Agent-1] 處理 Task 1: CSV 工具函數
  ✓ 寫入 src/utils/csv.ts (87 行)
  📏 code-structure: 文件 87 行 ≤ 500，函數最大 22 行 ≤ 50（為 AI 行為約束，合入時建議 CI 再跑同樣規則）
  🔍 審查 1 (規格): 符合 spec
  🔍 審查 2 (質量): 代碼清晰，無明顯問題

[Agent-2] 處理 Task 2: 導出按鈕
  ✓ 寫入 src/components/DashboardToolbar.tsx
  …

[Agent-3] 處理 Task 5: 單元測試
  ✓ RED: 先失敗再實現（TDD）
  ✓ GREEN: 14 個測試全部 PASS
  📊 test-coverage: 分支覆蓋率 91%（以本地/CI 報告為準）

全部 5 個任務完成

5.6 測試 + 審查

🤖 AI：

🧪 運行全部測試…
  56 tests passing（原 42 + 新 14）

🔍 代碼審查:
  🟡 WARNING: csv.ts 的 escapeCSV 建議增加 null/undefined 處理
  → 已修正

🔒 安全檢查（security-* 已 enable 時）:
  依賴/秘密/API 掃描無阻斷項則繼續

5.7 驗證 + 收尾

👤 你：/opsx:verify

🤖 AI：對照 spec csv-export
  各 Scenario 與實現一致則標記通過

👤 你：需要創建 PR

/opsx:archive
  將變更按團隊規範歸檔；主 spec 隨團隊流程更新

總耗時：約 40 分鐘量級的演示口徑（人實際投入因審 spec、點合併而異）

第六章：進階技巧與最佳實踐

6.1 跳過某些步驟的藝術

不是每個變更都需要全套流程。教你判斷：

6.2 模型選擇建議

• 規劃階段（/opsx:propose 等）：傾向高推理、長上下文的模型，減少 spec 歧義
• 實現階段（/opsx:apply）：可在質量不降的前提下用成本更低的模型
• 子 Agent：通常繼承主會話模型；並行時注意 token 與合併成本

6.3 上下文窗口管理

Agent Skills 會消耗 token，建議：

# 初期：只啓用最核心的 5-8 個技能
agent-skills on \
  test-coverage \
  code-structure \
  code-documentation \
  security-secrets \
  production-ready

# 需求階段再加
agent-skills on req-clarify req-breakdown

# 需求完成後關閉（釋放上下文）
agent-skills off req-clarify req-breakdown

OpenSpec 也建議在實現前清理無關對話，保持可驗證的乾淨上下文。

6.4 團隊協作模式

關鍵：OpenSpec 的文檔層可作為團隊書面契約；

Superpowers 幫助把實現過程拆成可並行的子任務；

Agent Skills 主要降低風格與低級問題的反覆拉扯

——合入前仍應保留 Code Review 與 CI（與第三章邊界聲明一致，尤其是安全與業務關鍵路徑）。

第七章：與手動編碼的效率對比

下面用同一條功能線做量級對比，數字是教學示意，以你團隊真實工時為準；「三件套」行的優勢在於可預測、可歸檔、可迴歸，而不僅是快。