OpenSpec 安裝與工作流程小記

OpenSpec 安裝與工作流程小記



環境：

• macOS 26.5
• Node.js v26.0.0
• OpenSpec 1.3.1

最近在研究 AI 與 SDD (Spec Driven Development)，注意到 OpenSpec 這個工具，先把想做什麼寫清楚，再讓 AI 動手。今天來記錄安裝與第一次跑完整流程的過程。

GitHub https://github.com/Fission-AI/OpenSpec

安裝

# 全域安裝
npm install -g @fission-ai/openspec@latest

# 確認版本
openspec --version
# 1.3.1

在專案初始化

進到專案目錄執行 init，它會問你用哪個 AI 工具（選 Claude Code）：

openspec init

安裝完確認一下結構，commands 跟 skills 都裝到 .claude/ 下，不影響版控（因為 .claude/ 在 .gitignore 裡）：

.claude/
├── commands/opsx/
│   ├── apply.md
│   ├── archive.md
│   ├── explore.md
│   └── propose.md
└── skills/
    ├── openspec-apply-change
    ├── openspec-archive-change
    ├── openspec-explore
    └── openspec-propose

openspec/
├── changes/
│   └── archive/
└── specs/

openspec/ 下的三個目錄都是空的，git 不追蹤空目錄，所以 git status 完全乾淨。

工作流程：propose → apply → archive

OpenSpec 的核心是三個 slash command：

• /opsx:propose　規劃
• /opsx:apply　實作
• /opsx:archive　歸檔

以這次新增器材摘要功能為例：

Step 1：/opsx:propose

輸入想做什麼，AI 自動在 openspec/changes/<name>/ 建立四份文件：

openspec/changes/admin-machines/
├── proposal.md    # 做什麼、為什麼做
├── design.md      # 技術決策、風險評估
├── specs/
│   └── machine-summary/
│       └── spec.md  # 需求規格與 scenario
└── tasks.md       # 逐一打勾的實作清單

可以在這裡修改內容，確認設計沒問題再繼續。

Step 2：/opsx:apply

AI 讀入四份文件，按 tasks.md 的清單逐一實作，每完成一項就打勾。這次四個 task 全跑完，最後一項是依照 qa-spec.md 補寫 QA 腳本並執行通過。

• 這邊會列出相關的工項給使用者確認，如果有跟需求不符合的部分可以請 AI 加上工項
• 預設執行工項不會進行 QA，建議可以將 QA 加入工項，或是引入自己的參照

Step 3：/opsx:archive

實作完畢後歸檔，把 change 資料夾移到 archive/，同時把 specs/ 下的規格同步至主規格庫 openspec/specs/：

openspec/
├── changes/
│   └── archive/
│       └── 2026-05-30-admin-machines/  # 歸檔的 change
└── specs/
    └── machine-summary/
        └── spec.md  # 長期維護的規格

沒有進行中的功能時，changes/ 下只剩 archive/。清爽。

操作了一下沒有太多違和感，如果平常就有使用規範的話，我覺得使用 OpenSpec 最大的好處應該是會保留清楚的 spec 與功能歷史紀錄。

又前進一步 ~ enjoy it

Reference

• https://github.com/Fission-AI/OpenSpec