OPSX 工作流程
歡迎在 Discord 上提供回饋。
什麼是 OPSX？
OPSX 現在是 OpenSpec 的標準工作流程。
它是一個流暢、迭代的 OpenSpec 變更工作流程。不再有僵硬的階段劃分——隨時都可以採取行動。
為何存在
傳統的 OpenSpec 工作流程可以運作，但它是鎖死的：
- 指令是寫死的 — 埋藏在 TypeScript 中，你無法修改它們
- 全有或全無 — 一個大指令會建立所有東西，無法單獨測試個別部分
- 固定結構 — 對所有人都是相同的工作流程，無法自訂
- 黑箱 — 當 AI 輸出不佳時，你無法調整提示詞
OPSX 開啟了它。 現在任何人都可以：
- 試驗指令 — 編輯範本，看看 AI 是否表現更好
- 精細測試 — 獨立驗證每個產物的指令
- 自訂工作流程 — 定義你自己的產物與依賴關係
- 快速迭代 — 修改範本，立即測試，無需重新建置
傳統工作流程： OPSX：
┌────────────────────────┐ ┌────────────────────────┐
│ 寫死在套件中 │ │ schema.yaml │◄── 你編輯這裡
│ （無法修改） │ │ templates/*.md │◄── 或這裡
│ ↓ │ │ ↓ │
│ 等待新版本釋出 │ │ 立即生效 │
│ ↓ │ │ ↓ │
│ 希望更好 │ │ 自行測試 │
└────────────────────────┘ └────────────────────────┘這對所有人都有益：
- 團隊 — 建立符合實際工作方式的工作流程
- 進階使用者 — 調整提示詞，讓 AI 在你們的程式碼庫上輸出更好
- OpenSpec 貢獻者 — 無需發佈即可試驗新方法
我們都還在學習什麼方法最有效。OPSX 讓我們一起學習。
使用者體驗
線性工作流程的問題： 你處於「規劃階段」，然後「實作階段」，然後「完成」。但實際工作並非如此。你實作某些東西，發現設計錯誤，需要更新規格，繼續實作。線性階段與實際工作的進行方式背道而馳。
OPSX 方法：
- 行動，而非階段 — 建立、實作、更新、封存 — 隨時都可以執行任何一個
- 依賴關係是促成者 — 它們顯示什麼是可能的，而不是下一步必須做什麼
proposal ──→ specs ──→ design ──→ tasks ──→ implement設定
bash
# 確保你已安裝 openspec — 技能會自動產生
openspec init這會在 .claude/skills/（或等效目錄）中建立技能，AI 編碼助理會自動偵測這些技能。
預設情況下，OpenSpec 使用 core 工作流程設定檔（propose、explore、apply、update、sync、archive）。如果你想要擴充的工作流程指令（new、continue、ff、verify、bulk-archive、onboard），請使用 openspec config profile 進行設定，並使用 openspec update 套用。
在設定期間，系統會提示你建立一個專案設定（openspec/config.yaml）。這是可選的，但建議執行。
專案設定
專案設定可讓你設定預設值，並將專案特定情境注入到所有產物中。
建立設定
設定會在 openspec init 期間建立，或手動建立：
yaml
# openspec/config.yaml
schema: spec-driven
context: |
技術堆疊：TypeScript、React、Node.js
API 慣例：RESTful、JSON 回應
測試：Vitest 用於單元測試，Playwright 用於端對端測試
風格：ESLint 搭配 Prettier，嚴格的 TypeScript
rules:
proposal:
- 包含回滾方案
- 識別受影響的團隊
specs:
- 對情境使用 Given/When/Then 格式
design:
- 為複雜流程包含時序圖設定欄位
| 欄位 | 類型 | 說明 |
|---|---|---|
schema | string | 新變更的預設 schema（例如 spec-driven） |
context | string | 注入所有產物指示的專案情境 |
rules | object | 每個產物的規則，以 artifact ID 為鍵 |
運作方式
Schema 優先順序（從最高到最低）：
- CLI 旗標（
--schema <name>） - 變更中繼資料（變更目錄中的
.openspec.yaml） - 專案設定（
openspec/config.yaml） - 預設（
spec-driven）
情境注入：
- 情境會被前置到每個產物的指示中
- 包裹在
<context>...</context>標籤中 - 幫助 AI 理解你專案的慣例
規則注入：
- 規則只會注入到相符的產物中
- 包裹在
<rules>...</rules>標籤中 - 出現在情境之後、範本之前
依 Schema 的產物 ID
spec-driven（預設）：
proposal— 變更提案specs— 規格design— 技術設計tasks— 實作任務
設定驗證
rules中的未知產物 ID 會產生警告- Schema 名稱會針對可用的 schema 進行驗證
- 情境有 50KB 的大小限制
- 無效的 YAML 會回報行號
疑難排解
「rules 中的未知產物 ID：X」
- 檢查產物 ID 是否符合你的 schema（參見上方清單）
- 執行
openspec schemas --json以查看每個 schema 的產物 ID
設定未套用：
- 確保檔案位於
openspec/config.yaml（而非.yml） - 使用驗證器檢查 YAML 語法
- 設定變更會立即生效（無需重新啟動）
情境過大：
- 情境限制為 50KB
- 改為摘要或連結到外部文件
指令
| 指令 | 功用 |
|---|---|
/opsx:propose | 一步建立變更並產生規劃產物（預設快速路徑） |
/opsx:explore | 思考想法、調查問題、釐清需求 |
/opsx:new | 開始新的變更骨架（擴充工作流程） |
/opsx:continue | 建立下一個產物（擴充工作流程） |
/opsx:ff | 快速推進規劃產物（擴充工作流程） |
/opsx:apply | 實作任務，視需要更新產物 |
/opsx:update | 修訂變更的規劃產物並保持一致性 |
/opsx:verify | 驗證實作是否符合產物（擴充工作流程） |
/opsx:sync | 將 delta 規格合併到主要規格（可選） |
/opsx:archive | 完成時封存 |
/opsx:bulk-archive | 封存多個已完成的變更（擴充工作流程） |
/opsx:onboard | 引導式的端到端變更教學（擴充工作流程） |
使用方式
探索想法
/opsx:explore思考想法、調查問題、比較選項。不需要結構 - 就像一位思考夥伴。當見解成形時，轉換到 /opsx:propose（預設）或 /opsx:new//opsx:ff（擴充）。
開始新的變更
/opsx:propose建立變更並產生實作前所需的規劃產物。
如果你已啟用擴充工作流程，你可以改用：
text
/opsx:new # 僅建立骨架
/opsx:continue # 一次建立一個產物
/opsx:ff # 一次建立所有規劃產物建立產物
/opsx:continue根據依賴關係顯示可建立的內容，然後建立一個產物。重複使用以逐步建立你的變更。
/opsx:ff add-dark-mode一次建立所有規劃產物。當你對要建立的東西有清楚構想時使用。
實作（彈性部分）
/opsx:apply逐步執行任務，並在進行時勾選完成。如果你同時處理多個變更，可以執行 /opsx:apply <name>；否則它會從對話中推斷，如果無法判斷則提示你選擇。
更新變更
/opsx:update add-dark-mode - 我們現在將主題儲存在 cookie 中修訂變更既有的規劃產物並保持一致性 - 任何方向都可以（設計編輯可能會回饋到提案）。只處理規劃產物：它不編輯程式碼，也不會建立缺失的產物（那是 /opsx:continue 的工作）。每個編輯都會先跟你確認。如果變更已經實作，它會建議 /opsx:apply，讓程式碼跟上修訂後的計畫。如果你的修訂改變了變更的意圖，請改為重新開始 - 參見 何時更新 vs. 重新開始。
同步 delta 規格
text
/opsx:sync將目前變更的 delta 規格合併到你的主要 openspec/specs/ 中，而不進行封存 — 變更仍然保持啟用。它套用整個 delta：在 ## REMOVED 下的需求會從主要規格中刪除，重新命名的需求會就地重新標題，而 delta 未提及的內容則保持不變。同步是可選的 — 封存會提示你先同步（如果你尚未同步）。當你想在封存前更新主要規格、當平行的變更需要建立在此變更剛新增的規格之上、或當你想在封存前檢閱合併後的主要規格時，可以使用它。
完成收尾
/opsx:archive # 完成後移到封存（如有需要會提示同步規格）何時更新 vs. 重新開始
你總可以在實作前編輯你的提案或規格。但何時修改會變成「這是不同的工作」？
提案所捕捉的內容
一個提案定義了三件事：
- 意圖 — 你正在解決什麼問題？
- 範圍 — 什麼是允許/不允許的？
- 方法 — 你將如何解決它？
問題是：哪些改變了，改變了多少？
在以下情況更新現有變更：
相同的意圖，精煉的執行
- 你發現了你未考慮的邊界情況
- 方法需要調整，但目標不變
- 實作顯示設計略有偏差
範圍縮小
- 你意識到完整範圍太大，想先發佈 MVP
- 「加入深色模式」→「加入深色模式切換（系統偏好設定在 v2）」
學習驅動的修正
- 程式碼庫的結構與你原本想的不同
- 某個依賴未如預期運作
- 「使用 CSS 變數」→「改用 Tailwind 的 dark: 前綴」
在以下情況開始新的變更：
意圖根本改變
- 問題本身已經不同
- 「加入深色模式」→「加入包含自訂顏色、字型、間距的全面主題系統」
範圍爆炸
- 變更成長到本質上成為不同的工作
- 原始提案在更新後會變得無法辨識
- 「修正登入錯誤」→「重寫認證系統」
原始的可以完成
- 原始的變更可以標記為「完成」
- 新工作是獨立的，不是修改
- 完成「加入深色模式 MVP」→ 封存 → 新變更「增強深色模式」
啟發式判斷
┌─────────────────────────────────────┐
│ 這是相同的工作嗎？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
相同的意圖？ >50% 重疊？ 原始工作能否在
相同的問題？ 相同的範圍？ 不包含這些變更的
│ │ 情況下「完成」？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
是 否 是 否 否 是
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新的 更新 新的 更新 新的| 測試 | 更新 | 新變更 |
|---|---|---|
| 身份 | 「相同的事物，經精煉」 | 「不同的工作」 |
| 範圍重疊 | >50% 重疊 | <50% 重疊 |
| 完成 | 無法在不包含變更的情況下「完成」 | 可以完成原始工作，新工作獨立存在 |
| 故事 | 更新的鏈條講述連貫的故事 | 修補會造成混淆，而非釐清 |
原則
更新保留情境。新的變更提供清晰度。
當你的思考歷史有價值時，選擇更新。 當重新開始比修補更清楚時，選擇新的變更。
把它想像成 git 分支：
- 在處理相同功能時持續提交
- 當確實是新的工作時，建立新分支
- 有時合併部分功能，並為第二階段重新開始
有何不同？
舊版 (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| 結構 | 單一大型提案文件 | 具有依賴關係的獨立工件 |
| 工作流程 | 線性階段：規劃 → 實作 → 封存 | 靈活的動作 — 隨時執行任何操作 |
| 迭代 | 回溯相當不便 | 隨著學習進度更新工件 |
| 自訂能力 | 固定結構 | 基於架構（定義您自己的工件） |
關鍵洞察： 工作並非線性。OPSX 不再假裝它是線性的。
架構深入解析
本節說明 OPSX 的內部運作方式，以及它與傳統工作流程的比較。 本節的範例使用擴展命令集（new、continue 等）；預設 core 使用者可將相同的流程對應到 propose → apply → sync → archive。
設計理念：階段 vs 動作
┌─────────────────────────────────────────────────────────────────────────────┐
│ 傳統工作流程 │
│ （階段鎖定、全有或全無） │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 規劃階段 │ ───► │ 實作階段 │ ───► │ 歸檔階段 │ │
│ │ │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • 一次性建立所有產出物 │
│ • 實作期間無法返回更新規格 │
│ • 階段閘門強制線性推進 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX 工作流程 │
│ （流暢動作、迭代式） │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 動作（非階段） │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ 任意順序 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • 逐一建立產出物或快轉 │
│ • 實作期間可更新規格/設計/任務 │
│ • 依賴關係推動進度，不存在階段概念 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘元件架構
傳統工作流程 使用 TypeScript 中的硬編碼範本：
┌─────────────────────────────────────────────────────────────────────────────┐
│ 傳統工作流程元件 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 硬編碼範本（TypeScript 字串） │
│ │ │
│ ▼ │
│ 工具專屬的設定器/適配器 │
│ │ │
│ ▼ │
│ 產生的命令檔案（.claude/commands/openspec/*.md） │
│ │
│ • 固定結構，無產出物感知能力 │
│ • 修改需要改動程式碼並重新建置 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX 使用外部模式定義和依賴圖引擎：
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX 元件 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 模式定義（YAML） │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── 依賴關係 │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob 模式 │ │
│ │ requires: [proposal] ◄── proposal 完成後啟用 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 產出物圖引擎 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • 拓撲排序（依賴順序） │ │
│ │ • 狀態偵測（檔案系統存在性） │ │
│ │ • 豐富指令產生（範本 + 上下文） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 技能檔案（.claude/skills/openspec-*/SKILL.md） │
│ │
│ • 跨編輯器相容（Claude Code、Cursor、Devin） │
│ • 技能透過 CLI 查詢結構化資料 │
│ • 可透過模式檔案完全自訂 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘依賴圖模型
產出物形成有向無環圖（DAG）。依賴關係是啟用條件，而非閘門：
proposal
（根節點）
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
（requires: （requires:
proposal） proposal）
│ │
└─────────────┬─────────────┘
│
▼
tasks
（requires:
specs, design）
│
▼
┌──────────────┐
│ 實作階段 │
│ （requires: │
│ tasks） │
└──────────────┘狀態轉換：
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
缺少依賴 所有依賴 檔案存在於
關係 均為 DONE 檔案系統上資訊流
傳統工作流程 — 代理接收靜態指令：
使用者："/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ 靜態指令： │
│ • 建立 proposal.md │
│ • 建立 tasks.md │
│ • 建立 design.md │
│ • 建立 delta 規格檔案 │
│ │
│ 無法感知已存在什麼或 │
│ 產出物之間的依賴關係 │
└─────────────────────────────────────────┘
│
▼
代理一次性建立所有產出物OPSX — 代理查詢豐富上下文：
使用者："/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ 步驟 1：查詢目前狀態 │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── 第一個就緒 │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", │ │
│ │ "missingDeps": ["specs", "design"]} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ 步驟 2：取得就緒產出物的豐富指令 │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ 步驟 3：讀取依賴 → 建立一個產出物 → 顯示解鎖了什麼 │
└──────────────────────────────────────────────────────────────────────────┘迭代模型
傳統工作流程 — 迭代困難：
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── 「等等，設計有問題」
│ │
│ ├── 選項：
│ │ • 手動編輯檔案（破壞上下文）
│ │ • 放棄並重新開始
│ │ • 硬撐過去，之後再修
│ │
│ └── 沒有正式的「返回」機制
│
└── 一次性建立所有產出物OPSX — 自然迭代：
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── 「設計有問題」
│ │ │
│ │ ▼
│ │ 直接編輯 design.md
│ │ 然後繼續！
│ │ │
│ │ ▼
│ │ /opsx:apply 會從
│ │ 你停下的地方繼續
│ │
│ └── 建立一個產出物，顯示解鎖了什麼
│
└── 搭建變更骨架，等待方向指示自訂模式
使用模式管理命令建立自訂工作流程：
bash
# 從零開始建立新模式（互動式）
openspec schema init my-workflow
# 或分叉現有模式作為起點
openspec schema fork spec-driven my-workflow
# 驗證模式結構
openspec schema validate my-workflow
# 查看模式的解析來源（有助於除錯）
openspec schema which my-workflow模式儲存在 openspec/schemas/（專案本地、版本控制）或 ~/.local/share/openspec/schemas/（使用者全域）。
模式結構：
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.md範例 schema.yaml：
yaml
name: research-first
artifacts:
- id: research # 在 proposal 之前新增
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # 現在依賴 research
- id: tasks
generates: tasks.md
requires: [proposal]依賴圖：
research ──► proposal ──► tasks總結
| 面向 | 傳統 | OPSX |
|---|---|---|
| 範本 | 硬編碼 TypeScript | 外部 YAML + Markdown |
| 依賴關係 | 無（一次性建立） | 具拓撲排序的 DAG |
| 狀態 | 基於階段的心理模型 | 檔案系統存在性 |
| 自訂 | 編輯原始碼、重新建置 | 建立 schema.yaml |
| 迭代 | 階段鎖定 | 流暢，可編輯任何內容 |
| 編輯器支援 | 工具專屬設定器/適配器 | 單一技能目錄 |
Schema
Schema 定義了存在哪些工件及其依賴關係。目前可用：
- spec-driven（預設）：proposal → specs → design → tasks
bash
# 列出可用的 schema
openspec schemas
# 查看所有 schema 及其解析來源
openspec schema which --all
# 以互動方式建立新的 schema
openspec schema init my-workflow
# 複製現有 schema 以進行自訂
openspec schema fork spec-driven my-workflow
# 在使用前驗證 schema 結構
openspec schema validate my-workflow提示
- 使用
/opsx:explore在決定變更前先思考一個想法 - 當你知道你想要什麼時使用
/opsx:ff，探索時使用/opsx:continue - 在
/opsx:apply期間，如果出現問題——修正工件，然後繼續 - 任務透過
tasks.md中的核取方塊追蹤進度 - 隨時檢查狀態：
openspec status --change "name"
意見回饋
這還很粗糙。這是故意的——我們正在學習什麼有效。