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、archive）。如果您想使用擴展的工作流程指令（new、continue、ff、verify、sync、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 <名稱>；否則應從對話中推斷，如果無法判斷會提示您選擇。
完成
/opsx:archive # 完成後移至歸檔（如需要會提示同步規格）何時更新 vs. 重新開始
您總可以在實作前編輯提案或規格。但何時精煉會變成「這是不同的工作」？
提案捕捉的內容
提案定義三件事：
- 意圖 — 您要解決什麼問題？
- 範圍 — 哪些在範圍內/外？
- 方法 — 您將如何解決？
問題是：什麼改變了，改變了多少？
在以下情況更新現有變更：
相同意圖，精煉執行
- 您發現未考慮的邊緣情況
- 方法需要微調但目標不變
- 實作揭示設計略有偏差
範圍縮小
- 您發現完整範圍太大，想先發布 MVP
- 「新增深色模式」→「新增深色模式開關（v2 中使用系統偏好設定）」
基於學習的修正
- 程式碼庫結構與您預期不同
- 依賴項不如預期運作
- 「使用 CSS 變數」→「改用 Tailwind 的 dark: 前綴」
在以下情況開始新變更：
意圖根本改變
- 問題本身已不同
- 「新增深色模式」→「新增包含自訂顏色、字體、間距的完整主題系統」
範圍擴大
- 變更增長到本質上是不同的工作
- 原始提案在更新後將無法辨識
- 「修復登入錯誤」→「重寫認證系統」
原始變更可完成
- 原始變更可標記為「完成」
- 新工作獨立存在，非精煉
- 完成「新增深色模式 MVP」→ 歸檔 → 新變更「增強深色模式」
判斷標準
┌─────────────────────────────────────┐
│ 這是相同的工作嗎？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
相同意圖？ >50% 重疊？ 原始變更能否
相同問題？ 相同範圍？ 在無此變更下
│ │ 「完成」？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
是 否 是 否 否 是
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新變更 更新 新變更 更新 新變更| 測試 | 更新 | 新變更 |
|---|---|---|
| 本質 | 「相同事物，精煉」 | 「不同工作」 |
| 範圍重疊 | >50% 重疊 | <50% 重疊 |
| 完成度 | 無此變更無法「完成」 | 可完成原始變更，新工作獨立存在 |
| 敘事 | 更新鏈講述連貫故事 | 補丁會造成更多混淆而非釐清 |
原則
更新保留上下文。新變更提供清晰度。
當您的思考歷史有價值時，選擇更新。 當重新開始比修補更清晰時，選擇新變更。
將其視為 git 分支：
- 在開發相同功能時持續提交
- 在真正開始新工作時建立新分支
- 有時合併部分功能，然後為第二階段重新開始
有什麼不同？
Legacy (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| 結構 | 一個大型提案文件 | 具有依賴關係的離散工件 |
| 工作流程 | 線性階段：規劃 → 實施 → 歸檔 | 流動操作——隨時可執行任何操作 |
| 迭代 | 回溯修改較為不便 | 隨著學習進展更新工件 |
| 自訂性 | 固定結構 | 由 Schema 驅動（可定義自己的工件） |
關鍵洞察： 工作並非線性。OPSX 不再假裝它是。
架構深入解析
本節說明 OPSX 的運作原理，以及它與傳統工作流程的比較。 本節中的範例使用擴展指令集（new、continue 等）；預設的 core 使用者可以將相同的流程對應到 propose → apply → 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 ◄── 萬用字元模式 │ │
│ │ requires: [proposal] ◄── 在 proposal 後啟用 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 產物圖引擎 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • 拓撲排序（依賴順序） │ │
│ │ • 狀態偵測（檔案系統存在性） │ │
│ │ • 豐富指令產生（範本 + 上下文） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 技能檔案 (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • 跨編輯器相容（Claude Code, Cursor, Windsurf） │
│ • 技能查詢 CLI 以取得結構化資料 │
│ • 完全可透過結構描述檔案自訂 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘依賴圖模型
產物形成一個有向無環圖（DAG）。依賴關係是啟用者，而非門檻：
proposal
（根節點）
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
（需要： （需要：
proposal） proposal）
│ │
└─────────────┬─────────────┘
│
▼
tasks
（需要：
specs, design）
│
▼
┌──────────────┐
│ 應用階段 │
│ （需要： │
│ tasks） │
└──────────────┘狀態轉換：
已封鎖 ────────────────► 就緒 ────────────────► 完成
│ │ │
缺少 所有依賴 檔案存在
依賴 已完成 於檔案系統資訊流
傳統工作流程 — 代理接收靜態指令：
使用者："/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"
回饋
目前版本較為粗糙。這是刻意的安排——我們正在學習什麼方案有效。