OpenSpec 是 Fission AI 開發、給 AI Coding Agent 使用的開源規格驅動開發工具。它把原本散落在聊天紀錄裡的需求，整理成可以審查、修改與提交到 Git 的 Markdown 文件，讓人類和 AI 在寫程式之前先確認「為什麼改、要改什麼、怎麼做」。
網路上不少 OpenSpec 教學仍停留在 1.0 以前，使用 /openspec:proposal、/openspec:apply 這套舊流程。OpenSpec 1.0 已經改用 OPSX 工作流程，後續版本持續擴充 AI 工具整合與規格驗證。截至 2026 年 10 月 15 日， 官方最新穩定版為 1.14.1 ，本文依這個版本更新規格文件、指令與驗證流程。
- 發表：2026/08/13 openspec v1.9
- 更新：2026/10/01 openspec v1.13
- 更新：2026/10/15 openspec v1.14
OpenSpec 是什麼，為什麼要用
OpenSpec 最基本的用法，是由使用者描述需求，AI Coding Agent 整理成提案，再由使用者檢查規格與工作清單。確認內容沒有偏離需求後，交給 AI 實作；成果通過檢查後，再由 AI 將這次變更與規格歸檔。
AI 寫程式常見的問題不是不會寫，而是需求只存在對話上下文。討論時間一長、壓縮對話上下文、換一個 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 的設定檔 .openspec.yaml 使用 skip_specs: true，保留工作清單但略過 Delta Spec。
OpenSpec 的版本差異
OpenSpec 1.0 不是單純換版號，而是把原本線性的 proposal → apply → archive 流程重做成 OPSX action。後續 1.x 的方向大致分成三條：讓規劃流程更彈性、支援更多 AI 工具，以及提高同步與驗證的安全性。
| 版本 | 發布時間（UTC） | 主要變化 |
|---|---|---|
| 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 | 新增 validate --archived 與 Command Code 整合。 |
| 1.10 | 2026-08-19 | 支援 Zed，新增 init --language，移除安裝時的 postinstall script。 |
| 1.11 | 2026-08-26 | 新增 show --diff 與 status --all，協助審查規格差異與全部變更進度。 |
| 1.12 | 2026-09-03 | 新增 validate --report findings 與 SourceCraft 整合，規劃前先讀相關程式、測試和文件。 |
| 1.13.0 | 2026-09-09 | apply 提醒缺少 Delta Specs；修正歸檔解析、重複 Delta 區段與程式碼區塊內容保留。 |
| 1.13.1 | 2026-09-17 | 強化 CLI 安全、task 進度與規格驗證；update 先提出修訂內容，確認後才寫入。 |
| 1.13.2 | 2026-09-23 | verify 區分未執行與通過；修正 Windows 歸檔，並要求 task 群組包含各自所需的測試與文件。 |
| 1.14.0 | 2026-09-30 | 新增 Amp、Warp、Grok Build 等 10 種工具整合、list --archived／list --all 與 version --check；改善 workflow 狀態總覽、task 勾選與規格同步失敗時的歸檔處理。 |
| 1.14.1 | 2026-10-06 | 加快 CLI 啟動；規格逐份寫入，continue 補齊缺少的 specs；超過 500 字元的 requirement 會產生 warning，導致 strict 驗證失敗。view 不再列出或計算 archived changes，並修正自訂 schema 的 verify。 |
1.8 把 Codex Skills 搬到共用的 .agents/skills/，同時新增 vendor-neutral 的 agents target。普通模式也不再強制需求內文一定要出現英文 SHALL／MUST，中文規格可以通過驗證，但 --strict 仍會執行這項規則。
從 1.9 升級時，日常較有感的是 1.11 的規格差異檢視、1.12 的精簡驗證報告、1.13 系列的歸檔與驗證修正，以及 1.14 系列的歸檔紀錄查詢與狀態總覽。 官方發行紀錄 已補齊各版內容；升級後還要在專案執行 openspec update，Agent 才會取得新版 workflow instructions。
升級到 1.14.0 後，.openspec.yaml 裡未被識別的欄位會收到明確提示，並使 validate --strict 失敗。規格同步遇到阻擋條件時，archive 與 bulk archive 會停止；未安裝 sync skill 時，archive skill 會自行合併 Delta Specs。
1.14.1 另外把超過 500 字元的 requirement 列為 warning，使用 strict 驗證的專案應檢查過長的需求敘述。所有 tasks 勾選完成後，apply 也會要求先審查再歸檔。查詢歷史變更使用 openspec list --archived，目前的 openspec view 則只呈現進行中的變更。
OpenSpec 的基本運作邏輯
OpenSpec 的核心可以分成三個位置：openspec/specs/ 描述系統目前已經成立的行為，openspec/changes/<name>/ 放進行中的變更，openspec/changes/archive/ 保存已完成的變更。新的功能不會直接覆寫主規格，而是先在 change 裡描述差異；實作、驗證和審查完成後，再把差異合併回主規格，並把整個 change 資料夾移入 archive。
change 是資料夾，不是單一文件
openspec/
├── specs/ # 系統目前的正式規格
│ └── auth/
│ └── spec.md
├── changes/
│ ├── add-passkey-login/ # 一個 change，也就是一次變更的容器
│ │ ├── .openspec.yaml # schema 與 change metadata，可省略
│ │ ├── proposal.md # 為什麼改、範圍是什麼
│ │ ├── specs/ # 做完後系統行為要如何改變
│ │ │ └── auth/spec.md # 相對於主規格的 Delta Spec
│ │ ├── design.md # 技術設計與取捨
│ │ └── tasks.md # 實作清單
│ └── archive/ # 已完成 change 的完整歷史
│ ├── 2026-07-10-add-password-login/
│ └── 2026-08-20-add-passkey-login/
└── config.yaml # 專案背景、規則與 schema 設定所以 change 不是 proposal.md 的另一個名稱，也不是單一文件。它是一次變更的容器，在預設 spec-driven schema 裡裝著四類 artifact（規劃文件），分工可以記成 why → what → how → do。這些 artifact 可以反覆修改，不是產生後就不能回頭；簡單的 change 可能不需要 design.md，custom schema 或 skip_specs change 的檔案組合也可能不同。
proposal、specs、design 與 tasks 的分工
四種文件分別供人決定是否要做、確認完成後的行為、討論實作方法，以及追蹤施工進度。以「申請送出後可以在 1 小時內撤回」為例，同一個需求在各文件中會寫成不同內容：
| 文件 | 回答的問題 | 撤回申請範例 |
|---|---|---|
proposal.md | 為什麼做、做哪些、不做哪些，供人決定「要不要做這件事」。實作細節留給 design。 | 減少送錯申請後的人工處理；這次提供限時自行撤回，不包含逾時撤回或管理員代撤。 |
specs/ | 系統應表現出什麼行為。逐條寫「系統 SHALL …」並附情境與預期結果，完成後據此驗收。 | 當申請人在送出後 1 小時內撤回自己的申請，系統將該筆申請標成「已撤回」。 |
design.md | 怎麼做，包括資料表結構、設定檔格式、檔案位置，以及選擇某方案而不採其他方案的原因。 | 決定撤回時間存在哪個欄位、期限如何設定、由哪個模組處理，以及為何由伺服器判斷期限。 |
tasks.md | 施工清單。依 specs 與 design 拆成可逐項勾選、可驗證的工作，實作時依序完成。 | 新增資料欄位、實作撤回 API、加入撤回操作介面，並在各工作中完成對應測試。 |
specs 裡的情境要能拿來驗收。例如以下是假設業務已確認「剛好 1 小時仍可撤回」的 Delta Spec 片段；是否允許已處理的申請撤回等其他規則，仍須在規劃時確認。
## ADDED Requirements
### Requirement: 限時撤回申請
系統 SHALL 允許申請人在送出後 1 小時內撤回自己的申請，
並將該筆申請的狀態標成「已撤回」。
#### Scenario: 期限內撤回
- **GIVEN** 申請由目前登入的申請人送出
- **WHEN** 申請人在送出後 30 分鐘要求撤回
- **THEN** 系統將該筆申請標成「已撤回」
#### Scenario: 剛好到達期限
- **WHEN** 申請人在送出後剛好 1 小時要求撤回自己的申請
- **THEN** 系統將該筆申請標成「已撤回」
#### Scenario: 超過期限
- **WHEN** 申請人在送出超過 1 小時後要求撤回
- **THEN** 系統拒絕撤回，並保留原本狀態功能完成並同步規格後，change 中的 Delta Specs 會合併到 openspec/specs/，成為專案的正式規格。proposal、design、tasks 與 Delta Spec 原檔則隨 change 歸檔，保留決策和施工紀錄。這個分工依據 官方 spec-driven schema；其中 tasks 還要求每項工作寫出驗證方式，所需的測試與文件更新應放進各自的工作群組。
archive 保存歷史，主規格保存最新狀態
一般含 Delta Specs 且選擇同步的 archive 流程會做兩件事。第一，change 裡的 Delta Specs 會合併進 openspec/specs/；第二，包含 proposal、specs、design 與 tasks 的完整 change 資料夾會加上日期前綴，移到 openspec/changes/archive/YYYY-MM-DD-<name>/。因此 active changes 只留下尚未完成的工作，archive 則保留每次變更的動機、設計決策與實作清單。
同一項系統行為可能經過多個 change 反覆修改。例如第一個 change 建立密碼登入，後續 change 改成 passkey，再下一個 change 調整 fallback 規則。每次變更都應先由使用者或團隊確認內容，再實作與歸檔。後來核准並歸檔的 MODIFIED Requirements 會取代主規格裡同名 requirement 的舊版本，所以 openspec/specs/ 會維持目前正式狀態；歷次 change 則留在 archive，讓人與 Agent 回頭查看以前怎麼設計、為什麼那樣做，以及後來為什麼修改。
重點：只保留最新狀態的是 openspec/specs/，不是 archive。archive 不會把歷次 change 壓成一份最新版，而是保留每個已完成 change 的完整 artifacts。若兩個進行中的 change 同時修改同一個 requirement，也不能只看建立時間判定後者自動覆蓋前者；歸檔前要依實際採用的設計解決衝突，再確認主規格反映最後實作結果。
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 應該寫使用者在什麼條件下能完成登入。
使用 MODIFIED Requirements 時，要放入該 requirement 修改後的完整內容，包含仍要保留的 scenarios；只寫新增的幾行，歸檔後可能遺失舊情境。1.11 起可用 openspec show <change> --diff 把實際差異抽出來審查。若是全新的 capability，1.13.2 的 schema 也要求 Delta Spec 先寫 ## Purpose，讓歸檔時建立的主規格有正式用途說明。
OpenSpec 安裝與初始化
OpenSpec 1.14.1 需要 Node.js 20.19.0 以上；Node.js 尚未安裝時，須先完成安裝並讓終端機能找到 node 與 npm。還需要先備妥 Claude Code、Codex 或其他支援的 AI 工具，並完成該工具的登入或 API 設定。以下專案路徑為示例，終端機指令以 macOS／Linux shell 為主：
# Node.js 必須是 20.19.0 以上
node --version
# 安裝目前最新穩定版
npm install -g @fission-ai/openspec@latest
# 確認實際執行到的版本
openspec --version官方也提供 pnpm、Yarn Classic（1.x）、Bun 與 Nix 安裝方式；下面的 yarn global add 適用 Yarn Classic，Yarn 2 以上可改用 npm、pnpm 或 Bun。用 Bun 安裝後，執行 OpenSpec 仍需要 Node.js 20.19.0 以上。使用哪一個套件管理器不會改變 OpenSpec 的資料格式；重點是日後升級要繼續用同一個工具，避免 PATH 上同時留下兩套不同版本。
# 擇一使用，不需要全部安裝
pnpm add -g @fission-ai/openspec@latest
# 僅適用 Yarn Classic 1.x
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。--tools 會以非互動方式初始化並自動清理舊版整合檔，可能包含 ~/.codex/prompts/opsx-*.md；既有專案應先檢查自訂 commands／prompts。Claude Code 與 Codex 同時使用時，可以這樣初始化：
openspec init --tools claude,codex --language "繁體中文"
# 只安裝 AGENTS.md 相容工具共用的 Skills
openspec init --tools agents1.10 起可用 --language 在新建的 config.yaml 寫入文件語言指示；已有設定的專案應修改 context，這個旗標不會覆寫既有設定。1.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。
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。propose 會建立規劃文件、apply 進入實作，archive 則會保存已完成的變更，必要時處理 Spec 同步。實際呼叫形式以 openspec init 完成後顯示的提示為準。
初始化後，依 CLI 顯示的提示重新啟動或重新載入 AI 工具，確認對應的 Skill／聊天指令可被找到；例如 Claude Code 的 /opsx:explore 或 Codex 的 $openspec-explore。找不到時，先確認目前工作目錄是初始化的專案，再核對 profile 是否包含該 workflow，必要時執行 openspec update 後重新載入。以下流程使用 Claude Code 的 /opsx: 寫法；Codex 請使用下表的完整 Skill 名稱，其他工具以初始化提示及已安裝的 Skill／command 名稱為準。
Claude Code 的 action 名稱與 Codex 的 Skill 名稱並非全部相同。例如 apply 對應 openspec-apply-change，sync 對應 openspec-sync-specs。以下依 官方 Skill 名稱 列出完整對照；標為 custom 的項目需先在 openspec config profile 選取，再執行 openspec update。
| Claude Code | Codex | Profile |
|---|---|---|
/opsx:propose | $openspec-propose | core |
/opsx:explore | $openspec-explore | core |
/opsx:apply | $openspec-apply-change | core |
/opsx:update | $openspec-update-change | core |
/opsx:sync | $openspec-sync-specs | core |
/opsx:archive | $openspec-archive-change | core |
/opsx:new | $openspec-new-change | custom |
/opsx:continue | $openspec-continue-change | custom |
/opsx:ff | $openspec-ff-change | custom |
/opsx:verify | $openspec-verify-change | custom |
/opsx:bulk-archive | $openspec-bulk-archive-change | custom |
/opsx:onboard | $openspec-onboard | custom |
OPSX 完整工作流程
以下以加入 Passkey 登入為例，從探索、產生規劃文件到實作、驗證與歸檔，沿用同一個 change。
探索與提案
需求還很模糊時，先在 AI 工具的聊天輸入 /opsx:explore。這個模式可以讀 codebase、比較方案，但不進入程式實作。若由 Agent 提議把結果寫成 change，會先列出預計建立或修改的檔案並等待確認；使用者明確要求記錄成 change 時，授權涵蓋所指定的規劃文件，實作仍由 apply 接手。方向已經確定時可以直接用 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。1.13.1 起，update 會先提出修訂內容，經確認後才寫入。
/opsx:update add-passkey-login
保留密碼登入，不把 Passkey 設為唯一登入方式；
同步修改 spec、design 與 tasks。
/opsx:apply add-passkey-loginapply 會依 tasks 實作並勾選進度，但 task 被勾起來不等於功能一定正確。custom workflow 可以用 /opsx:verify 比對實作與規格；1.13.2 的 verify 會分開列出未執行的檢查，不再把它們算成通過；移除的 requirement 則檢查舊行為是否已移除。驗證報告仍需搭配專案對應的測試、lint 或 build，openspec validate 通過只代表規格格式與一致性檢查通過。
同步與歸檔
/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 show <name> --diff | 1.11 起，檢視 change 相對於主規格的實際差異。 |
openspec status --change <name> | 查看規劃 artifact 狀態，不等於實作已完成。 |
openspec status --all | 1.11 起，一次查看全部 active changes 的規劃狀態。 |
openspec validate <name> --strict | 嚴格驗證指定 change。 |
openspec validate --all --no-interactive | 在 CI 驗證所有 active change 與 specs。 |
openspec validate --all --report findings | 1.12 起，只展開問題項目，保留完整總數與 exit code。 |
openspec validate --archived | 1.9 新增，檢查 archive 是否仍有未完成 tasks。 |
openspec config profile | 選擇 core／custom workflows 與 delivery。 |
openspec completion install zsh | 安裝 shell tab completion。 |
舊版 OpenSpec 升級方式
從 0.x 或早期 1.x 升級時，先更新 CLI，再回到每個專案執行 init／update。1.0 以前的 change、archive 與主規格可以保留，互動式初始化會辨識舊檔案並在清理前要求確認。非互動式 init --tools ... 或使用 --force 時會自動清理 OpenSpec 的 legacy 整合檔，升級前應保留自訂內容；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 Command Prompt 使用 where openspec，PowerShell 使用 Get-Command 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。
參考來源
- GitHub: v1.13.2 – Verify and Windows archive fixes (驗證與 Windows 歸檔修正)
- GitHub: OpenSpec/schemas/spec-driven/schema.yaml at v1.13.2 · Fission-AI/OpenSpec (四種規格文件的產生規則)
- GitHub: Fission-AI/OpenSpec (OpenSpec 官方儲存庫)
- GitHub: Releases · Fission-AI/OpenSpec (OpenSpec 發行版本)
- GitHub: OpenSpec/CHANGELOG.md at main · Fission-AI/OpenSpec (OpenSpec 變更紀錄)
- OpenSpec: Getting Started (入門指南)
- OpenSpec: Concepts (核心概念)
- OpenSpec: Existing Projects (既有專案)
- OpenSpec: Writing Good Specs (撰寫規格)
- OpenSpec: OPSX Commands (OPSX 指令)
- OpenSpec: Migrating to OPSX (遷移至 OPSX)
- OpenSpec: Glossary (名詞表)
- OpenSpec: CLI Reference (CLI 參考資料)
- npm: @fission-ai/openspec (OpenSpec npm 套件)