技術選型

本節說明實施規格驅動工作流程所需的關鍵技術選擇。

LLM 服務提供者

首選：Claude Code

Claude Code 是首選的 LLM 服務提供者。它原生支援 CLAUDE.md 與專案指引檔案，讓代理能有效消費結構化脈絡。內建的 MCP (Model Context Protocol) 支援讓工具能力可以彈性擴展。在程式碼生成、重構、錯誤修正等核心開發任務上，Claude Code 表現優異，同時提供企業級的安全性與隱私保護。對於高頻開發場景，Pro/Max 訂閱提供類似「吃到飽」的大量使用能力，不用擔心 API 呼叫次數限制。整體生態系與 OpenSpec、各種 IDE 擴充套件都有良好整合。

替代方案：OpenCode

當 Claude Code 無法使用時（例如網路限制、成本考量），OpenCode 可作為替代方案。

OpenCode 是開源專案，可以自行部署，不會有供應商鎖定的問題。它支援多種 LLM 後端，可以使用本地模型或較低成本的 API，資料也能完全留在本地環境。

選擇建議：

• 企業環境、需要最佳品質 → Claude Code
• 有網路限制或合規要求 → OpenCode（本地部署）
• 成本敏感的實驗專案 → OpenCode
• 需要特定模型微調 → OpenCode
• 不確定 → Claude Code（較安全的選擇）

規格管理框架：OpenSpec

為何需要框架

當團隊開始導入 AI 輔助開發，很快會發現一個問題：AI 需要規格作為脈絡，但規格散落各處。有人寫在 Confluence，有人放在 Google Doc，有人直接寫在 Jira ticket 裡。每個團隊發明自己的格式，AI 代理每次都要重新理解結構。

更麻煩的是變更追蹤。當一個功能橫跨三個月開發，中間改了五次規格，最後沒人說得清楚現在的規格到底是什麼。實作跟規格漸行漸遠，直到某天發現兩者完全脫節。

OpenSpec 解決的就是這個問題：給規格一個固定的家、統一的格式、清楚的生命週期。AI 代理知道去哪裡找規格、怎麼解析內容、如何追蹤變更。人類也終於能回答「X 功能的規格在哪裡」這個簡單問題。

架構

openspec/
├── project.md              # 專案慣例與脈絡
├── specs/                  # 當前真相 - 已建置的內容
│   └── [capability]/
│       └── spec.md         # 需求與情境
├── changes/                # 提案 - 應該變更的內容
│   └── [change-id]/
│       ├── proposal.md     # 為什麼、什麼、影響
│       ├── tasks.md        # 實作檢查清單
│       └── specs/          # 每個能力的差異變更
└── archive/                # 已完成變更（歷史）

簡單來說：specs/ 放的是當前真相（已經建好的東西），changes/ 放的是提案（應該要改的東西），archive/ 放的是歷史（曾經改過的東西）。

CLI 快速參考

# 發現
openspec list                    # 進行中的變更
openspec list --specs            # 當前能力
openspec show [item]             # 檢視細節

# 驗證
openspec validate [change] --strict

# 生命週期
openspec archive [change] --yes  # 完成並合併

框架轉換策略

OpenSpec 的規格檔案是純 Markdown，沒有專屬格式。標題結構遵循固定慣例，任何文字處理工具都能解析。所有內容存放於 Git，遷移時歷史紀錄完整保留。

如果未來需要換用其他框架，內容不需要大幅度重寫。

技術堆疊總覽

層級	首選	替代方案
LLM 服務	Claude Code	OpenCode
規格框架	OpenSpec	純 Markdown + Git
API 規格	任何 schema 化的 API 描述格式（依專案需求選擇）	-
規格格式	Gherkin（OpenSpec 採用，BDD 業界慣例）	-
版本控制	Git	-
文件格式	Markdown	-

為什麼沒有指定 API 規格格式？

API 規格格式應依專案需求選擇。重點是採用 schema 化的描述方式，讓 AI 代理能準確理解 API 結構。常見選項包括 OpenAPI、AsyncAPI、GraphQL Schema 等。

Agent Skill 框架

為什麼需要 Skill 框架

AI 程式碼代理缺乏內在紀律——它們不會自動釐清需求、先寫測試、或在聲稱完成前驗證結果。Skill 框架提供「AI 代理的員工手冊」，透過結構化工作流程強制執行專業開發實踐。

沒有明確的流程紀律，代理會跳過步驟、合理化捷徑、並過早聲稱完成。Skill 框架將隱性團隊知識轉換為明確、可執行的工作流程。

推薦：Superpowers

儲存庫： github.com/obra/superpowers

Superpowers 是一個可組合的 skill 框架，引導 AI 代理通過紀律化的開發工作流程。它不是建議性的指導，而是從需求釐清到驗證的強制性流程。該框架提供 15 個結構化 skills，涵蓋完整開發生命週期。

與我們工作流程對應的關鍵 Skills

Skill	對應工作流程	用途
Brainstorming	功能開發流程	編碼前的蘇格拉底式提問；YAGNI 執行
Writing Plans	API 設計流程	詳細實作任務（每個 2-5 分鐘）
Systematic Debugging	錯誤修復流程	4 階段調查：根因 → 模式 → 假設 → 修復
Test-Driven Development	原則 E4（嚴謹驗證）	RED-GREEN-REFACTOR 執行
Verification Before Completion	原則 E4（嚴謹驗證）	基於證據的完成聲明

與 OpenSpec 的整合

Superpowers 與 OpenSpec 互補：OpenSpec 定義要建造什麼（規格），Superpowers 定義代理如何工作（流程紀律）。團隊同時使用兩者——OpenSpec 用於規格生命週期，Superpowers 用於執行紀律。

詳細採用指南請參閱 Agent Skill 採用 提案。

參考資料

• Claude Code - Claude Code 官方文件
• OpenCode - OpenCode 開源專案
• OpenSpec - OpenSpec 官方儲存庫
• Superpowers - 紀律化開發的 Agent skill 框架
• Model Context Protocol (MCP) - Anthropic 的 AI 工具整合協定