OpenSpec 是什麼:安裝、核心概念與工作流程

OpenSpec 是一個輕量的規格驅動開發(Spec-Driven Development)框架:在你和 AI 程式設計助手之間加一層「約定」,先把要做什麼寫下來,看過計畫再寫程式碼,而不是讓需求只存在於聊天記錄裡。它是 MIT 授權的開源專案,支援 30 多個 AI 程式設計工具,HagiCode 自己的工作流程也基於它。本文提供安裝和第一次完整流程的最短路徑,完整指南在獨立網站維護。

核心概念

OpenSpec 由五個概念構成:

規格(specs)是事實來源。 描述系統現在怎麼運作,放在 openspec/specs/,依領域組織,由需求和情境組成。
變更(change)是一個工作單元。 要新增、修改或刪除行為時,在 openspec/changes/ 下建立一個資料夾,把這件事的提案、設計、任務清單和規格修改放在一起。
差異規格(delta specs)只描述變化。 變更裡不重寫整份規格,而是寫 ADDED、MODIFIED、REMOVED,這讓它特別適合修改既有系統。
產出物依序互相銜接。 proposal(為什麼)→ specs(做什麼)→ design(怎麼做)→ tasks(步驟)→ 實作。它們是輔助,不是關卡,隨時可以回頭修改。
封存把變更併回事實。 工作完成後封存,差異規格合併進主規格,變更資料夾移到 changes/archive/ 並加上日期。

安裝

前置條件是 Node.js 20.19.0 或更高版本(HagiCode 的其他元件建議使用 24 或更高版本,請見安裝 Node.js)。

npm install -g @fission-ai/openspec@latest
openspec --version

macOS 和 Linux 也可以使用 Homebrew:brew install openspec。pnpm、yarn(1.x)和 bun 同樣可以全域安裝,但 OpenSpec 仍然執行在 Node.js 上。

接著進入你的專案目錄進行初始化:

cd your-project
openspec init

初始化會詢問你使用哪些 AI 工具,並為它們產生技能或指令檔案。想略過互動,可以使用 openspec init --tools claude,cursor;工具 ID 清單請見支援的工具。

第一次完整流程

斜線指令要輸入在 AI 助手的聊天視窗裡,不是終端機:

/opsx:explore            # 還沒想清楚?先讓 AI 讀程式碼、權衡方案
/opsx:propose add-dark-mode   # 產生變更資料夾:proposal、specs、design、tasks
/opsx:apply              # 依任務清單實作
/opsx:archive            # 封存,差異規格併入主規格

/opsx:propose 會產生 openspec/changes/add-dark-mode/,裡面有 proposal.md、specs/、design.md 和 tasks.md。規格是一般的 Markdown,沒有特殊語法:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

規格由 AI 來寫,你在寫程式碼之前審閱計畫。預設設定包含 propose、explore、apply、update、sync、archive;需要 new、continue、ff、verify、bulk-archive 等展開流程時,用 openspec config profile 選擇,再執行 openspec update 套用。

指令名稱在不同助手裡略有不同

/opsx:propose 是標準寫法。Cursor 和 GitHub Copilot 裡是 /opsx-propose,Amazon Q 裡是 @opsx-propose,Codex 裡是 $openspec-propose。openspec init 會印出你所選工具對應的寫法。

升級

npm install -g @fission-ai/openspec@latest   # 升級軟體套件
openspec update                              # 在每個專案裡重新整理 AI 指令檔案

透過 Homebrew 安裝的請用 brew upgrade openspec。

常見問題

openspec: command not found:全域 npm 目錄不在 PATH 裡。執行 npm prefix -g,macOS 和 Linux 把該目錄下的 bin/ 加入 PATH,Windows 則直接把該目錄加入 PATH。
提示需要 Node.js 20.19.0 或更高版本:用 node --version 檢查並升級。
聊天視窗裡找不到 /opsx:propose:確認指令輸入在助手裡而不是終端機,執行 openspec update 重新產生檔案,再重新啟動助手;Codex 等只支援技能的工具要使用 $openspec-propose 這類寫法。
初始化沒有設定你的工具:重新執行 openspec init,或用 --tools 指定。