OpenSpec 是一套給 AI Coding Agent 使用的規格驅動開發工具。它把原本散落在聊天紀錄裡的需求，整理成可以審查、修改與提交到 Git 的 Markdown 文件，讓人類和 AI 在寫程式之前先確認「為什麼改、要改什麼、怎麼做」。
網路上不少 OpenSpec 教學仍停留在 1.0 以前，使用 /openspec:proposal、/openspec:apply 這套舊流程。OpenSpec 1.0 已經改用 OPSX 工作流程，後續版本又加入 profile、Stores、Codex Skills、通用 .agents 目錄與更嚴格的驗證。npm 官方 registry 在 2026 年 8 月 13 日晚間將 1.9.0 設為 latest，因此本文以 1.9 為準；此時 GitHub CHANGELOG 仍停在 1.8.0，剛升級的讀者應以實際安裝版本為準。
OpenSpec 是什麼，為什麼要用
OpenSpec 最基本的用法，是由使用者描述需求，AI Coding Agent 整理成提案，再由使用者檢查規格與工作清單。確認內容沒有偏離需求後，交給 AI 實作；成果通過檢查後，再由 AI 將這次變更與規格歸檔。
AI 寫程式常見的問題不是不會寫，而是需求只存在對話上下文。討論時間一長、執行 compact、換一個 Agent，或是同時開多個工作階段，原本談好的限制就可能被遺漏。一般提示詞能告訴 AI 這一輪要做什麼，卻不等於一份可以長期維護的系統規格。
OpenSpec 在專案裡建立一層輕量的 specification workflow。預設 spec-driven schema 會為變更建立 proposal、Delta Spec、design 與 tasks，完成後再把差異合併回主規格。這些檔案跟程式碼一起進 Git，因此 code review 不只能看「改了哪些程式」，也能看「實作是否符合原本答應的行為」。
它特別適合以下情境：
- 功能會改到多個模組，無法靠一段 prompt 說清楚。
- 同時使用 Claude Code、Codex、Cursor 或 GitHub Copilot，希望共用同一份需求。
- 多人或多個 Agent 平行開發，需要知道哪些變更已確認、哪些仍在規劃。
- 既有系統持續演進，需要保留需求變更與設計決策的歷史。
不過，不是每次改字或修一行設定都要建立完整規格。小型、低風險且不改變外部行為的工作，可以直接處理；純重構、工具或文件變更，也能從 1.7 起在 change metadata 使用 skip_specs: true，保留工作清單但略過 Delta Spec。
OpenSpec 1.0 到 1.9 的差異
OpenSpec 1.0 不是單純換版號，而是把原本線性的 proposal → apply → archive 流程重做成 OPSX action。後續 1.x 的方向大致分成三條：讓規劃流程更彈性、支援更多 AI 工具，以及提高同步與驗證的安全性。
| 版本 | 發布時間 | 主要變化 |
|---|---|---|
| 1.0 | 2026-01-26 | OPSX action-based workflow、動態 instructions、語意化 Delta Spec 同步與 Agent Skills。 |
| 1.1 | 2026-01-30 | 修正 Codex 全域路徑、跨磁碟 archive 與 Windsurf workflow 路徑。 |
| 1.2 | 2026-02-23 | 新增 core／custom profile、一步完成規劃的 propose，以及 AI 工具自動偵測。 |
| 1.3 | 2026-04-11 | 加入 Junie、Lingma、ForgeCode、IBM Bob，改善 shell completion 與 JSON 輸出。 |
| 1.4 | 2026-06-01 | 加入 Kimi CLI、Mistral Vibe，並把 sync 納入預設 core profile。 |
| 1.5 | 2026-06-28 | 推出早期 beta 的 Stores，讓多個 repository 共用獨立規格庫。 |
| 1.6 | 2026-07-10 | 新增 /opsx:update、Oh My Pi 與 TRAE，強化 archive exit code 與 requirement parser。 |
| 1.7 | 2026-07-29 | Codex 改成 Skills-only、加入 skip_specs、自動提醒升級 CLI，並支援獨立安裝 Skills。 |
| 1.8 | 2026-08-05 | 加入通用 .agents/skills、Copilot coding agent、MiniMax Code、Rovo Dev，以及 capability retirement。 |
| 1.9 | 2026-08-13 | npm latest 新增 validate --archived 與 Command Code 整合。 |
1.8 把 Codex Skills 搬到共用的 .agents/skills/，同時新增 vendor-neutral 的 agents target。普通模式也不再強制需求內文一定要出現英文 SHALL／MUST，中文規格可以通過驗證，但 --strict 仍會執行這項規則。
1.9 的官方 npm 套件已加入 openspec validate --archived，用來檢查已歸檔 change 是否還留著未勾選的 task，也加入 Command Code adapter。由於套件發布時間早於 GitHub CHANGELOG 更新，這一版先只列出能從正式套件直接確認的功能。
OpenSpec 的基本運作邏輯
OpenSpec 的核心只有兩個區域：openspec/specs/ 描述系統目前已經成立的行為，openspec/changes/ 放尚未完成的變更。新的功能不會直接覆寫主規格，而是先在 change 裡描述差異；實作、驗證和審查完成後，再把差異合併回主規格並歸檔。
主規格與變更資料夾
openspec/
├── specs/ # 系統目前的正式規格
│ └── auth/
│ └── spec.md
├── changes/
│ └── add-passkey-login/
│ ├── .openspec.yaml # schema 與 change metadata
│ ├── proposal.md # 為什麼改、範圍是什麼
│ ├── design.md # 技術設計與取捨
│ ├── tasks.md # 實作清單
│ └── specs/auth/spec.md # 相對於主規格的 Delta
└── config.yaml # 專案背景、規則與 schema 設定在預設 spec-driven schema 裡，proposal.md 回答 why 與 scope，specs/ 回答系統行為要怎麼改，design.md 記錄技術方案，tasks.md 則讓 Agent 知道實作進度。這些 artifact 可以反覆修改，不是產生後就不能回頭；custom schema 或 skip_specs change 的檔案組合可能不同。
Delta Spec 的四種操作
ADDED Requirements：加入新的 requirement。MODIFIED Requirements：更新既有 requirement，archive 時會取代原版本。REMOVED Requirements：刪除不再成立的 requirement。RENAMED Requirements：保留內容，只調整 requirement 名稱。
## ADDED Requirements
### Requirement: Passkey Login
The system SHALL allow a registered user to sign in with a passkey.
#### Scenario: Successful passkey authentication
- **GIVEN** the user has registered a passkey
- **WHEN** the user completes platform authentication
- **THEN** the system creates an authenticated sessionRequirement 是可驗證的行為，不是「做一個登入頁」這種工作項目；Scenario 則用 GIVEN／WHEN／THEN 描述可觀察結果。tasks 可以寫「建立 WebAuthn controller」，但 spec 應該寫使用者在什麼條件下能完成登入。
OpenSpec 安裝與初始化
OpenSpec 1.9 需要 Node.js 20.19.0 以上。先確認版本，再用 npm 全域安裝官方套件：
# Node.js 必須是 20.19.0 以上
node --version
# 安裝目前最新穩定版
npm install -g @fission-ai/openspec@latest
# 確認實際執行到的版本
openspec --version官方也支援 pnpm、Yarn、Bun 與 Nix。使用哪一個套件管理器不會改變 OpenSpec 的資料格式；重點是日後升級要繼續用同一個工具，避免 PATH 上同時留下兩套不同版本。
# 擇一使用，不需要全部安裝
pnpm add -g @fission-ai/openspec@latest
yarn global add @fission-ai/openspec@latest
bun add -g @fission-ai/openspec@latest互動式初始化
進入既有專案根目錄執行 openspec init。設定精靈會偵測專案內的 Claude Code、Cursor 等工具目錄，讓我們選擇要安裝哪些 workflow skills 與 command files。
cd your-project
openspec init自動化環境可以用逗號分隔 tool ID。Claude Code 與 Codex 同時使用時，可以這樣初始化：
openspec init --tools claude,codex
# 只安裝 AGENTS.md 相容工具共用的 Skills
openspec init --tools agents1.8 之後，Codex 與通用 agents target 都會使用 .agents/skills/。這不代表可以刪掉專案自己的 AGENTS.md；前者是 OpenSpec workflow skill，後者仍然負責專案規則與操作慣例。
Core 與 custom profile
預設 core profile 已包含 propose、explore、apply、update、sync、archive，足以完成一般工作。需要逐份 artifact 控制、verify 或 bulk archive 時，再用互動式設定挑選 custom workflows：
openspec config profile
openspec update調整 global profile 後一定要執行 openspec update，它才會重新產生目前專案的 skills 與 commands。升級 CLI 也是同樣順序：先更新 npm 套件，再跑 update。
OPSX 完整工作流程
探索與提案
需求還很模糊時，先在 AI 工具的聊天輸入 /opsx:explore。這個模式可以讀 codebase、比較方案，初始探索不會直接進入程式實作；若使用者接受 capture，1.8 起也能建立 change 與所需 artifacts。方向已經確定時可以直接用 propose：
/opsx:explore
評估目前密碼登入加入 Passkey 的影響，包含舊瀏覽器 fallback。
/opsx:propose add-passkey-login/opsx:propose 是 1.2 起的快速入口，使用預設 spec-driven schema 時，會建立 change 並一次產生 proposal、specs、design、tasks。複雜需求若希望逐份確認，可以改用 custom profile 的 /opsx:new 搭配 /opsx:continue，或用 /opsx:ff 一次補齊。
Propose 與 proposal 的差別
propose 是動詞，在新版 OpenSpec 代表「提出一項變更」的 action，也就是 /opsx:propose 指令。proposal 是名詞，通常指 change 裡的 proposal.md 提案文件。執行 propose 會產生 proposal，但還會依 schema 建立 specs、design 與 tasks，因此兩者不是新舊檔名，也不能互換。
| 名稱 | 性質 | 用途 |
|---|---|---|
/opsx:propose | 新版 action／指令 | 建立 change，並產生實作前需要的 artifacts。 |
proposal.md | Artifact／文件 | 記錄為什麼要改、要改什麼與影響範圍。 |
/openspec:proposal | 1.0 以前的 legacy 指令 | 舊版一次建立 proposal、specs、design 與 tasks。 |
因此，1.0 以前的教學多半會看到 /openspec:proposal。1.0 改成 OPSX action-based workflow 後，早期 OPSX 教學會用 /opsx:new 建立 change，再用 /opsx:continue 逐份產生 artifact，或用 /opsx:ff 一次完成。1.2 才加入現在的 /opsx:propose，把 new 與 fast-forward 的常用組合收成一步。最新版文件仍把 /openspec:proposal 列為 legacy workflow，主要供既有專案使用；新專案以 OPSX 指令為準。
官方 release note 沒有把改名理由單獨列成一項決策。不過，1.0 將整套流程定位為 action-based system，而新版指令也統一採用 explore、propose、apply、sync、archive 等動詞；文件則繼續使用 proposal、design、tasks 等名詞。依這套命名可以看出，調整後能把「執行什麼動作」與「產生哪份文件」分開，也更符合 propose 會一次建立多種 artifacts 的實際行為。這是根據官方命名與工作流程做出的解讀，不是官方公布的原話。
審查與實作
propose 完成不代表立刻接受。先閱讀該 schema 產生的 artifacts，特別檢查需求邊界、例外情境、是否誤改既有行為，以及 tasks 是否真的涵蓋 spec。需要調整時直接編輯 Markdown，或使用 1.6 新增的 /opsx:update 讓 AI 協調相關 artifact。
/opsx:update add-passkey-login
保留密碼登入，不把 Passkey 設為唯一登入方式；同步修改 spec、design 與 tasks。
/opsx:apply add-passkey-loginapply 會依 tasks 實作並勾選進度，但 task 被勾起來不等於功能一定正確。custom workflow 可以用 /opsx:verify 比對實作與規格；即使只使用 core profile，也應執行專案本身的測試、lint 和 build。
同步與歸檔
/opsx:sync 會先把 Delta Spec 合併回主規格，但保留 active change。一般流程不需要單獨執行 sync，完成實作與驗證後直接執行 archive 即可；如果 Delta Spec 尚未合併，archive 會先詢問是否同步。長期開發、其他平行 change 需要先使用新的主規格，或想在歸檔前檢查合併結果時，才需要提早執行 sync。
# 可選：先更新主規格，但 change 仍保持 active
/opsx:sync add-passkey-login
# 完成後同步並移到 changes/archive/
/opsx:archive add-passkey-login在沒有互動 stdin 的 Agent 或 CI 裡直接呼叫 CLI archive，要明確提供 change 名稱與 --yes，否則新版會安全地退出並提示正確指令，不會猜測要歸檔哪一項。
openspec archive add-passkey-login --yesSkill 操作與 CLI 的角色
使用 Claude Code、Codex 等 AI Coding Agent 時，日常操作的重點是理解 OpenSpec 的 workflow 與 Skill。常見流程是提出變更、確認 artifacts、實作、測試／驗證，再把成果歸檔。/opsx:... 或各工具對應的 Skill 是使用者下達工作意圖的入口；Agent 會依 Skill instructions 呼叫 openspec ... CLI、讀寫 artifacts，並在需要額外權限時等待確認。
CLI 主要用來理解與排錯
終端機 CLI 不需要每一條都背起來。了解 init、status、validate、archive 等動作，就能從 Agent 的執行紀錄判斷目前是在初始化、檢查規格，還是正式歸檔。遇到 Agent 卡住、PATH 指到舊版本或 CI 驗證失敗時，再親自使用對應指令排查；首次初始化、切換 profile 或更新 Skills，也可能需要手動執行。
| 指令 | 用途 |
|---|---|
openspec init | 初始化專案與 AI 工具整合。 |
openspec update | 升級後重新產生 skills 與 commands。 |
openspec list | 列出 active changes。 |
openspec list --specs | 列出目前主規格。 |
openspec show <name> | 查看 change 或 spec 詳細內容。 |
openspec status --change <name> | 查看 artifact 是否 ready、blocked 或完成。 |
openspec validate <name> --strict | 嚴格驗證指定 change。 |
openspec validate --all --no-interactive | 在 CI 驗證所有 active change 與 specs。 |
openspec validate --archived | 1.9 新增，檢查 archive 是否仍有未完成 tasks。 |
openspec config profile | 選擇 core／custom workflows 與 delivery。 |
openspec completion install zsh | 安裝 shell tab completion。 |
Skill 與聊天指令的呼叫方式
| 工具 | Propose 範例 |
|---|---|
| Claude Code、Gemini CLI | /opsx:propose |
| Cursor、GitHub Copilot IDE | /opsx-propose |
| Codex | $openspec-propose |
| 通用 Skills-only 工具 | /openspec-propose |
| Kimi Code | /skill:openspec-propose |
不同寫法只反映各工具顯示 Skill／command 的方式不同，背後仍使用同一套 OpenSpec artifacts。比起背誦 CLI 參數，更重要的是知道 propose 會建立規劃文件、apply 進入實作，archive 則會完成並保存變更，必要時處理 Spec 同步。實際呼叫形式以 openspec init 完成後顯示的提示為準。
舊版 OpenSpec 升級方式
從 0.x 或早期 1.x 升級時，先更新 CLI，再回到每個專案執行 init／update。1.0 以前的 change、archive 與主規格可以保留，初始化程序會辨識舊檔案並在清理前要求確認。
npm install -g @fission-ai/openspec@latest
openspec --version
cd your-project
openspec init
openspec update
openspec validate --all如果升級後仍顯示舊版，通常是 PATH 上還有另一個 npm、pnpm、Bun 或 Volta 安裝。先用 which openspec（Windows 使用 where openspec）確認實際執行檔，再用原本擁有該安裝的套件管理器更新。
舊文章常見的 /openspec:proposal 等 legacy 指令，不應再作為新專案的主要流程。最新版文件仍保留部分相容說明，但新安裝應以 /opsx:propose、/opsx:apply、/opsx:archive 為準。
常見問答
OpenSpec 免費嗎？需要 API Key 嗎？
OpenSpec 本身採 MIT 授權，不需要 API Key。它只負責規格格式、CLI 與 AI 工具的 workflow instructions；Claude Code、Codex、Cursor 等 AI 工具的訂閱或 API 費用仍然各自計算。
OpenSpec 會取代 CLAUDE.md 或 AGENTS.md 嗎？
不會。CLAUDE.md／AGENTS.md 適合放整個 repository 長期成立的規則，例如測試指令、架構慣例與禁止事項；OpenSpec 描述某項變更的動機、需求、設計和 tasks。兩者解決的問題不同。
規格可以用中文嗎？
可以。1.8 起，一般 validate 把英文 SHALL／MUST 視為建議，不再阻擋其他語言的 requirement；但是 --strict 仍會強制檢查。若團隊要在 CI 使用 strict mode，可以採用中文敘述搭配 SHALL／MUST 關鍵字。
專案開發到一半可以使用 OpenSpec 嗎？
可以。OpenSpec 本來就重視既有專案的持續修改，不需要重新建立專案，也不用先替所有程式補規格。在 repository 執行 openspec init 後，先挑下一個範圍明確、確實要完成的變更，讓 Agent 用 /opsx:explore 閱讀相關程式，再從 propose、apply 到 archive 走完一次。已完成的功能可以先維持原狀；之後修改哪個範圍，再逐步累積該領域的 Specs。
已經開發好的系統可以補上 Spec 嗎？
可以，但不建議一次把整套系統倒推成完整 Specs。現有程式、測試、API 文件、PRD 與操作文件都能作為 Agent 探索的來源；先挑下一個要修改的功能，確認目前行為，再寫與這次 change 有關的 requirement 和 scenario。每次 archive 都會把經過確認的 Delta Spec 合併回主規格，規格便能隨實際變更逐步補齊。
如果既有系統有重要且相對穩定的規格，也可以主動建立 baseline Spec，不必等到下一次修改。例如登入與權限、安全邊界、付款與退款、公開 API 契約、資料保存期限、法規要求，以及跨服務介面，都值得優先建檔。先讓 Agent 探索相關程式、測試與既有文件，整理可觀察的目前行為，再由熟悉該領域的人確認；確認後可建立 openspec/specs/<domain>/spec.md，而不是用 Delta Spec 把既有行為誤寫成新功能。無法從程式或文件證實的內容應列為待確認，不能由 AI 自行補完。官方所說的不要全面回填，重點是避免無差別產生大量容易過期的文件，不是禁止替重要規格建檔。
OpenSpec 目前沒有「建立 baseline」的專用指令。這是一種進階的主動建檔方式，可以按照以下步驟進行：
- 執行
/opsx:explore，指定要盤點的單一領域，要求 Agent 只讀取程式、測試與文件，不修改程式。 - 要求 Agent 把結果分成「已有證據」「互相矛盾」「仍待確認」三類，先不要產生正式 Spec。
- 由熟悉該領域的人確認哪些行為才是現況契約，而不是程式錯誤或過時文件。
- 要求 Agent 直接建立主規格
openspec/specs/<domain>/spec.md，使用Purpose、Requirements與Scenarios結構，不建立虛構的功能 change，也不執行 apply。 - 執行
openspec validate <domain> --type spec --strict驗證格式，再把 Spec 與相關測試一起交由團隊審查並提交 Git。
例如要替既有登入系統建立 baseline，可以在 AI 聊天欄輸入：
請探索現有登入與權限行為，只讀取相關程式、測試、API 文件與設定，不修改任何檔案。
先列出：
1. 有程式或測試證實的可觀察行為
2. 程式與文件互相矛盾之處
3. 無法證實、需要人工確認之處
等我確認後，再建立 openspec/specs/auth/spec.md 作為現況 baseline。
每個 Requirement 都要描述可驗證的行為，使用 SHALL 或 MUST，並至少提供一個 Scenario。
不要建立 change、proposal、design 或 tasks，也不要修改程式。確認盤點結果後，再要求 Agent 寫成下面這類主規格。主規格使用 ## Requirements，不要出現只屬於 Delta Spec 的 ADDED、MODIFIED 或 REMOVED 標題。
# Authentication Specification
## Purpose
定義目前登入、工作階段與存取控制的可觀察行為。
## Requirements
### Requirement: 登入失敗回應
系統 SHALL 在帳號或密碼錯誤時回傳相同的公開錯誤訊息。
#### Scenario: 密碼錯誤
- **GIVEN** 使用者帳號已存在
- **WHEN** 使用者提交錯誤密碼
- **THEN** 系統拒絕登入
- **AND** 回應不得透露帳號是否存在openspec validate auth --type spec --strict
openspec show auth --type spec
git add openspec/specs/auth/spec.md
git commit -m "docs: establish authentication baseline spec"這種做法是在記錄「系統現在已經怎麼運作」，因此不需要執行 /opsx:apply 或 /opsx:archive。未來要改變登入行為時，再使用正常的 propose 流程建立 Delta Spec；完成歸檔後，OpenSpec 會把變更合併回這份 baseline。
OpenSpec 適合小型專案嗎？
適合，但應控制粒度。跨檔案功能、資料格式或 API 行為值得建立 change；拼字、格式與一眼能確認的修正不必硬套完整流程。OpenSpec 的價值是降低需求漂移，不是增加文件數量。
OpenSpec 和 GitHub Spec Kit 有什麼差別？
兩者都把規格放進 AI 開發流程。OpenSpec 特別強調既有系統持續修改、每個 change 的 Delta Spec，以及完成後合併回主規格；Spec Kit 更常用於從規格建立新功能或新專案。選擇時應看團隊工作方式，不需要在同一項變更同時套兩套 artifact。