OPSX 工作流程
歡迎在 Discord 上提供回饋。
它是什麼？
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、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，E2E 測試使用 Playwright
# 風格規範：搭配 Prettier 使用 ESLint，嚴格模式 TypeScript
rules:
proposal:
# 包含復原方案
# 標註受影響的團隊
specs:
# 場景使用 Given/When/Then 格式
design:
# 複雜流程需包含序列圖設定欄位
| 欄位 | 類型 | 說明 |
|---|---|---|
schema | 字串 | 新變更的預設 schema（例如 spec-driven） |
context | 字串 | 注入所有產物指令的專案上下文 |
rules | 物件 | 以產物 ID 為鍵的個別產物規則 |
運作方式
Schema 優先順序（從高到低）：
- CLI 參數（
--schema <名稱>） - 變更中繼資料（變更目錄下的
.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 | 將差異規格同步至主分支（預設工作流程，選填） |
/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:update add-dark-mode - we're storing the theme in a cookie now修改變更的既有規劃產物並保持一致性——修改方向不限（例如調整設計可能導致提案也需要同步修改）。僅修改規劃產物：不會編輯程式碼，也不會建立遺漏的產物（建立產物請使用 /opsx:continue）。所有修改都會先經過你確認。如果該變更已經進入實作階段，系統會建議你執行 /opsx:apply，讓程式碼跟上修訂後的規劃。如果你的修改會改變變更的核心目的，建議重新建立變更，詳情見〈何時修改 vs 重新建立〉。
完成收尾
/opsx:archive # 完成後移動至封存區（如有需要會提示同步規格書）何時修改現有變更 vs 重新建立
在實作前，你隨時可以編輯提案或規格書。但何時「優化」會變成「這是不同的工作」？
提案記錄的內容
一份提案定義了三項內容：
- 核心目的——你要解決什麼問題？
- 範圍——包含什麼、不包含什麼？
- 實作方案——你要如何解決？
關鍵在於：哪項內容改變了、改變幅度有多大？
符合以下情況時，修改現有變更：
核心目的相同，僅優化實作方式
- 你發現之前未考慮到的邊界情況
- 方案需要微調，但目標不變
- 實作過程中發現設計有輕微偏差
範圍縮小
- 你發現完整範圍過大，想先推出最小可行產品（MVP）
- 「新增深色模式」→「新增深色模式切換功能（v2 版本再加入系統偏好設定）」
基於學習的修正
- 程式碼庫的結構與你原本預期的不同
- 某個相依套件的運作方式與預期不符
- 「使用 CSS 變數」→「改用 Tailwind 的 dark: 前綴」
符合以下情況時，重新建立變更：
核心目的根本改變
- 要解決的問題本身已經不同
- 「新增深色模式」→「新增完整的主題系統，支援自訂顏色、字體、間距」
範圍大幅擴張
- 變更內容增加太多，實質上已是不同的工作
- 更新後的原始提案會面目全非
- 「修復登入錯誤」→「重寫驗證系統」
原始變更可標記為完成
- 原始變更可以標記為「已完成」
- 新工作可獨立存在，並非對原有工作的優化
- 完成「新增深色模式 MVP」→ 封存 → 新建立「強化深色模式」變更
判斷準則
┌─────────────────────────────────────┐
│ 這是相同的工作嗎？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
核心目的相同？ 重疊度 >50%？ 原始變更不做這些修改
問題相同？ 範圍相同？ 能否「完成」？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
是 否 是 否 否 是
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
修改 重新建立 修改 重新建立 修改 重新建立| 判斷維度 | 修改現有變更 | 重新建立變更 |
|---|---|---|
| 本質辨識 | 「相同工作，僅優化」 | 「不同的工作」 |
| 範圍重疊度 | 重疊度 >50% | 重疊度 <50% |
| 完成可行性 | 不做修改就無法標記為「完成」 | 可完成原始變更，新工作可獨立存在 |
| 脈絡連貫性 | 修改鏈能構成連貫的開發脈絡 | 補丁式修改會造成更多混淆而非釐清 |
核心原則
修改保留脈絡，重新建立提供清晰度。 當你的思考歷程具有參考價值時，選擇修改。 當重新開始比補丁式修改更清晰時，選擇重新建立。
可以類比成 Git 分支：
- 開發同一功能時持續提交
- 當工作是全新的時，建立新分支
- 有時可以合併部分功能，再為第二階段重新建立分支
與舊版的差異
舊版（/openspec:proposal） | OPSX（/opsx:*） | |
|---|---|---|
| 結構 | 單一龐大的提案文件 | 具有相依關係的獨立產物 |
| 工作流程 | 線性階段：規劃 → 實作 → 封存 | 彈性行動——隨時可執行任何動作 |
| 迭代方式 | 回頭修改非常麻煩 | 邊學習邊更新產物 |
| 自訂程度 | 結構固定 | 由 Schema 驅動（可自行定義產物） |
核心洞見：工作並非線性進行。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 ◄── 萬用字元模式 │ │
│ │ requires: [proposal] ◄── 提案完成後啟用 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 產物圖引擎 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • 拓撲排序（依賴順序） │ │
│ │ • 狀態偵測（檔案系統是否存在） │ │
│ │ • 豐富指令生成（範本 + 上下文） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 技能檔案（.claude/skills/openspec-*/SKILL.md） │
│ │
│ • 跨編輯器相容（Claude Code、Cursor、Windsurf） │
│ • 技能查詢 CLI 用於取得結構化資料 │
│ • 可透過結構描述檔案完全自訂 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘依賴圖模型
產物構成有向無環圖（DAG）。依賴關係是啟用條件，而非閘門：
提案
（根節點）
│
┌─────────────┴─────────────┐
│ │
▼ ▼
規格 設計
（依賴： （依賴：
提案） 提案）
│ │
└─────────────┬─────────────┘
│
▼
任務
（依賴：
規格、設計）
│
▼
┌──────────────┐
│ APPLY 階段 │
│（依賴： │
│ 任務） │
└──────────────┘狀態轉換：
阻塞 ────────────────► 就緒 ────────────────► 完成
│ │ │
缺少依賴關係 所有依賴 檔案存在於
皆完成 檔案系統中資訊流
舊版工作流程 — 代理程式接收靜態指令：
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ 靜態指令： │
│ • 建立 proposal.md │
│ • 建立 tasks.md │
│ • 建立 design.md │
│ • 建立 specs/<capability>/spec.md │
│ │
│ 不知道現有檔案狀態，也不了解 │
│ 產物之間的依賴關係 │
└─────────────────────────────────────────┘
│
▼
Agent 一次性建立所有產物OPSX — 代理程式查詢豐富上下文：
User: "/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 會從
│ │ 你上次中斷的地方繼續
│ │
│ └── 一次產生單一產出物，並顯示已解鎖的後續步驟
│
└── 建立變更的基礎框架，等待後續指示自訂 Schema
使用以下 Schema 管理指令建立自訂工作流程：
bash
# 從頭建立新的 Schema（互動模式）
openspec schema init my-workflow
# 或基於現有 Schema 分支作為起點
openspec schema fork spec-driven my-workflow
# 驗證你的 Schema 結構
openspec schema validate my-workflow
# 查看 Schema 的解析來源（除錯時很有用）
openspec schema which my-workflowSchema 會儲存在 openspec/schemas/（專案本機、版本控制）或 ~/.local/share/openspec/schemas/（使用者全域）目錄下。
Schema 結構：
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.mdschema.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 |
| 迭代方式 | 階段鎖定 | 彈性流暢，可隨意編輯任何內容 |
| 編輯器支援 | 工具專屬的設定器/適配器 | 單一 skills 目錄 |
Schema
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"查看狀態
回饋
這個功能還在早期開發階段，這是刻意的——我們正在測試什麼方案最有效。