OPSX 工作流程
歡迎在 Discord 上提供回饋。
這是什麼？
OPSX 現在是 OpenSpec 的標準工作流程。
這是一個用於 OpenSpec 變更的流暢、迭代的工作流程。不再有僵化的階段——只有您可以隨時採取的行動。
為何存在
舊版 OpenSpec 工作流程可行，但它是封閉的：
- 指令被硬編碼 — 埋藏在 TypeScript 中，你無法更改
- 全有或全無 — 一個大指令建立所有內容，無法單獨測試各部分
- 固定結構 — 每個人都使用相同的工作流程，無法自訂
- 黑箱 — 當 AI 輸出不佳時，你無法調整提示詞
OPSX 將其開放。 現在任何人都可以：
- 實驗指令 — 編輯模板，看看 AI 是否表現更好
- 細粒度測試 — 獨立驗證每個產出物的指令
- 自訂工作流程 — 定義你自己的產出物和依賴關係
- 快速迭代 — 更改模板，立即測試，無需重新建置
舊版工作流程： OPSX：
┌────────────────────────┐ ┌────────────────────────┐
│ 硬編碼在套件中 │ │ schema.yaml │◄── 你編輯這個
│ （無法更改） │ │ templates/*.md │◄── 或這個
│ ↓ │ │ ↓ │
│ 等待新版本發布 │ │ 立即生效 │
│ ↓ │ │ ↓ │
│ 祈禱它更好 │ │ 自己測試 │
└────────────────────────┘ └────────────────────────┘這適用於所有人：
- 團隊 — 建立符合你實際工作方式的工作流程
- 進階使用者 — 調整提示詞，為你的程式碼庫獲得更好的 AI 輸出
- OpenSpec 貢獻者 — 無需發布新版本即可實驗新方法
我們都還在學習什麼最有效。OPSX 讓我們能一起學習。
使用者體驗
線性工作流程的問題： 你處於「規劃階段」，然後是「實作階段」，最後「完成」。但實際工作並非如此。你實作某個功能，發現設計有誤，需要更新規格，然後繼續實作。線性階段與工作的實際運作方式相悖。
OPSX 方法：
- 動作，而非階段 — 建立、實作、更新、歸檔 — 隨時執行任何一個
- 依賴是促成因素 — 它們顯示可能性，而非接下來的必要步驟
提案 ──→ 規格 ──→ 設計 ──→ 任務 ──→ 實作設定
bash
# 確保你已安裝 openspec — 技能會自動生成
openspec init這會在 .claude/skills/（或同等位置）中建立技能，AI 程式碼助手會自動偵測。
預設情況下，OpenSpec 使用 core 工作流程設定檔（propose、explore、apply、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 | 新變更的預設架構（例如 spec-driven） |
context | string | 注入所有產出物指令的專案上下文 |
rules | object | 每個產出物的規則，以產出物 ID 為鍵 |
運作方式
架構優先順序（由高到低）：
- CLI 旗標（
--schema <name>） - 變更中繼資料（變更目錄中的
.openspec.yaml） - 專案設定（
openspec/config.yaml） - 預設值（
spec-driven）
上下文注入：
- 上下文會前置到每個產出物的指令
- 包裹在
<context>...</context>標籤中 - 幫助 AI 理解你專案的慣例
規則注入：
- 規則僅注入到匹配的產出物
- 包裹在
<rules>...</rules>標籤中 - 出現在上下文之後、模板之前
依架構區分的產出物 ID
spec-driven（預設）：
proposal— 變更提案specs— 規格design— 技術設計tasks— 實作任務
設定驗證
rules中未知的產出物 ID 會產生警告- 架構名稱會根據可用架構進行驗證
- 上下文有 50KB 大小限制
- 無效的 YAML 會報告行號
疑難排解
「規則中未知的產出物 ID：X」
- 檢查產出物 ID 是否與你的架構匹配（參見上方列表）
- 執行
openspec schemas --json查看每個架構的產出物 ID
設定未被套用：
- 確保檔案位於
openspec/config.yaml（不是.yml） - 使用驗證器檢查 YAML 語法
- 設定變更立即生效（無需重啟）
上下文過大：
- 上下文限制為 50KB
- 改為總結或連結到外部文件
指令
| 指令 | 功能 |
|---|---|
/opsx:propose | 一步建立變更並生成規劃產出物（預設快速路徑） |
/opsx:explore | 思考想法、調查問題、釐清需求 |
/opsx:new | 開始新的變更腳手架（擴展工作流程） |
/opsx:continue | 建立下一個產出物（擴展工作流程） |
/opsx:ff | 快進規劃產出物（擴展工作流程） |
/opsx:apply | 實作任務，並根據需要更新產出物 |
/opsx:verify | 根據產出物驗證實作（擴展工作流程） |
/opsx:sync | 將差異規格同步到主線（預設工作流程，可選） |
/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:archive # 完成後移至歸檔（如果需要，會提示同步規格）何時更新 vs. 全新開始
你總是可以編輯你的提案或規格。但何時精煉會變成「這是不同的工作」？
提案捕捉的內容
提案定義三件事：
- 意圖 — 你要解決什麼問題？
- 範圍 — 什麼在範圍內/外？
- 方法 — 你將如何解決？
問題是：哪個改變了，改變了多少？
在以下情況更新現有變更：
相同意圖，精煉執行
- 你發現未考慮的邊界情況
- 方法需要調整但目標未變
- 實作揭示設計略有偏差
範圍縮小
- 你意識到完整範圍太大，想先發布最小可行產品
- 「新增深色模式」→「新增深色模式開關（系統偏好設定在 v2）」
學習驅動的修正
- 程式碼庫結構與你想的不同
- 依賴項運作不如預期
- 「使用 CSS 變數」→「改用 Tailwind 的 dark: 前綴」
在以下情況開始新變更：
意圖根本改變
- 問題本身現在不同了
- 「新增深色模式」→「新增包含自訂顏色、字體、間距的完整主題系統」
範圍爆炸
- 變更增長太多，本質上是不同的工作
- 更新後原始提案將面目全非
- 「修復登入錯誤」→「重寫驗證系統」
原始變更可完成
- 原始變更可以標記為「完成」
- 新工作獨立存在，而非精煉
- 完成「新增深色模式最小可行產品」→歸檔→新變更「增強深色模式」
啟發式方法
┌─────────────────────────────────────┐
│ 這是相同的工作嗎？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
相同意圖？ >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、Windsurf） │
│ • 技能透過 CLI 查詢結構化資料 │
│ • 可透過結構描述檔案完全自訂 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘依賴圖模型
產出物構成一個有向無環圖（DAG）。依賴關係是啟用條件，而非閘門：
proposal
（根節點）
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
（requires: （requires:
proposal） proposal）
│ │
└─────────────┬─────────────┘
│
▼
tasks
（requires:
specs, design）
│
▼
┌──────────────┐
│ APPLY 階段 │
│ （requires: │
│ tasks） │
└──────────────┘狀態轉換：
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
缺少依賴 所有依賴 檔案存在
已完成 於檔案系統資訊流
傳統工作流程 — 代理接收靜態指令：
使用者："/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ 靜態指令： │
│ • 建立 proposal.md │
│ • 建立 tasks.md │
│ • 建立 design.md │
│ • 建立 specs/<capability>/spec.md │
│ │
│ 無法感知現有內容或 │
│ 產出物間的依賴關係 │
└─────────────────────────────────────────┘
│
▼
代理一次建立所有產出物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"]}│ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ 步驟 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 |
| 迭代 | 階段鎖定 | 流暢，可編輯任何內容 |
| 編輯器支援 | 工具專用設定器/轉接器 | 單一技能目錄 |
架構
架構定義了存在哪些產出物及其相依關係。目前可用的架構：
- 規格驅動（預設）：提案 → 規格 → 設計 → 任務
bash
# 列出可用的架構
openspec schemas
# 查看所有架構及其解析來源
openspec schema which --all
# 互動式建立新架構
openspec schema init my-workflow
# 分叉現有架構以進行自訂
openspec schema fork spec-driven my-workflow
# 使用前驗證架構結構
openspec schema validate my-workflow提示
- 使用
/opsx:explore在提交變更前先梳理想法 - 當你確定目標時使用
/opsx:ff，探索時使用/opsx:continue - 在
/opsx:apply過程中，若發現問題 — 修正產出物，然後繼續 - 任務透過
tasks.md中的核取方塊追蹤進度 - 隨時檢查狀態：
openspec status --change "name"
回饋
目前版本較為粗糙。這是刻意的 — 我們正在學習什麼方式有效。