---
# System prepended metadata

title: openspec note

---

## 前置作業
1. 安裝 node 版本 >= 20.19.0，因 OpenSpec CLI 需要。
```
nvm install 20.19.0
```
預期會看到以下內容
```
v20.19.0 is already installed.
```
2. 檢查版本是否切換成 20.19.0
```
node --version
```
如果安裝後版本沒有切換成 20.19.0，執行`nvm use 20.19.0`切換版本
預期會看到以下內容
```
Now using node v20.19.0 (npm v10.8.2)
```
3. 安裝 Codex CLI 或是 Claude Code CLI
```
brew install --cask codex
brew install --cask claude-code
```
安裝好後確認是否成功
```
codex --version
claude --version
```
進入 CLI
```
codex
claude
```

## Codex 版本
先說流程，它會根據你的需求產生 Proposal(提案)，有完整的規格文件 (proposal → specs → design → tasks)，接著可以根據這個 Proposal 去 Apply(應用)，讓 AI 根據每個步驟去撰寫程式碼，最後完成後將剛剛的提案 Archive(歸檔)存成專案文件。
1. 初始化 openspec
```
openspec init
```
在初始化時可選擇多個工具，這邊選擇 Claude Code、Codex，按下 Enter 後會看到專案跟目錄建立了`.claude`、`.codex`兩個資料夾。

![截圖 2026-02-27 10.02.52](https://hackmd.io/_uploads/S1O8oOCuWx.png)

初始化時，會一併建立預設的 .codex/skills/openspec-* 裡面的 SKILL.md，可以調整內容讓 codex 參考你修改的內容執行。

輸入`/skills -> list skills -> openspec-explore`後會開始一系列定義方向。

![截圖 2026-02-27 10.18.30](https://hackmd.io/_uploads/SJG-yFR_bg.png)

這邊再實作過程中發現`/prompts:opsx-explore`指令和`/skills -> list skills -> openspec-explore`是有些微差異的！

`/prompts:opsx-explore`：在 Codex CLI 裡調用自訂提示檔案的方式，這些提示檔放在 ~/.codex/prompts/ 目錄裡，內容是你預先寫好的 Markdown 類型提示，用來快速重用某些常見任務指令，例如放一個`opsx-explore.md`檔案，然後在 Codex 裡輸入`/opsx-explore`就會把該提示發送給模型。
這和傳統意義上的 reusable prompt 很像，但它是客製化提示而非 Skill。

`/skills -> list skills -> openspec-explore`：是比單純提示更結構化、重用性更強的工作流程或技能包，在 Codex 中，Skills 是一種包含名稱、描述、行為指令及可能的腳本/支持資源的技能包。
它可以讓模型根據任務內容自動選擇是否啟用或可以用 $skillName 類似方式手動調用。
openspec-explore 這種 Skill 通常會有完整的 SKILL.md，不是單純一段提示。
Skills 通常有更清楚的觸發條件與流程定義和支援更複雜的工作流程，而不只是直接把一段提示塞進模型上下文。

基本上用`openspec-propose`產生變更內容`proposal/design/tasks/.openspec.yaml` 都會是在規格內。
- .openspec.yaml -> 記錄這個 change 的基本設定與 schema。
- proposal.md -> 說明 why(為何要做) and what(要做什麼)。
- design.md -> 說明該 how(怎麼做)。
- tasks.md -> 執行任務。
- spec.md -> 這次 change 的規格，是 apply 前最重要的行為。

可以用以下方式判斷該在什麼時候修改什麼檔案：
- 需求/測試條件錯：改 spec.md
- 邏輯不對：改 design.md
- 任務拆分：改 tasks.md
- 範圍改變：改 proposal.md

最常修改的應該是`spec.md`、`tasks.md`。

確認規格檔案都生成好後接著執行`/skills -> $openspec-apply-change`指令，就會開始按照先前所產出的規格實作。

最後當所有的 task 完成後就可以操作`$openspec-archive-change`進行歸檔。

流程可以理解為：
openspec-explore -> openspec-propose -> openspec-apply-change -> openspec-archive-change。

`openspec-explore` -> 需求不明確時使用。
`openspec-propose` -> 需求明確時可直接從這步開始。
`openspec-apply-change` -> 可重複執行很多次直到 tasks 全部完成才進 archive。
`openspec-archive-change` -> 將處理完成的任務內容進行歸檔。

- 需求明確：propose -> apply -> archive。
- 需求不明確：explore -> propose -> apply -> archive。

在進行`explore`或`propose`階段時，會在`openspec/changes`層級產生 artifacts，如果發現內容規格不正確可以在這步驟自行調整規格內容，確認沒問題後再進行`apply(應用)`，最後`archive(歸檔)`。

## Claude Code 版本