OpenSpec 實戰指南

作者：AgentBuff

日期：2026年5月9日下午6:09

來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點高亮

OpenSpec 係一個專為 AI 編碼助手設計嘅輕量規範驅動開發框架，透過結構化規範層解決需求丟失、迭代困難等痛點。

整理版摘要

呢篇文章係由 Fission AI 團隊撰寫嘅 OpenSpec 實戰指南。OpenSpec 係一個專為 AI 編碼助手時代設計嘅輕量級規範驅動開發框架（Spec-Driven Development）。作者想解決傳統 AI 編碼入面嘅幾個痛點：需求只存在於聊天歷史，好難迭代；每次修改都要重新描述上下文；冇審計軌跡；團隊協作依賴個人 prompt 技巧。整體結論係 OpenSpec 透過建立一層結構化嘅「規範層」，令開發者同 AI 喺寫 code 之前先對齊意圖、範圍同技術方案，從而提升效率同質量。

框架嘅核心係產物依賴圖引擎（DAG），支援多種 AI 工具適配，並提供 Delta 機制處理存量項目。工作流分 Core 快速路徑同 Expanded 擴展路徑，可以因應需求靈活選擇。另外，OpenSpec 支援自定義 Schema 同模板，適合團隊標準化協作。文章仲詳細介紹咗安裝、初始化、Slash 命令、CLI 命令、配置、最佳實踐等內容，係一份相當全面嘅實戰指南。

文章強調「規範唔等於實現計劃」，規範只描述系統行為契約，唔應該包含類名、庫選擇等實現細節。Delta 規範嘅設計令框架可以高效適應存量項目，只描述變化而非重寫整個規範。呢啲原則對於有效使用 OpenSpec 非常關鍵。

OpenSpec 透過產物依賴圖（DAG）管理 proposal、specs、design、tasks 等產物，確保迭代有序。
核心設計哲學強調「流動唔死板」「迭代唔瀑布」「輕量易用」「存量優先」。
Delta 規範機制只記錄變化，可自動合併入主規範，適合改造現有項目。
工作流提供 Core（快速）同 Expanded（擴展）兩種路徑，另支援探索式工作流處理不明確需求。
支援超過20種 AI 編碼工具，可透過 Schema 自定義工作流，適合團隊標準化。

整理重點

咩係 OpenSpec？

OpenSpec 係一個輕量級規範驅動開發框架（Spec-Driven Development），專為 AI 編碼助手時代設計。佢喺開發者同 AI 之間建立咗一層結構化嘅「規範層」，令雙方喺寫 code 之前先對齊意圖、範圍同技術方案。

OpenSpec 解決嘅核心問題包括：需求丟失、迭代困難、無審計軌跡同團隊協作難。傳統 AI 編碼中，需求只存在於聊天歷史，每次修改都要重新描述上下文；而 OpenSpec 提供結構化規範文件、Delta 機制同標準化工作流，令經驗可複用。

結構化規範文件可版本控制

Delta 機制 + 歸檔歷史

整理重點

核心架構與概念

OpenSpec 核心係產物依賴圖引擎，實現一個 DAG（有向無環圖）系統。產物之間嘅依賴關係係使能器（enabler），唔係門禁（gate），佢哋話畀你咩可以創建，而唔係必須按咩順序。

目錄結構示例 text

openspec/
├── specs/
│ ├── auth/
│ │ └── spec.md
│ └── payments/
│ └── spec.md
├── changes/
│ ├── add-dark-mode/
│ │ ├── proposal.md
│ │ ├── specs/
│ │ │ └── ui/
│ │ │ └── spec.md
│ │ ├── design.md
│ │ ├── tasks.md
│ │ └── .openspec.yaml
│ └── archive/
│ └── 2025-01-24-add-dark-mode/
├── schemas/
│ └── my-workflow/
│ ├── schema.yaml
│ └── templates/
└── config.yaml

規範（Specs）描述系統嘅行為契約，唔係實現細節。例：JWT 令牌認證嘅 Given/When/Then 場景。Delta 規範係 OpenSpec 適配存量項目嘅核心能力，只描述變化，分 ADDED、MODIFIED、REMOVED 三類，歸檔時自動合併入主規範。

規範 ≠ 實現計劃

SHALL/MUST/SHOULD (RFC 2119)

Delta 規範合併規則：ADDED 追加、MODIFIED 替換、REMOVED 刪除

整理重點

實戰工作流：從提案到歸檔

OpenSpec 提供兩種工作流路徑：Core 快速路徑（默認）同 Expanded 擴展路徑。Core 路徑用一條命令 /opsx:propose 完成所有規劃產物生成，然後 apply、sync、archive。Expanded 路徑支援逐個產物創建同審查（/opsx:new、/opsx:continue、/opsx:ff）。

Core 快速路徑：/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive
Expanded 擴展路徑：/opsx:new → /opsx:continue (或 /opsx:ff) → /opsx:apply → /opsx:verify → /opsx:archive
探索式工作流：/opsx:explore 先探索再提案，適合需求不明確時

完整案例：為應用添加暗色模式。Phase 1：/opsx:propose add-dark-mode 生成 proposal、specs、design、tasks；Phase 2：用 openspec list 同 openspec show 審查產物；Phase 3：/opsx:apply 按 tasks 逐項實現；Phase 4：/opsx:verify 檢查完整性、正確性同一致性；Phase 5：/opsx:archive 將 Delta 合併到主規範並歸檔。

Completeness、Correctness、Coherence 三維驗證

歸檔保留完整產物作為審計軌跡

整理重點

命令參考與配置自定義

Slash 命令喺 AI 對話中直接使用，例如 /opsx:propose、/opsx:apply、/opsx:explore。唔同工具嘅命令語法略有差異，例如 Claude Code 用斜線格式，Cursor 用連字符格式。CLI 終端命令則以 openspec 開頭，支援 init、list、show、view、validate、archive、config 等。

常用 CLI 命令示例 bash

# 初始化
openspec init --tools claude,cursor

# 瀏覽變更
openspec list
openspec show add-dark-mode

# 驗證
openspec validate add-dark-mode

# 歸檔
openspec archive add-dark-mode -y

# 配置
openspec config set telemetry.enabled false

自定義 Schema 可以 fork 現有 schema 或從零創建。Schema 定義產物類型、依賴關係同模板。項目配置 config.yaml 可設置 context（技術棧等背景資訊）同 rules（各產物嘅編寫規則），context 大小限制 50KB。

openspec schema fork spec-driven my-workflow

config.yaml 中 rules 按產物類型分組

整理重點

最佳實踐與工具支援

變更命名規範：使用 add-<feature>、fix-<issue>、refactor-<module>、optimize-<target>、implement-<spec>，避免 feature-1、update 等模糊名稱。工作流選擇決策：如果 30 秒內清楚「做咩」，需求明確就用 /opsx:propose；否則先用 /opsx:explore。

高質量規範：用 Given/When/Then 格式，避免寫實現細節

建議使用高推理能力模型：Claude Opus 4.5 / Sonnet 4.5 或 GPT 5.2

團隊協作：將 openspec/ 目錄納入版本控制，產物審查納入 Code Review
上下文衞生：開始實現前清空上下文窗口，使用 openspec instructions 獲取富指令
工具支援：超過20種 AI 編碼助手（Claude Code、Cursor、GitHub Copilot、Windsurf 等）

文章仲提供咗大量 CLI 命令同配置選項，建議讀者實際試用 OpenSpec 來體驗規範驅動開發嘅效率提升。

支援超過20種 AI 編碼工具

openspec workspace 協調跨倉庫變更（Beta）

介紹

#1.1 OpenSpec 係咩嚟

OpenSpec 係一個輕量級規範驅動開發框架（Spec-Driven Development），專為 AI 編碼助手時代而設計。佢喺開發者同 AI 之間建立咗一層結構化嘅「規範層」，等雙方喺寫 code 之前先對齊意圖、範圍同技術方案。

#1.2 核心設計哲學

fluid not rigid         — 無階段鎖定，隨時可以回溯修改任何產物
iterative not waterfall — 邊做邊學，持續迭代
easy not complex        — 輕量初始化，最小化儀式感
brownfield-first        — 為存量項目設計，不只是綠地開發

#1.3 解決嘅核心問題

痛點	傳統 AI 編碼	OpenSpec 方案
需求遺失	需求淨係存在喺聊天記錄入面	結構化規範文件，可以做版本控制
迭代困難	每次修改都要重新講返個上下文	任務驅動，可以暫停/恢復
無審計軌跡	改動冇記錄	Delta 機制 + 歸檔歷史
團隊協作難	依賴個人 prompt 技巧	標準化工作流程，經驗可以重用

架構設計

#核心架構：產物依賴圖引擎

OpenSpec 嘅核心係產物依賴圖引擎。佢實現咗一個 DAG（有向無環圖）系統：

狀態轉換模型：

#多工具適配層

OpenSpec 透過適配器模式為多種 AI 工具生成對應嘅設定檔。根據工具能力同當前 delivery/profile 配置，佢會生成 Skills、Commands，或者淨係生成 Skills。唔同工具嘅檔案路徑格式同渲染邏輯由各自適配器處理，用家通常只需要喺 openspec init 時揀目標工具就得。

核心概念

#目錄結構

運行 openspec init 之後，項目入面會建立：

openspec/
├── specs/              # 【權威基準】系統當前行為的完整描述
│   ├── auth/
│   │   └── spec.md
│   └── payments/
│       └── spec.md
├── changes/            # 【變更工作區】正在進行的修改
│   ├── add-dark-mode/
│   │   ├── proposal.md       # 提案：為什麼做、做什麼
│   │   ├── specs/            # Delta 規範：正在變化的部分
│   │   │   └── ui/
│   │   │       └── spec.md
│   │   ├── design.md         # 設計：如何實現
│   │   ├── tasks.md          # 任務：具體實現步驟
│   │   └── .openspec.yaml    # 變更元數據
│   └── archive/              # 已歸檔的歷史變更
│       └── 2025-01-24-add-dark-mode/
├── schemas/            # 【可選】自定義工作流 Schema
│   └── my-workflow/
│       ├── schema.yaml
│       └── templates/
└── config.yaml         # 項目配置

#Specs（規範）— 權威基準

規範描述系統嘅行為契約，唔係實作細節。

# Auth 規範

## 目的
用戶身份驗證和會話管理。

## 需求

### 需求：JWT 令牌認證
系統 SHALL 在登錄成功時頒發 JWT 令牌。

#### 場景：有效憑據登錄
- GIVEN 用戶具有有效的郵箱和密碼
- WHEN 用戶提交登錄表單
- THEN 系統返回 accessToken 和 refreshToken
- AND accessToken 有效期為 15 分鐘

關鍵要素：

要素	說明
`## 目的`	該規範領域嘅高層描述
`### 需求：`	系統必須有嘅具體行為
`#### 場景：`	可驗證嘅具體場景（Given/When/Then）
SHALL/MUST/SHOULD	RFC 2119 關鍵詞，表示需求強度

規範 ≠ 實現計劃：如果改 code 實作但唔改外部行為，就唔應該出現在規範度。類名、library 選擇、code 結構屬於 design.md。

#Changes（變更）— 提議嘅修改

每個變更係一個獨立資料夾，包含：

Proposal（提案）— 回答「點解做」同「做啲乜」
Specs（Delta 規範）— 描述緊變化嘅部分
Design（設計）— 回答「點樣實現」
Tasks（任務）— 具體實作步驟清單

#Delta 規範 — 增量描述變化

Delta 規範係 OpenSpec 適應現有項目嘅核心能力。佢淨係描述變化，而唔係成個規範重新寫過。

# Delta for Auth

## ADDED Requirements
### 需求：雙因素認證
系統 MUST 支持基於 TOTP 的雙因素認證。
...

## MODIFIED Requirements
### 需求：會話過期時間
系統 MUST 在 15 分鐘不活動後使會話過期。
（之前：30 分鐘）
...

## REMOVED Requirements
### 需求：記住我功能
（因支持 2FA 而廢棄）

歸檔時嘅合併規則：

Delta 段	歸檔效果
`## ADDED Requirements`	追加到主規範尾
`## MODIFIED Requirements`	取代主規範入面同名嘅需求
`## REMOVED Requirements`	從主規範入面刪除嗰個需求

#Artifacts（產物）依賴關係

產物之間形成 DAG 依賴：

proposal（無依賴，可首先創建）
    ↓
  specs ←─────→ design（都依賴 proposal，可並行創建）
    ↓              ↓
        tasks（依賴 specs + design）
          ↓
       implement（依賴 tasks）

依賴是使能器（enabler），而唔係門禁（gate）。佢哋話俾你知可以創建啲乜，而唔係一定要跟邊個順序。

#Schema — 工作流程定義

Schema 係一個 YAML 檔案，定義產物類型同佢哋嘅依賴關係。內置嘅 spec-driven Schema：

# schemas/spec-driven/schema.yaml
name:spec-driven
version:1
description:DefaultOpenSpecworkflow-proposal→specs→design→tasks

artifacts:
-id:proposal
    generates:proposal.md
    template:proposal.md
    instruction:|
      Create the proposal document that establishes WHY this change is needed.
      ...
    requires: []

-id:specs
    generates:"specs/**/*.md"
    template:spec.md
    instruction:|
      Create specification files that define WHAT the system should do.
      ...
    requires:
      -proposal

-id:design
    generates:design.md
    template:design.md
    instruction:|
      Create the design document that explains HOW to implement the change.
      ...
    requires:
      -proposal

-id:tasks
    generates:tasks.md
    template:tasks.md
    instruction:|
      Create the task list that breaks down the implementation work.
      ...
    requires:
      -specs
      -design

apply:
requires: [tasks]
tracks:tasks.md

Schema 字段說明：

字段	說明
`id`	唯一標識符，用嚟俾命令同規則引用
`generates`	輸出檔案名，支援 glob（例如 `specs/*/.md`）
`template`	模板檔案路徑（相對於 Schema 嘅 `templates/` 目錄）
`instruction`	AI 創建該產物時嘅指令
`requires`	依賴嘅產物 ID 列表

安裝與初始化

#安裝

# npm 全局安裝（推薦）
npm install -g @fission-ai/openspec@latest

# 或使用 pnpm
pnpm add -g @fission-ai/openspec@latest

# 或使用 yarn
yarn global add @fission-ai/openspec@latest

# 驗證安裝
openspec --version

#初始化項目

cd your-project

# 交互式初始化（推薦新手）
openspec init

# 非交互式：指定 AI 工具
openspec init --tools claude,cursor

# 配置所有支持的工具
openspec init --tools all

# 指定 profile
openspec init --profile core

初始化會建立：

openspec/specs/ — 規範目錄
openspec/changes/ — 變更目錄
openspec/config.yaml — 項目設定
.claude/skills/ / .cursor/skills/ 等 — AI 工具設定

#升級與更新

# 升級包
npm install -g @fission-ai/openspec@latest

# 在項目中重新生成 AI 工具配置文件
openspec update

完整工作流程實戰

#兩種模式

Core 快速路徑（預設）：

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

Expanded 擴展路徑（要開咗先用得）：

openspec config profile   # 選擇 workflows
openspec update            # 應用到項目

/opsx:new → /opsx:continue (或 /opsx:ff) → /opsx:apply → /opsx:verify → /opsx:archive

#完整案例：為應用程式加暗色模式

Phase 1: 開始變更

喺 AI 對話視窗輸入：

/opsx:propose add-dark-mode

我想為應用添加暗色模式功能：
1. 設置頁面添加主題切換開關
2. 支持檢測系統偏好（跟隨系統）
3. 用戶選擇持久化到 localStorage
4. 所有頁面即時切換，無需刷新

AI 會建立：

openspec/changes/add-dark-mode/proposal.md
openspec/changes/add-dark-mode/specs/ui/spec.md
openspec/changes/add-dark-mode/design.md
openspec/changes/add-dark-mode/tasks.md

Phase 2: 審查產物

# 查看變更列表
openspec list

# 查看變更詳情
openspec show add-dark-mode

# 交互式儀表板
openspec view

審查清單：

Proposal：意圖同範圍係咪準確？
Specs：場景係咪覆蓋主要用例同邊界情況？
Design：技術方案合唔合理？
Tasks：任務拆分合唔合理？粒度啱唔啱？

如果產物有問題，直接同 AI 講要改：「請將 tasks.md 入面第 2 組任務拆得更細啲」

Phase 3: 實作 code

/opsx:apply

AI 會跟住 tasks.md 逐項實作：

✓ 1.1 創建 ThemeContext
✓ 1.2 添加 CSS 自定義屬性
✓ 1.3 實現 localStorage 持久化
→ 2.1 創建 ThemeToggle 組件（進行中）
○ 2.2 添加到設置頁面
○ 3.1 定義暗色調色板

實作期間可以隨時暫停，下次繼續嗰陣 AI 會由未完成嘅任務繼續。

Phase 4: 驗現實作（推薦）

/opsx:verify

AI 會檢查三個維度：

Completeness：所有任務係咪完成？所有需求係咪實現咗？
Correctness：實作係咪符合規範意圖？邊界情況有冇處理？
Coherence：code 有冇反映設計決策？

Phase 5: 歸檔變更

/opsx:archive

歸檔過程會：

將 Delta 規範合併到 openspec/specs/ui/spec.md
將變更資料夾移動到 openspec/changes/archive/2025-xx-xx-add-dark-mode/
保留完整產物作為審計軌跡

#探索式工作流程

當需求唔清楚嘅時候：

/opsx:explore

You: 我想提升頁面加載性能，但不確定瓶頸在哪。

AI:  讓我分析一下...
     發現三個主要瓶頸：
     1. 未優化的大圖片
     2. ProductList 中的同步數據獲取
     3. Context 變化導致的重渲染

     你想先解決哪個？

You: 先解決數據獲取問題。

You: /opsx:propose optimize-product-list-fetching

#並行變更

# 正在做 add-dark-mode，被緊急 bug 打斷
/opsx:propose fix-login-redirect
/opsx:apply
/opsx:archive

# 回到之前的工作
/opsx:apply add-dark-mode

#更新 vs 新建變更

判斷條件	更新現有變更	新建變更
意圖	同一目標，調整執行	唔同嘅工作
範圍重疊	> 50%	< 50%
原先嘅變更能夠獨立完成	否	是

經驗法則： 如果改動歷史有價值，就更新；如果由頭做起更清楚，就新建。

Slash 命令參考

#Core Profile 命令（預設）

命令	說明
`/opsx:propose [名稱]`	建立變更並生成所有規劃產物（一條命令）
`/opsx:explore [主題]`	探索想法、調查問題、明確需求（唔會建立產物）
`/opsx:apply [名稱]`	實作任務清單入面嘅 code
`/opsx:sync [名稱]`	將 Delta 規範合併到主規範（可揀，archive 會自動處理）
`/opsx:archive [名稱]`	歸檔已經完成嘅變更

#Expanded Workflow 命令（要開咗先用得）

命令	說明
`/opsx:new [名稱]`	建立變更嘅基本結構（淨係目錄同元數據）
`/opsx:continue [名稱]`	跟依賴順序建立下一個產物（逐個）
`/opsx:ff [名稱]`	快進：一次過建立所有規劃產物
`/opsx:verify [名稱]`	驗現實作係咪同產物一致
`/opsx:bulk-archive [名稱...]`	批量歸檔多個已完成嘅變更
`/opsx:onboard`	互動式教學，帶你完成完整工作流程

#唔同工具嘅命令語法

工具	語法示例
Claude Code	`/opsx:propose`, `/opsx:apply`
Cursor	`/opsx-propose`, `/opsx-apply`
Windsurf	`/opsx-propose`, `/opsx-apply`
GitHub Copilot（IDE 擴展）	`/opsx-propose`, `/opsx-apply`
Kimi CLI	`/skill:openspec-propose`
Trae	`/openspec-propose`

註：GitHub Copilot 嘅 .github/prompts/*.prompt.md 方式目前係面向 IDE 擴展（例如 VS Code、JetBrains、Visual Studio）。Copilot CLI 唔可以直接用呢啲 prompt 檔案；Kimi CLI、Trae 呢啲工具主要都係依賴 skill-based 調用，而唔係統一嘅 opsx-* 命令檔案。

CLI 終端命令參考

#設定命令

命令	說明
`openspec init [路徑]`	初始化 OpenSpec（互動式/非互動式）
`openspec update [路徑]`	更新 AI 工具設定檔

openspec init --tools claude,cursor --profile core
openspec update --force

#瀏覽命令

命令	說明
`openspec list`	列出活動變更
`openspec list --specs`	列出所有規範
`openspec show [名稱]`	睇變更或規範詳情
`openspec view`	互動式儀錶板

openspec list --json          # JSON 輸出（適合腳本）
openspec show add-dark-mode   # 查看變更詳情
openspec show auth --type spec # 查看規範

#驗證命令

openspec validate                     # 交互式選擇驗證
openspec validate add-dark-mode       # 驗證特定變更
openspec validate --changes           # 驗證所有變更
openspec validate --all --json        # 全部驗證，JSON 輸出
openspec validate --all --strict      # 嚴格模式

#生命週期命令

openspec archive                      # 交互式歸檔
openspec archive add-dark-mode        # 歸檔特定變更
openspec archive add-dark-mode -y     # 跳過確認
openspec archive update-ci --skip-specs  # 跳過規範更新

#工作流程命令

openspec status --change add-dark-mode        # 查看產物完成狀態
openspec status --change add-dark-mode --json # JSON 輸出
openspec instructions --change add-dark-mode  # 獲取下一步指令
openspec instructions design --change add-dark-mode  # 獲取特定產物指令
openspec templates                            # 查看模板路徑
openspec schemas                              # 列出可用 Schema

#Schema 命令

openspec schema init my-workflow              # 創建新 Schema
openspec schema fork spec-driven my-workflow  # Fork 現有 Schema
openspec schema validate my-workflow          # 驗證 Schema
openspec schema which my-workflow             # 查看 Schema 解析來源
openspec schema which --all                   # 列出所有 Schema 及來源

#設定命令

openspec config path              # 顯示配置文件路徑
openspec config list              # 列出所有設置
openspec config get telemetry.enabled  # 獲取特定值
openspec config set telemetry.enabled false  # 設置值
openspec config profile           # 交互式配置 profile
openspec config profile core      # 快速切換到 core profile

#工作區命令（Beta）

openspec workspace setup                                    # 交互式設置
openspec workspace setup --no-interactive --name platform --link /repos/api
openspec workspace list                                     # 列出已知工作區
openspec workspace link api-service /repos/api              # 連結倉庫
openspec workspace relink api-service /new/path             # 修復連結
openspec workspace doctor                                   # 診斷問題
openspec workspace open                                     # 打開工作區
openspec workspace open platform --agent github-copilot     # 用指定工具打開

#其他命令

openspec feedback "建議信息"         # 提交反饋（需 gh CLI）
openspec completion install          # 安裝 Shell 自動補全
openspec completion install zsh      # 安裝 zsh 補全

#Schema 解析優先級

1. CLI 標誌: --schema <name>
2. 變更元數據: .openspec.yaml
3. 項目配置: openspec/config.yaml
4. 默認值: spec-driven

#環境變量

變量	說明
`OPENSPEC_TELEMETRY=0`	停用遙測
`DO_NOT_TRACK=1`	停用遙測（標準 DNT 訊號）
`OPENSPEC_CONCURRENCY=6`	批量驗證並行數
`EDITOR` / `VISUAL`	`openspec config edit` 用嘅編輯器
`NO_COLOR`	停用顏色輸出

自訂與擴展

#項目設定（config.yaml）

最簡單嘅自訂方式，喺 openspec/config.yaml 入面設定：

schema: spec-driven

context:|
  項目名稱：MyApp
  技術棧：TypeScript, React 18, Node.js, PostgreSQL
  API 風格：RESTful，文檔在 docs/api.md
  測試：Jest + React Testing Library
  代碼規範：ESLint + Prettier，嚴格 TypeScript
  所有公共 API 保持向後兼容

rules:
proposal:
    -必須包含回滾計劃
    -列出受影響的團隊
specs:
    -使用Given/When/Then格式
    -優先引用現有模式
design:
    -說明關鍵技術決策的理由
    -考慮性能和安全影響
tasks:
    -任務粒度適中（每個約1-2小時）
    -包含必要的測試任務

工作機制：

context 注入到所有產物嘅指令入面
rules 淨係注入到對應產物嘅指令入面
上下文大小限制：50KB

#建立自訂 Schema

方法一：Fork 現有 Schema（推薦）

openspec schema fork spec-driven my-workflow

生成：

openspec/schemas/my-workflow/
├── schema.yaml           # 可編輯的工作流定義
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

方法二：由零開始建立

# 交互式
openspec schema init research-first

# 非交互式
openspec schema init rapid \
  --description "快速迭代工作流" \
  --artifacts "proposal,tasks" \
  --default

示例：快速迭代 Schema

# openspec/schemas/rapid/schema.yaml
name:rapid
version:1
description:最小開銷的快速迭代

artifacts:
-id:proposal
    generates:proposal.md
    description:快速提案
    template:proposal.md
    instruction:|
      為此變更創建簡短提案。
      重點說明做什麼和為什麼，跳過詳細規範。
    requires: []

-id:tasks
    generates:tasks.md
    description:實現清單
    template:tasks.md
    requires: [proposal]

apply:
requires: [tasks]
tracks:tasks.md

示例：加個審查步驟

  - id:review
    generates:review.md
    description:實現前的審查清單
    template:review.md
    instruction:|
      基於設計創建審查清單。
      包含安全、性能和測試注意事項。
    requires:
      -design

-id:tasks
    ...
    requires:
      -specs
      -design
      -review    # tasks 現在也依賴 review

#Schema 管理

# 驗證 Schema 結構
openspec schema validate my-workflow

# 查看 Schema 解析來源
openspec schema which my-workflow
# 輸出：
# my-workflow resolves from: project
# Path: /path/to/project/openspec/schemas/my-workflow

# 列出所有可用 Schema
openspec schema which --all

Schema 解析優先級：

項目級：openspec/schemas/<name>/（推薦，版本控制）
用戶級：~/.local/share/openspec/schemas/<name>/（跨項目共享）
包內置：@fission-ai/openspec/schemas/

#模板自訂

模板係 Markdown 檔案，引導 AI 生成產物。可以包含：

AI 應該填嘅章節標題
HTML 註解入面嘅指導
期望結構嘅示例格式

<!-- templates/proposal.md -->
## 為什麼

<!-- 解釋此變更的動機。解決什麼問題？為什麼現在做？ -->

## 變更內容

<!-- 描述將發生的變化。具體說明新增能力或修改。 -->

## 影響

<!-- 受影響的代碼、API、依賴、系統 -->

支援嘅 AI 工具

OpenSpec 支援多種 AI 編碼助手，喺 openspec init 嗰陣可以自動設定。唔同工具嘅整合深度唔完全一樣：有啲同時支援 Skills 同 Commands，有啲淨係支援 Skills，或者用各自工具特有嘅命令入口。

#完整工具列表

工具	ID	Skills 路徑	Commands 路徑
Claude Code	`claude`	`.claude/skills/openspec-*/SKILL.md`	`.claude/commands/opsx/<id>.md`
Cursor	`cursor`	`.cursor/skills/openspec-*/SKILL.md`	`.cursor/commands/opsx-<id>.md`
Windsurf	`windsurf`	`.windsurf/skills/openspec-*/SKILL.md`	`.windsurf/workflows/opsx-<id>.md`
GitHub Copilot	`github-copilot`	`.github/skills/openspec-*/SKILL.md`	`.github/prompts/opsx-<id>.prompt.md`
Gemini CLI	`gemini`	`.gemini/skills/openspec-*/SKILL.md`	`.gemini/commands/opsx/<id>.toml`
Cline	`cline`	`.cline/skills/openspec-*/SKILL.md`	`.clinerules/workflows/opsx-<id>.md`
RooCode	`roocode`	`.roo/skills/openspec-*/SKILL.md`	`.roo/commands/opsx-<id>.md`
Continue	`continue`	`.continue/skills/openspec-*/SKILL.md`	`.continue/prompts/opsx-<id>.prompt`
Codex	`codex`	`.codex/skills/openspec-*/SKILL.md`	`$CODEX_HOME/prompts/opsx-<id>.md`
Amazon Q	`amazon-q`	`.amazonq/skills/openspec-*/SKILL.md`	`.amazonq/prompts/opsx-<id>.md`
Kiro	`kiro`	`.kiro/skills/openspec-*/SKILL.md`	`.kiro/prompts/opsx-<id>.prompt.md`
Kimi CLI	`kimi`	`.kimi/skills/openspec-*/SKILL.md`	—（用 skill-based 調用）
Lingma	`lingma`	`.lingma/skills/openspec-*/SKILL.md`	`.lingma/commands/opsx/<id>.md`
Qwen Code	`qwen`	`.qwen/skills/openspec-*/SKILL.md`	`.qwen/commands/opsx-<id>.toml`
Trae	`trae`	`.trae/skills/openspec-*/SKILL.md`	—（用 skill-based 調用）
OpenCode	`opencode`	`.opencode/skills/openspec-*/SKILL.md`	`.opencode/commands/opsx-<id>.md`
Kilo Code	`kilocode`	`.kilocode/skills/openspec-*/SKILL.md`	`.kilocode/workflows/opsx-<id>.md`
iFlow	`iflow`	`.iflow/skills/openspec-*/SKILL.md`	`.iflow/commands/opsx-<id>.md`
Qoder	`qoder`	`.qoder/skills/openspec-*/SKILL.md`	`.qoder/commands/opsx/<id>.md`
CoStrict	`costrict`	`.cospec/skills/openspec-*/SKILL.md`	`.cospec/openspec/commands/opsx-<id>.md`
Crush	`crush`	`.crush/skills/openspec-*/SKILL.md`	`.crush/commands/opsx/<id>.md`
Factory Droid	`factory`	`.factory/skills/openspec-*/SKILL.md`	`.factory/commands/opsx-<id>.md`
Auggie	`auggie`	`.augment/skills/openspec-*/SKILL.md`	`.augment/commands/opsx-<id>.md`
Antigravity	`antigravity`	`.agent/skills/openspec-*/SKILL.md`	`.agent/workflows/opsx-<id>.md`
CodeBuddy	`codebuddy`	`.codebuddy/skills/openspec-*/SKILL.md`	`.codebuddy/commands/opsx/<id>.md`
IBM Bob	`bob`	`.bob/skills/openspec-*/SKILL.md`	`.bob/commands/opsx-<id>.md`
Junie	`junie`	`.junie/skills/openspec-*/SKILL.md`	`.junie/commands/opsx-<id>.md`
ForgeCode	`forgecode`	`.forge/skills/openspec-*/SKILL.md`	—（冇命令適配器）
Pi	`pi`	`.pi/skills/openspec-*/SKILL.md`	`.pi/prompts/opsx-<id>.md`

#非互動式安裝

# 配置特定工具
openspec init --tools claude,cursor

# 配置所有工具
openspec init --tools all

# 跳過工具配置
openspec init --tools none

#生成嘅 Skill 名稱

openspec-propose
openspec-explore
openspec-new-change
openspec-continue-change
openspec-apply-change
openspec-ff-change
openspec-sync-specs
openspec-archive-change
openspec-bulk-archive-change
openspec-verify-change
openspec-onboard

多語言支援

在 openspec/config.yaml 的 context 入面加語言指令就得：

schema: spec-driven

context: |
  語言：中文（簡體）
  所有產出物必須用簡體中文撰寫。

  技術棧: TypeScript, React, Node.js

其他語言示例：

# 英語（默認，無需配置）

# 葡萄牙語
context: |
  Language: Portuguese (pt-BR)
  All artifacts must be written in Brazilian Portuguese.

# 日語
context: |
  言語：日本語
  すべての成果物は日本語で作成してください。

# 技術術語處理
context: |
  語言：中文（簡體）
  用中文撰寫，但保留 API、REST、GraphQL 等技術術語為英文。
  代碼示例和文件路徑保持英文。

Coordination Workspace（協調工作區）

Beta 功能 — 命令行為同輸出格式可能會隨時變。目前唔建議基於 workspace 命令建立長期自動化、外部整合或者穩定依賴嘅團隊流程；更適合人手驅動、邊試邊調嘅協同規劃場景。

#概念模型

workspace = 相關跨倉庫變更的規劃之家
link      = 倉庫或文件夾的穩定名稱
change    = 一個功能、修復或項目的規劃單元

#目錄結構

workspace-folder/
├── changes/                       # 工作區級規劃
└── .openspec-workspace/
    ├── workspace.yaml             # 共享工作區標識和連結名稱
    └── local.yaml                 # 本機本地路徑（不提交）

#典型用法

# 設置工作區
openspec workspace setup
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web

# 連結倉庫
openspec workspace link api-service /repos/api

# 診斷問題
openspec workspace doctor

# 打開工作區
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

最佳實踐

#變更命名規範

模式	示例	場景
`add-<feature>`	`add-dark-mode`	新增功能
`fix-<issue>`	`fix-login-redirect`	Bug 修復
`refactor-<module>`	`refactor-auth-service`	代碼重構
`optimize-<target>`	`optimize-query-performance`	效能優化
`implement-<spec>`	`implement-2fa`	實現規範

避免： feature-1、update、wip、changes

#工作流程選擇決策

你能在 30 秒內描述清楚「做什麼」嗎？
├── 是 → 需求明確
│   ├── 功能複雜度高（>10 個任務）？
│   │   ├── 是 → /opsx:new + /opsx:ff
│   │   └── 否 → /opsx:propose
│   └── 需要團隊審查？
│       ├── 是 → /opsx:continue（逐步審查）
│       └── 否 → /opsx:propose
└── 否 → /opsx:explore 先探索

#12.3 高質量規範編寫

✅ 好嘅規範：

### 需求：JWT 令牌認證
系統 SHALL 在登錄成功時頒發 JWT 令牌。

#### 場景：有效憑據登錄
- GIVEN 用戶具有有效的郵箱和密碼
- WHEN 用戶提交登錄表單
- THEN 系統返回包含 accessToken 和 refreshToken 的響應
- AND accessToken 有效期為 15 分鐘

❌ 要避免嘅寫法：

### 需求：登錄功能
使用 bcrypt 比較密碼，用 jsonwebtoken 庫生成 JWT。
在 UserController.login() 方法中實現...

#12.4 設定模板推薦

# openspec/config.yaml
schema:spec-driven

context:|
  項目名稱：MyApp
  技術棧：TypeScript, React 18, Node.js, PostgreSQL
  測試：Jest + React Testing Library
  代碼規範：ESLint + Prettier，嚴格 TypeScript
  API：RESTful，保持向後兼容

rules:
proposal:
    -必須包含回滾計劃
    -說明對現有功能的影響
specs:
    -使用Given/When/Then格式
    -包含邊界條件和異常場景
design:
    -說明關鍵技術決策的理由
    -列出受影響的文件和模塊
tasks:
    -粒度適中（每個約1-2小時）
    -按模塊分組，使用層級編號
    -包含必要的測試任務

#團隊協作建議

將 openspec/ 將目錄納入版本控制
將 openspec/config.yaml 提交到 code 庫，確保團隊用一致嘅設定
建立 team 專屬嘅 Schema 同 templates
將產物審查納入 Code Review 流程
定期歸檔變更，保持 changes/ 目錄整齊

#模型選擇

OpenSpec 官方推薦用高推理能力模型：

Claude Opus 4.5 / Sonnet 4.5 — 規劃同實作
GPT 5.2 — 規劃同實作

#上下文衞生

開始實作前清空上下文視窗
喺成個會話入面保持良好嘅上下文衞生
使用 openspec instructions 獲取豐富嘅指令，而唔係手動拼接

如果你睇到呢度，即係呢篇文章對你都仲有啲幫助，希望可以關注我，獲取更多有見解嘅內容，你嘅讚好、收藏、轉發係我堅持嘅動力。

最近🈶️新嘅病毒嚟襲，提前儲備啲口罩同酒精以備不時之需：

介紹

#1.1 OpenSpec 是什麼

OpenSpec 是一個輕量級規範驅動開發框架（Spec-Driven Development），專為 AI 編碼助手時代設計。它在開發者與 AI 之間建立了一層結構化的「規範層」，讓雙方在編寫代碼之前先對齊意圖、範圍和技術方案。

#1.2 核心設計哲學

fluid not rigid         — 無階段鎖定，隨時可以回溯修改任何產物
iterative not waterfall — 邊做邊學，持續迭代
easy not complex        — 輕量初始化，最小化儀式感
brownfield-first        — 為存量項目設計，不只是綠地開發

#1.3 解決的核心問題

痛點	傳統 AI 編碼	OpenSpec 方案
需求丟失	需求只存在於聊天曆史中	結構化規範文件，可版本控制
迭代困難	每次修改需重新描述上下文	任務驅動，可暫停/恢復
無審計軌跡	變更無記錄	Delta 機制 + 歸檔歷史
團隊協作難	依賴個人 prompt 技巧	標準化工作流，經驗可複用

架構設計

#核心架構：產物依賴圖引擎

OpenSpec 的核心是產物依賴圖引擎。它實現了一個 DAG（有向無環圖）系統：

狀態轉換模型：

#多工具適配層

OpenSpec 通過適配器模式為多種 AI 工具生成對應的配置文件。根據工具能力和當前 delivery/profile 配置，它會生成 Skills、Commands，或僅生成 Skills。不同工具的文件路徑格式和渲染邏輯由各自適配器處理，用戶通常只需要在 openspec init 時選擇目標工具即可。

核心概念

#目錄結構

運行 openspec init 後，項目中會創建：

openspec/
├── specs/              # 【權威基準】系統當前行為的完整描述
│   ├── auth/
│   │   └── spec.md
│   └── payments/
│       └── spec.md
├── changes/            # 【變更工作區】正在進行的修改
│   ├── add-dark-mode/
│   │   ├── proposal.md       # 提案：為什麼做、做什麼
│   │   ├── specs/            # Delta 規範：正在變化的部分
│   │   │   └── ui/
│   │   │       └── spec.md
│   │   ├── design.md         # 設計：如何實現
│   │   ├── tasks.md          # 任務：具體實現步驟
│   │   └── .openspec.yaml    # 變更元數據
│   └── archive/              # 已歸檔的歷史變更
│       └── 2025-01-24-add-dark-mode/
├── schemas/            # 【可選】自定義工作流 Schema
│   └── my-workflow/
│       ├── schema.yaml
│       └── templates/
└── config.yaml         # 項目配置

#Specs（規範）— 權威基準

規範描述系統的行為契約，不是實現細節。

# Auth 規範

## 目的
用戶身份驗證和會話管理。

## 需求

### 需求：JWT 令牌認證
系統 SHALL 在登錄成功時頒發 JWT 令牌。

#### 場景：有效憑據登錄
- GIVEN 用戶具有有效的郵箱和密碼
- WHEN 用戶提交登錄表單
- THEN 系統返回 accessToken 和 refreshToken
- AND accessToken 有效期為 15 分鐘

關鍵要素：

要素	說明
`## 目的`	該規範領域的高層描述
`### 需求：`	系統必須具備的具體行為
`#### 場景：`	可驗證的具體場景（Given/When/Then）
SHALL/MUST/SHOULD	RFC 2119 關鍵詞，表示需求強度

規範 ≠ 實現計劃：如果改代碼實現但不改外部行為，那就不該出現在規範裏。類名、庫選擇、代碼結構屬於 design.md。

#Changes（變更）— 提議的修改

每個變更是一個獨立文件夾，包含：

Proposal（提案）— 回答「為什麼做」和「做什麼」
Specs（Delta 規範）— 描述正在變化的部分
Design（設計）— 回答「如何實現」
Tasks（任務）— 具體實現步驟清單

#Delta 規範 — 增量描述變化

Delta 規範是 OpenSpec 適配存量項目的核心能力。它只描述變化，而非重寫整個規範。

# Delta for Auth

## ADDED Requirements
### 需求：雙因素認證
系統 MUST 支持基於 TOTP 的雙因素認證。
...

## MODIFIED Requirements
### 需求：會話過期時間
系統 MUST 在 15 分鐘不活動後使會話過期。
（之前：30 分鐘）
...

## REMOVED Requirements
### 需求：記住我功能
（因支持 2FA 而廢棄）

歸檔時的合併規則：

Delta 段	歸檔效果
`## ADDED Requirements`	追加到主規範末尾
`## MODIFIED Requirements`	替換主規範中的同名需求
`## REMOVED Requirements`	從主規範中刪除該需求

#Artifacts（產物）依賴關係

產物之間形成 DAG 依賴：

proposal（無依賴，可首先創建）
    ↓
  specs ←─────→ design（都依賴 proposal，可並行創建）
    ↓              ↓
        tasks（依賴 specs + design）
          ↓
       implement（依賴 tasks）

依賴是使能器（enabler），不是門禁（gate）。它們告訴你什麼可以創建，而非必須按什麼順序。

#Schema — 工作流定義

Schema 是一個 YAML 文件，定義產物類型及其依賴關係。內置的 spec-driven Schema：

# schemas/spec-driven/schema.yaml
name:spec-driven
version:1
description:DefaultOpenSpecworkflow-proposal→specs→design→tasks

artifacts:
-id:proposal
    generates:proposal.md
    template:proposal.md
    instruction:|
      Create the proposal document that establishes WHY this change is needed.
      ...
    requires: []

-id:specs
    generates:"specs/**/*.md"
    template:spec.md
    instruction:|
      Create specification files that define WHAT the system should do.
      ...
    requires:
      -proposal

-id:design
    generates:design.md
    template:design.md
    instruction:|
      Create the design document that explains HOW to implement the change.
      ...
    requires:
      -proposal

-id:tasks
    generates:tasks.md
    template:tasks.md
    instruction:|
      Create the task list that breaks down the implementation work.
      ...
    requires:
      -specs
      -design

apply:
requires: [tasks]
tracks:tasks.md

Schema 字段說明：

字段	說明
`id`	唯一標識符，用於命令和規則引用
`generates`	輸出文件名，支持 glob（如 `specs/*/.md`）
`template`	模板文件路徑（相對於 Schema 的 `templates/` 目錄）
`instruction`	AI 創建該產物時的指令
`requires`	依賴的產物 ID 列表

安裝與初始化

#安裝

# npm 全局安裝（推薦）
npm install -g @fission-ai/openspec@latest

# 或使用 pnpm
pnpm add -g @fission-ai/openspec@latest

# 或使用 yarn
yarn global add @fission-ai/openspec@latest

# 驗證安裝
openspec --version

#初始化項目

cd your-project

# 交互式初始化（推薦新手）
openspec init

# 非交互式：指定 AI 工具
openspec init --tools claude,cursor

# 配置所有支持的工具
openspec init --tools all

# 指定 profile
openspec init --profile core

初始化會創建：

openspec/specs/ — 規範目錄
openspec/changes/ — 變更目錄
openspec/config.yaml — 項目配置
.claude/skills/ / .cursor/skills/ 等 — AI 工具配置

#升級與更新

# 升級包
npm install -g @fission-ai/openspec@latest

# 在項目中重新生成 AI 工具配置文件
openspec update

完整工作流實戰

#兩種模式

Core 快速路徑（默認）：

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

Expanded 擴展路徑（需啓用）：

openspec config profile   # 選擇 workflows
openspec update            # 應用到項目

/opsx:new → /opsx:continue (或 /opsx:ff) → /opsx:apply → /opsx:verify → /opsx:archive

#完整案例：為應用添加暗色模式

Phase 1: 啓動變更

在 AI 對話窗口中輸入：

/opsx:propose add-dark-mode

我想為應用添加暗色模式功能：
1. 設置頁面添加主題切換開關
2. 支持檢測系統偏好（跟隨系統）
3. 用戶選擇持久化到 localStorage
4. 所有頁面即時切換，無需刷新

AI 將創建：

openspec/changes/add-dark-mode/proposal.md
openspec/changes/add-dark-mode/specs/ui/spec.md
openspec/changes/add-dark-mode/design.md
openspec/changes/add-dark-mode/tasks.md

Phase 2: 審查產物

# 查看變更列表
openspec list

# 查看變更詳情
openspec show add-dark-mode

# 交互式儀表板
openspec view

審查清單：

Proposal：意圖和範圍是否準確？
Specs：場景是否覆蓋主要用例和邊界情況？
Design：技術方案是否合理？
Tasks：任務拆分是否合理？粒度是否適中？

如果產物有問題，直接告訴 AI 修改：「請把 tasks.md 中的第 2 組任務拆分得更細一些」

Phase 3: 實現代碼

/opsx:apply

AI 將按 tasks.md 逐項實現：

✓ 1.1 創建 ThemeContext
✓ 1.2 添加 CSS 自定義屬性
✓ 1.3 實現 localStorage 持久化
→ 2.1 創建 ThemeToggle 組件（進行中）
○ 2.2 添加到設置頁面
○ 3.1 定義暗色調色板

實現過程中可以隨時暫停，下次繼續時 AI 會從未完成的任務繼續。

Phase 4: 驗證實現（推薦）

/opsx:verify

AI 將檢查三個維度：

Completeness：所有任務是否完成？所有需求是否實現？
Correctness：實現是否符合規範意圖？邊界情況是否處理？
Coherence：代碼是否反映了設計決策？

Phase 5: 歸檔變更

/opsx:archive

歸檔過程會：

將 Delta 規範合併到 openspec/specs/ui/spec.md
將變更文件夾移動到 openspec/changes/archive/2025-xx-xx-add-dark-mode/
保留完整產物作為審計軌跡

#探索式工作流

當需求不明確時：

/opsx:explore

You: 我想提升頁面加載性能，但不確定瓶頸在哪。

AI:  讓我分析一下...
     發現三個主要瓶頸：
     1. 未優化的大圖片
     2. ProductList 中的同步數據獲取
     3. Context 變化導致的重渲染

     你想先解決哪個？

You: 先解決數據獲取問題。

You: /opsx:propose optimize-product-list-fetching

#並行變更

# 正在做 add-dark-mode，被緊急 bug 打斷
/opsx:propose fix-login-redirect
/opsx:apply
/opsx:archive

# 回到之前的工作
/opsx:apply add-dark-mode

#更新 vs 新建變更

判斷條件	更新現有變更	新建變更
意圖	同一目標，調整執行	不同的工作
範圍重疊	> 50%	< 50%
原變更能否獨立完成	否	是

經驗法則： 如果改動歷史有價值，就更新；如果從頭開始更清晰，就新建。

Slash 命令參考

#Core Profile 命令（默認）

命令	說明
`/opsx:propose [名稱]`	創建變更並生成所有規劃產物（一條命令）
`/opsx:explore [主題]`	探索想法、調查問題、明確需求（不創建產物）
`/opsx:apply [名稱]`	實現任務清單中的代碼
`/opsx:sync [名稱]`	將 Delta 規範合併到主規範（可選，archive 會自動處理）
`/opsx:archive [名稱]`	歸檔已完成的變更

#Expanded Workflow 命令（需啓用）

命令	說明
`/opsx:new [名稱]`	創建變更腳手架（僅目錄和元數據）
`/opsx:continue [名稱]`	按依賴順序創建下一個產物（逐個）
`/opsx:ff [名稱]`	快進：一次性創建所有規劃產物
`/opsx:verify [名稱]`	驗證實現是否與產物一致
`/opsx:bulk-archive [名稱...]`	批量歸檔多個已完成的變更
`/opsx:onboard`	交互式教程，引導完成完整工作流

#不同工具的命令語法

工具	語法示例
Claude Code	`/opsx:propose`, `/opsx:apply`
Cursor	`/opsx-propose`, `/opsx-apply`
Windsurf	`/opsx-propose`, `/opsx-apply`
GitHub Copilot（IDE 擴展）	`/opsx-propose`, `/opsx-apply`
Kimi CLI	`/skill:openspec-propose`
Trae	`/openspec-propose`

注：GitHub Copilot 的 .github/prompts/*.prompt.md 方式目前面向 IDE 擴展（如 VS Code、JetBrains、Visual Studio）。Copilot CLI 不能直接消費這類 prompt 文件；Kimi CLI、Trae 等工具也主要依賴 skill-based 調用，而不是統一的 opsx-* 命令文件。

CLI 終端命令參考

#設置命令

命令	說明
`openspec init [路徑]`	初始化 OpenSpec（交互式/非交互式）
`openspec update [路徑]`	更新 AI 工具配置文件

openspec init --tools claude,cursor --profile core
openspec update --force

#瀏覽命令

命令	說明
`openspec list`	列出活動變更
`openspec list --specs`	列出所有規範
`openspec show [名稱]`	查看變更或規範詳情
`openspec view`	交互式儀表板

openspec list --json          # JSON 輸出（適合腳本）
openspec show add-dark-mode   # 查看變更詳情
openspec show auth --type spec # 查看規範

#驗證命令

openspec validate                     # 交互式選擇驗證
openspec validate add-dark-mode       # 驗證特定變更
openspec validate --changes           # 驗證所有變更
openspec validate --all --json        # 全部驗證，JSON 輸出
openspec validate --all --strict      # 嚴格模式

#生命週期命令

openspec archive                      # 交互式歸檔
openspec archive add-dark-mode        # 歸檔特定變更
openspec archive add-dark-mode -y     # 跳過確認
openspec archive update-ci --skip-specs  # 跳過規範更新

#工作流命令

openspec status --change add-dark-mode        # 查看產物完成狀態
openspec status --change add-dark-mode --json # JSON 輸出
openspec instructions --change add-dark-mode  # 獲取下一步指令
openspec instructions design --change add-dark-mode  # 獲取特定產物指令
openspec templates                            # 查看模板路徑
openspec schemas                              # 列出可用 Schema

#Schema 命令

openspec schema init my-workflow              # 創建新 Schema
openspec schema fork spec-driven my-workflow  # Fork 現有 Schema
openspec schema validate my-workflow          # 驗證 Schema
openspec schema which my-workflow             # 查看 Schema 解析來源
openspec schema which --all                   # 列出所有 Schema 及來源

#配置命令

openspec config path              # 顯示配置文件路徑
openspec config list              # 列出所有設置
openspec config get telemetry.enabled  # 獲取特定值
openspec config set telemetry.enabled false  # 設置值
openspec config profile           # 交互式配置 profile
openspec config profile core      # 快速切換到 core profile

#工作區命令（Beta）

openspec workspace setup                                    # 交互式設置
openspec workspace setup --no-interactive --name platform --link /repos/api
openspec workspace list                                     # 列出已知工作區
openspec workspace link api-service /repos/api              # 連結倉庫
openspec workspace relink api-service /new/path             # 修復連結
openspec workspace doctor                                   # 診斷問題
openspec workspace open                                     # 打開工作區
openspec workspace open platform --agent github-copilot     # 用指定工具打開

#其他命令

openspec feedback "建議信息"         # 提交反饋（需 gh CLI）
openspec completion install          # 安裝 Shell 自動補全
openspec completion install zsh      # 安裝 zsh 補全

#Schema 解析優先級

1. CLI 標誌: --schema <name>
2. 變更元數據: .openspec.yaml
3. 項目配置: openspec/config.yaml
4. 默認值: spec-driven

#環境變量

變量	說明
`OPENSPEC_TELEMETRY=0`	禁用遙測
`DO_NOT_TRACK=1`	禁用遙測（標準 DNT 信號）
`OPENSPEC_CONCURRENCY=6`	批量驗證併發數
`EDITOR` / `VISUAL`	`openspec config edit` 使用的編輯器
`NO_COLOR`	禁用顏色輸出

自定義與擴展

#項目配置（config.yaml）

最簡單的自定義方式，在 openspec/config.yaml 中設置：

schema: spec-driven

context:|
  項目名稱：MyApp
  技術棧：TypeScript, React 18, Node.js, PostgreSQL
  API 風格：RESTful，文檔在 docs/api.md
  測試：Jest + React Testing Library
  代碼規範：ESLint + Prettier，嚴格 TypeScript
  所有公共 API 保持向後兼容

rules:
proposal:
    -必須包含回滾計劃
    -列出受影響的團隊
specs:
    -使用Given/When/Then格式
    -優先引用現有模式
design:
    -說明關鍵技術決策的理由
    -考慮性能和安全影響
tasks:
    -任務粒度適中（每個約1-2小時）
    -包含必要的測試任務

工作機制：

context 注入到所有產物的指令中
rules 只注入到對應產物的指令中
上下文大小限制：50KB

#創建自定義 Schema

方式一：Fork 現有 Schema（推薦）

openspec schema fork spec-driven my-workflow

生成：

openspec/schemas/my-workflow/
├── schema.yaml           # 可編輯的工作流定義
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

方式二：從零創建

# 交互式
openspec schema init research-first

# 非交互式
openspec schema init rapid \
  --description "快速迭代工作流" \
  --artifacts "proposal,tasks" \
  --default

示例：快速迭代 Schema

# openspec/schemas/rapid/schema.yaml
name:rapid
version:1
description:最小開銷的快速迭代

artifacts:
-id:proposal
    generates:proposal.md
    description:快速提案
    template:proposal.md
    instruction:|
      為此變更創建簡短提案。
      重點說明做什麼和為什麼，跳過詳細規範。
    requires: []

-id:tasks
    generates:tasks.md
    description:實現清單
    template:tasks.md
    requires: [proposal]

apply:
requires: [tasks]
tracks:tasks.md

示例：添加審查步驟

  - id:review
    generates:review.md
    description:實現前的審查清單
    template:review.md
    instruction:|
      基於設計創建審查清單。
      包含安全、性能和測試注意事項。
    requires:
      -design

-id:tasks
    ...
    requires:
      -specs
      -design
      -review    # tasks 現在也依賴 review

#Schema 管理

# 驗證 Schema 結構
openspec schema validate my-workflow

# 查看 Schema 解析來源
openspec schema which my-workflow
# 輸出：
# my-workflow resolves from: project
# Path: /path/to/project/openspec/schemas/my-workflow

# 列出所有可用 Schema
openspec schema which --all

Schema 解析優先級：

項目級：openspec/schemas/<name>/（推薦，版本控制）
用戶級：~/.local/share/openspec/schemas/<name>/（跨項目共享）
包內置：@fission-ai/openspec/schemas/

#模板自定義

模板是 Markdown 文件，引導 AI 生成產物。可以包含：

AI 應填充的章節標題
HTML 註釋中的指導
期望結構的示例格式

<!-- templates/proposal.md -->
## 為什麼

<!-- 解釋此變更的動機。解決什麼問題？為什麼現在做？ -->

## 變更內容

<!-- 描述將發生的變化。具體說明新增能力或修改。 -->

## 影響

<!-- 受影響的代碼、API、依賴、系統 -->

支持的 AI 工具

OpenSpec 支持多種 AI 編碼助手，在 openspec init 時可以自動配置。不同工具的集成深度不完全相同：有些同時支持 Skills 和 Commands，有些只支持 Skills，或使用各自工具特有的命令入口。

#完整工具列表

工具	ID	Skills 路徑	Commands 路徑
Claude Code	`claude`	`.claude/skills/openspec-*/SKILL.md`	`.claude/commands/opsx/<id>.md`
Cursor	`cursor`	`.cursor/skills/openspec-*/SKILL.md`	`.cursor/commands/opsx-<id>.md`
Windsurf	`windsurf`	`.windsurf/skills/openspec-*/SKILL.md`	`.windsurf/workflows/opsx-<id>.md`
GitHub Copilot	`github-copilot`	`.github/skills/openspec-*/SKILL.md`	`.github/prompts/opsx-<id>.prompt.md`
Gemini CLI	`gemini`	`.gemini/skills/openspec-*/SKILL.md`	`.gemini/commands/opsx/<id>.toml`
Cline	`cline`	`.cline/skills/openspec-*/SKILL.md`	`.clinerules/workflows/opsx-<id>.md`
RooCode	`roocode`	`.roo/skills/openspec-*/SKILL.md`	`.roo/commands/opsx-<id>.md`
Continue	`continue`	`.continue/skills/openspec-*/SKILL.md`	`.continue/prompts/opsx-<id>.prompt`
Codex	`codex`	`.codex/skills/openspec-*/SKILL.md`	`$CODEX_HOME/prompts/opsx-<id>.md`
Amazon Q	`amazon-q`	`.amazonq/skills/openspec-*/SKILL.md`	`.amazonq/prompts/opsx-<id>.md`
Kiro	`kiro`	`.kiro/skills/openspec-*/SKILL.md`	`.kiro/prompts/opsx-<id>.prompt.md`
Kimi CLI	`kimi`	`.kimi/skills/openspec-*/SKILL.md`	—（使用 skill-based 調用）
Lingma	`lingma`	`.lingma/skills/openspec-*/SKILL.md`	`.lingma/commands/opsx/<id>.md`
Qwen Code	`qwen`	`.qwen/skills/openspec-*/SKILL.md`	`.qwen/commands/opsx-<id>.toml`
Trae	`trae`	`.trae/skills/openspec-*/SKILL.md`	—（使用 skill-based 調用）
OpenCode	`opencode`	`.opencode/skills/openspec-*/SKILL.md`	`.opencode/commands/opsx-<id>.md`
Kilo Code	`kilocode`	`.kilocode/skills/openspec-*/SKILL.md`	`.kilocode/workflows/opsx-<id>.md`
iFlow	`iflow`	`.iflow/skills/openspec-*/SKILL.md`	`.iflow/commands/opsx-<id>.md`
Qoder	`qoder`	`.qoder/skills/openspec-*/SKILL.md`	`.qoder/commands/opsx/<id>.md`
CoStrict	`costrict`	`.cospec/skills/openspec-*/SKILL.md`	`.cospec/openspec/commands/opsx-<id>.md`
Crush	`crush`	`.crush/skills/openspec-*/SKILL.md`	`.crush/commands/opsx/<id>.md`
Factory Droid	`factory`	`.factory/skills/openspec-*/SKILL.md`	`.factory/commands/opsx-<id>.md`
Auggie	`auggie`	`.augment/skills/openspec-*/SKILL.md`	`.augment/commands/opsx-<id>.md`
Antigravity	`antigravity`	`.agent/skills/openspec-*/SKILL.md`	`.agent/workflows/opsx-<id>.md`
CodeBuddy	`codebuddy`	`.codebuddy/skills/openspec-*/SKILL.md`	`.codebuddy/commands/opsx/<id>.md`
IBM Bob	`bob`	`.bob/skills/openspec-*/SKILL.md`	`.bob/commands/opsx-<id>.md`
Junie	`junie`	`.junie/skills/openspec-*/SKILL.md`	`.junie/commands/opsx-<id>.md`
ForgeCode	`forgecode`	`.forge/skills/openspec-*/SKILL.md`	—（無命令適配器）
Pi	`pi`	`.pi/skills/openspec-*/SKILL.md`	`.pi/prompts/opsx-<id>.md`

#非交互式安裝

# 配置特定工具
openspec init --tools claude,cursor

# 配置所有工具
openspec init --tools all

# 跳過工具配置
openspec init --tools none

#生成的 Skill 名稱

openspec-propose
openspec-explore
openspec-new-change
openspec-continue-change
openspec-apply-change
openspec-ff-change
openspec-sync-specs
openspec-archive-change
openspec-bulk-archive-change
openspec-verify-change
openspec-onboard

多語言支持

在 openspec/config.yaml 的 context 中添加語言指令即可：

schema: spec-driven

context: |
  語言：中文（簡體）
  所有產出物必須用簡體中文撰寫。

  技術棧: TypeScript, React, Node.js

其他語言示例：

# 英語（默認，無需配置）

# 葡萄牙語
context: |
  Language: Portuguese (pt-BR)
  All artifacts must be written in Brazilian Portuguese.

# 日語
context: |
  言語：日本語
  すべての成果物は日本語で作成してください。

# 技術術語處理
context: |
  語言：中文（簡體）
  用中文撰寫，但保留 API、REST、GraphQL 等技術術語為英文。
  代碼示例和文件路徑保持英文。

Coordination Workspace（協調工作區）

Beta 功能 — 命令行為和輸出格式可能隨時變更。當前不建議基於 workspace 命令構建長期自動化、外部集成或穩定依賴的團隊流程；更適合人工驅動、邊試邊調的協同規劃場景。

#概念模型

workspace = 相關跨倉庫變更的規劃之家
link      = 倉庫或文件夾的穩定名稱
change    = 一個功能、修復或項目的規劃單元

#目錄結構

workspace-folder/
├── changes/                       # 工作區級規劃
└── .openspec-workspace/
    ├── workspace.yaml             # 共享工作區標識和連結名稱
    └── local.yaml                 # 本機本地路徑（不提交）

#典型用法

# 設置工作區
openspec workspace setup
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web

# 連結倉庫
openspec workspace link api-service /repos/api

# 診斷問題
openspec workspace doctor

# 打開工作區
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

最佳實踐

#變更命名規範

模式	示例	場景
`add-<feature>`	`add-dark-mode`	新增功能
`fix-<issue>`	`fix-login-redirect`	Bug 修復
`refactor-<module>`	`refactor-auth-service`	代碼重構
`optimize-<target>`	`optimize-query-performance`	性能優化
`implement-<spec>`	`implement-2fa`	實現規範

避免： feature-1、update、wip、changes

#工作流選擇決策

你能在 30 秒內描述清楚「做什麼」嗎？
├── 是 → 需求明確
│   ├── 功能複雜度高（>10 個任務）？
│   │   ├── 是 → /opsx:new + /opsx:ff
│   │   └── 否 → /opsx:propose
│   └── 需要團隊審查？
│       ├── 是 → /opsx:continue（逐步審查）
│       └── 否 → /opsx:propose
└── 否 → /opsx:explore 先探索

#12.3 高質量規範編寫

✅ 好的規範：

### 需求：JWT 令牌認證
系統 SHALL 在登錄成功時頒發 JWT 令牌。

#### 場景：有效憑據登錄
- GIVEN 用戶具有有效的郵箱和密碼
- WHEN 用戶提交登錄表單
- THEN 系統返回包含 accessToken 和 refreshToken 的響應
- AND accessToken 有效期為 15 分鐘

❌ 避免的寫法：

### 需求：登錄功能
使用 bcrypt 比較密碼，用 jsonwebtoken 庫生成 JWT。
在 UserController.login() 方法中實現...

#12.4 配置模板推薦

# openspec/config.yaml
schema:spec-driven

context:|
  項目名稱：MyApp
  技術棧：TypeScript, React 18, Node.js, PostgreSQL
  測試：Jest + React Testing Library
  代碼規範：ESLint + Prettier，嚴格 TypeScript
  API：RESTful，保持向後兼容

rules:
proposal:
    -必須包含回滾計劃
    -說明對現有功能的影響
specs:
    -使用Given/When/Then格式
    -包含邊界條件和異常場景
design:
    -說明關鍵技術決策的理由
    -列出受影響的文件和模塊
tasks:
    -粒度適中（每個約1-2小時）
    -按模塊分組，使用層級編號
    -包含必要的測試任務

#團隊協作建議

將 openspec/ 目錄納入版本控制
將 openspec/config.yaml 提交到代碼庫，確保團隊使用一致配置
創建團隊專屬的 Schema 和 templates
將產物審查納入 Code Review 流程
定期歸檔變更，保持 changes/ 目錄整潔

#模型選擇

OpenSpec 官方推薦使用高推理能力模型：

Claude Opus 4.5 / Sonnet 4.5 — 規劃和實現
GPT 5.2 — 規劃和實現

#上下文衞生

開始實現前清空上下文窗口
在整個會話中保持良好的上下文衞生
使用 openspec instructions 獲取富指令，而非手動拼接

如果你看到這裏，那這篇文章對你還是有點幫助的，希望得到你的關注，獲取更多有見解的內容，你的點贊，收藏，轉發是我堅持的動力。

最近🈶️新的病毒來襲了，提前儲備點口罩和酒精以備不時之需：