OpenSpec SDD 框架

讓人與 AI 在寫程式碼前先對齊規格的輕量 Spec-Driven Development 框架。

概述

OpenSpec 是一個 Spec-Driven Development（SDD） 框架，核心理念是把「規格對齊」做為開發的第一步。每個程式碼變更都有獨立的資料夾，存放 proposal（動機與範圍）、specs（需求規格）、design（技術方案）與 tasks（實作清單），確保人與 AI 對每個變更的「為什麼」、「做什麼」、「怎麼做」都有共同的基準。

它的設計哲學強調流動性（Fluid）與迭代性（Iterative）：spec 可以在開發的任何階段修改，發現設計有問題就改 spec 再繼續，這是預期行為而非例外。框架有意保持輕量——最少的儀式，5 分鐘即可完成初始化，並對既有的成熟專案友好（Brownfield friendly）。

核心內容

Profile 選擇

OpenSpec 有兩種 profile，決定可用的 AI 指令組：

Profile	包含指令	適合場景
Core（預設）	`explore`、`propose`、`apply`、`archive`	快速上手、小型變更
Expanded	上述 + `new`、`continue`、`ff`、`verify`、`sync`、`bulk-archive`、`onboard`	品質閘門、多變更並行、團隊協作

實務建議直接使用 Expanded profile。多出來的指令不用的可以不碰，但 verify 和 sync 在實際開發中非常有價值（見下方說明）。

目錄結構

每個 change 都有獨立的資料夾，彼此隔離：

openspec/
├── config.yaml                          # 專案設定（可選）
├── specs/                               # 主規格（archive 時合併到這裡）
└── changes/
    ├── add-dark-mode/                   # 進行中的變更
    │   ├── .openspec.yaml               # metadata
    │   ├── proposal.md                  # 為什麼做、改什麼
    │   ├── specs/                       # delta 規格
    │   ├── design.md                    # 技術方案
    │   └── tasks.md                     # 實作任務清單（checkbox 格式）
    └── archive/                         # 已歸檔的變更
        └── 2026-04-11-add-dark-mode/

核心工作流

完整流程：

/opsx:explore ─(可選)─► /opsx:propose ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
     │                       │                 │                │
  先調查再規劃           產出所有 artifact    逐任務實作      全局驗證        歸檔 + 合併 spec

`/opsx:explore` — 探索階段（Thinking Phase）

explore 是一個 stance（姿態），不是 workflow——沒有固定步驟、沒有強制產出，對話自然演化。不要把它誤解為「Brownfield 既有系統調查工具」，官方定義涵蓋四個面向：

使用情境	說明
Greenfield 構思	從零比較可能做法，AI 提問、繪製架構圖、挑戰假設
需求釐清	需求模糊時對話縮小範圍，確認前提假設
Brownfield 系統調查	接手陌生 codebase，讀取檔案、追蹤 dependency、理解架構
架構決策比較	面對技術選型時，依具體情境系統化比較各方案 trade-offs

Implementation Guardrail（核心限制）： explore 嚴格禁止寫應用程式碼或修改既有程式碼，強制思考與實作分離。要求實作時 AI 會提醒先退出並改用 /opsx:new 或 /opsx:ff。

Change-Scoped 模式： /opsx:explore <change-name> 可在實作中途針對複雜子問題暫停深度思考，AI 自動載入對應 change 的 proposal/design/tasks 作為上下文。

explore 結束的 insights 可直接轉入 /opsx:propose 產出結構化 spec artifacts。方向已確定時可直接跳到 propose。

`/opsx:propose` — 提案（核心起點）

一步到位產出完整的 change artifact：

檔案	內容	用途
`proposal.md`	動機、範圍、方法概述	對齊「為什麼」和「做什麼」
`specs/`	需求規格、使用場景	定義「怎樣算做完」
`design.md`	技術架構、設計決策	定義「怎麼做」
`tasks.md`	checkbox 格式的任務清單	追蹤「做到哪了」

這些檔案在任何時候都可以修改，OpenSpec 不鎖階段——propose 之後發現 spec 有問題，直接改 spec 再繼續 apply 就好。

`/opsx:apply` — 實作

逐一執行 tasks.md 中的任務，完成後勾選 checkbox。tasks.md 是進度的 source of truth——中途中斷後重新執行，會從未完成的任務繼續。多個 change 並行時用 /opsx:apply <name> 指定。

搭配 Superpowers 使用時： 如果用 Superpowers 的 subagent-driven-development 做實作，可以跳過 /opsx:apply，但需要在 CLAUDE.md 加一條指示讓 Superpowers 同步更新 tasks.md 的 checkbox，確保 OpenSpec 的進度追蹤不脫節（見下方整合說明）。

`/opsx:verify` — 驗證（Expanded profile 必備）

apply 和 archive 之間的全局品質閘門，拿完整程式碼比對所有 artifact，涵蓋三個維度：

維度	檢查內容
Completeness（完整性）	所有任務完成、所有 spec 需求有對應程式碼、場景有測試覆蓋
Correctness（正確性）	實作符合 spec 意圖、邊界條件處理、錯誤狀態符合定義
Coherence（一致性）	程式碼結構反映 design.md 的設計決策、命名慣例一致

verify 填補的是 apply 和 archive 之間的盲區——apply 只負責執行任務和勾 checkbox，archive 只負責搬檔案，中間沒有人檢查「做出來的東西跟寫在 spec 上的是不是同一回事」。特別是搭配 AI 實作時，agent 很可能任務都完成了但某些 spec 場景被遺漏，或實作方式與 design.md 的技術決策脫節。強烈建議每次 archive 前執行。

`/opsx:archive` — 歸檔

將已完成的 change 搬進 archive/，並將 delta spec 依 ADDED / MODIFIED / REMOVED / RENAMED 順序合併回主規格 openspec/specs/。有未完成的任務時發出警告但不阻擋，由你決定是否繼續。

其他擴展指令

/opsx:ff（Fast Forward）： 搭配 /opsx:new 使用，先建空的 change 骨架再一次填入所有規劃 artifact，適合已知目標清楚時
/opsx:sync： 實作中改了做法但忘記更新 spec 時，讓 spec 反映實際實作狀態；archive 之前用來確保 spec 與程式碼一致
/opsx:bulk-archive： 多個 change 同時完成時，一次歸檔並自動處理 spec 衝突，依時間順序合併
/opsx:onboard： 用你的實際 codebase 走一遍完整流程的互動式教學，適合第一次使用時

與 Superpowers 整合

OpenSpec 負責 spec 管理層，Superpowers 負責執行紀律，兩者可以疊加：

/opsx:propose           → 產出 spec + tasks.md
        ↓
/superpowers:writing-plans → 基於 OpenSpec 的 spec 寫細粒度計畫
        ↓
Superpowers subagent    → 執行 + TDD + 兩階段 code review
        ↓                  （同步更新 tasks.md checkbox）
/opsx:verify            → 全局驗證實作 vs. spec
        ↓
/opsx:archive           → 歸檔 + 合併 spec

在 CLAUDE.md 中加入以下指示，讓 Superpowers 的任務完成狀態同步到 OpenSpec 的 tasks.md：

## OpenSpec + Superpowers Integration

- When Superpowers brainstorming would normally produce a spec, instead read the
  existing OpenSpec artifacts from `openspec/changes/<name>/` as the design input.

- **REQUIRED after every plan task completes** (subagent-driven-development,
  executing-plans, or manual execution): update the corresponding checkbox in
  `openspec/changes/<name>/tasks.md` with `[x]` syntax **before** calling
  TaskUpdate/TodoWrite to mark it complete. Do this per task, not at the end.

  Checklist to run after each task:
  1. Edit `openspec/changes/<name>/tasks.md` — mark completed task items `[x]`
  2. Then mark the task complete in TaskUpdate/TodoWrite

  **Why this is easy to forget in subagent-driven-development:** subagents handle
  implementation and do not update openspec tasks. The controller (you) must do
  it after each subagent returns DONE, before moving to the next task.

- Do NOT use Superpowers' finishing-a-development-branch for archiving; use
  `/opsx:verify` then `/opsx:archive` instead.

關鍵要點

每個 change 有獨立資料夾，含 proposal / specs / design / tasks 四個 artifact
Spec 可以隨時修改——iterative 是設計原則，不是例外
verify 是 AI 輔助開發的關鍵安全網，填補「任務完成」到「spec 真正滿足」之間的盲區
建議直接啟用 Expanded profile，verify 和 sync 在實務中不可缺

實際應用

搭配 Claude Code 權限模式使用：在 /opsx:apply 階段開啟 acceptEdits 或 Auto 模式，讓 AI 自主完成任務；再用 /opsx:verify 做全局品質驗證；最後 /opsx:archive 歸檔。這樣既享有自動化的效率，又有 spec 層面的品質保障。

部署設定參考

以下為安裝、初始化與常用操作指令，供快速查詢與複製使用。

安裝與初始化

bash

# 安裝（需要 Node.js 20.19.0+）
npm install -g @fission-ai/openspec@latest

# 在專案目錄初始化
cd your-project
openspec init

初始化會建立 openspec/ 目錄結構，並產生 AI agent 的 skill 檔案（如 .claude/skills/）。可選建立 openspec/config.yaml 專案設定。

切換到 Expanded Profile

bash

openspec config profile   # 選擇 expanded
openspec update           # 重新產生 skill 檔案

常用 CLI 指令

bash

openspec init              # 初始化專案
openspec update            # 更新 skill 檔案（升級 OpenSpec 後必做）
openspec config profile    # 切換 profile
openspec list              # 列出所有進行中的 change 及進度
openspec list --json       # JSON 格式輸出（含 completedTasks / totalTasks）

AI 輔助完善 config.yaml 的 Prompt

openspec/config.yaml 是描述專案技術棧、架構慣例與業務術語的設定檔。可用以下 Prompt 讓 AI 協助從現有程式碼自動產生：

請閱讀整個專案的程式碼結構、README、package.json、主要設定檔，
然後幫我完善 openspec/config.yaml，包含：
- 技術棧與版本
- 架構模式（如 monorepo、前後端分離、API 規範等）
- 目錄結構慣例
- 程式碼規範（命名、測試策略等）
- 核心業務領域術語
  
以英文撰寫設定檔

適合在 openspec init 後立即執行，讓 AI 根據現有 codebase 自動填入設定，再人工審閱調整。

AI 指令速查表

指令	用途	Profile
`/opsx:explore`	調查 codebase、評估可行性	Core
`/opsx:propose`	一步產出完整 change artifact	Core
`/opsx:apply`	逐任務實作	Core
`/opsx:archive`	歸檔並合併 spec	Core
`/opsx:new`	只建立空的 change 骨架	Expanded
`/opsx:continue`	逐步建立 artifact（一次一個）	Expanded
`/opsx:ff`	一次產出所有規劃 artifact	Expanded
`/opsx:verify`	全局驗證實作 vs. spec	Expanded
`/opsx:sync`	同步 spec 與實際程式碼	Expanded
`/opsx:bulk-archive`	批次歸檔多個 change	Expanded
`/opsx:onboard`	互動式教學	Expanded

來源

原始素材：OpenSpec 實用指南
原始素材：2026-04-11 更新openspec config.yaml prompt
原始素材：/opsx:explore — 正確定位與使用情境

OpenSpec SDD 框架 ​

概述 ​

核心內容 ​

Profile 選擇 ​

目錄結構 ​

核心工作流 ​

/opsx:explore — 探索階段（Thinking Phase） ​

/opsx:propose — 提案（核心起點） ​

/opsx:apply — 實作 ​

/opsx:verify — 驗證（Expanded profile 必備） ​

/opsx:archive — 歸檔 ​

其他擴展指令 ​

與 Superpowers 整合 ​

關鍵要點 ​

實際應用 ​

部署設定參考 ​

安裝與初始化 ​

切換到 Expanded Profile ​

常用 CLI 指令 ​

AI 輔助完善 config.yaml 的 Prompt ​

AI 指令速查表 ​

相關概念 ​

來源 ​

OpenSpec SDD 框架

概述

核心內容

Profile 選擇

目錄結構

核心工作流

`/opsx:explore` — 探索階段（Thinking Phase）

`/opsx:propose` — 提案（核心起點）

`/opsx:apply` — 實作

`/opsx:verify` — 驗證（Expanded profile 必備）

`/opsx:archive` — 歸檔

其他擴展指令

與 Superpowers 整合

關鍵要點

實際應用

部署設定參考

安裝與初始化

切換到 Expanded Profile

常用 CLI 指令

AI 輔助完善 config.yaml 的 Prompt

AI 指令速查表

相關概念

來源