OpenSpec：讓 AI 寫程式更可靠的規格驅動開發工具

前言

在 AI 輔助程式開發的時代，你是否遇過這些問題：

  • 告訴 AI「加個搜尋功能」，結果做出來的跟你想的完全不一樣？
  • AI 寫到一半「忘了」之前的需求，開始自己發明功能？
  • 每次都要重新解釋需求，因為 AI 不記得上次說過什麼？
  • 團隊裡每個人用的 AI 工具不同（Claude Code、Cursor、Windsurf…），需求描述各說各話？

如果你有以上困擾，OpenSpec 可能就是你在尋找的解決方案。

什麼是 OpenSpec？

OpenSpec 是由 Fission AI 團隊開發的開源 Specification-Driven Development（SDD，規格驅動開發） 工具。它的核心理念是：先寫規格，再寫程式碼。

簡單來說，OpenSpec 讓你：

  1. 把需求變成結構化的規格文件
  2. 讓 AI 根據規格來實作，而不是憑空猜測
  3. 追蹤所有變更，保持專案的一致性

為什麼需要 OpenSpec？

傳統的 AI 輔助開發模式：

1
2
3
4
5
使用者：「幫我加個按讚功能」
   ↓
AI：「好的！」（開始憑想像寫程式）
   ↓
結果：做出來的功能跟預期不符

使用 OpenSpec 的開發模式：

1
2
3
4
5
6
7
使用者：建立「按讚功能」的提案
   ↓
OpenSpec：產出 proposal.md → spec.md → design.md → tasks.md
   ↓
AI：根據明確的規格文件實作
   ↓
結果：符合預期的功能

安裝與初始化

安裝

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

初始化專案

1
2
3
# 在專案目錄下執行
cd your-project
openspec init

初始化後會建立以下結構：

1
2
3
4
5
6
7
your-project/
├── openspec/
│   ├── config.yaml       # 專案配置
│   ├── specs/            # 規格文件（已實作功能的真相來源）
│   └── changes/          # 變更提案（進行中的工作）
└── .claude/
    └── skills/           # Claude Code 的 Skills

目錄結構詳解

OpenSpec 使用雙資料夾模型：

1. openspec/specs/ - 規格真相來源

存放所有已實作功能的規格，是專案的「單一真相來源」。

1
2
3
4
5
6
openspec/specs/
├── auth/
│   ├── login.md
│   └── register.md
└── user/
    └── profile.md

2. openspec/changes/ - 變更提案

進行中的功能開發，每個變更都有完整的文件結構：

1
2
3
4
5
6
openspec/changes/
└── add-search-feature/
    ├── proposal.md   # 為什麼要改、改什麼
    ├── specs/        # 規格增量（delta specs）
    ├── design.md     # 技術設計與架構
    └── tasks.md      # 實作任務清單

核心文件說明

檔案 用途 內容
proposal.md WHY & WHAT 變更意圖、範圍、方法
specs/ 增量規格 這次變更新增/修改/移除的規格
design.md HOW 技術實作方案、架構設計
tasks.md TODO 可勾選的實作任務清單

OpenSpec 1.0 的工作流程

核心指令

OpenSpec 1.0 提供了更彈性的指令，不再強制按照固定順序執行：

指令 說明
/opsx:new 建立新的變更提案
/opsx:explore 在寫提案前先跟 AI 討論想法
/opsx:continue 根據相依性，逐步產出下一個文件
/opsx:ff Fast Forward - 一次產出所有文件
/opsx:apply 執行任務，AI 開始寫程式
/opsx:archive 完成後歸檔，更新規格

標準工作流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
┌─────────────────────────────────────────────────────────────┐
│                        OpenSpec 工作流程                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. /opsx:new        建立提案                                │
│         ↓                                                    │
│  2. /opsx:continue   逐步產出文件（或用 /opsx:ff 一次產出）   │
│         ↓                                                    │
│         ├── proposal.md（根節點）                            │
│         ├── specs/（依賴 proposal）                          │
│         ├── design.md（依賴 proposal）                       │
│         └── tasks.md（依賴 specs + design）                  │
│         ↓                                                    │
│  3. /opsx:apply      執行任務                                │
│         ↓                                                    │
│  4. /opsx:archive    歸檔並更新 specs/                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

文件相依性管理

OpenSpec 使用 DAG（有向無環圖） 來管理文件之間的相依性：

1
2
3
4
proposal（根節點）
    ├── specs（依賴 proposal）
    ├── design（依賴 proposal）
    └── tasks（依賴 specs + design）

每個文件有三種狀態：

  • BLOCKED - 還不能建立（依賴的文件還沒完成）
  • READY - 可以建立了
  • DONE - 已完成

實際使用範例

範例：新增搜尋功能

Step 1: 建立提案

1
/opsx:new 新增商品搜尋功能

AI 會建立 openspec/changes/add-product-search/ 目錄，並產出 proposal.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Proposal: 新增商品搜尋功能

## 背景
目前使用者只能透過分類瀏覽商品，缺乏搜尋功能導致查找效率低落。

## 目標
實作商品搜尋功能，讓使用者能透過關鍵字快速找到想要的商品。

## 範圍
- 支援關鍵字搜尋
- 支援篩選條件（價格區間、分類）
- 支援排序（價格、上架日期）

## 非目標
- 本期不實作進階搜尋（布林運算、模糊搜尋）

Step 2: 產出完整文件

使用 /opsx:ff 一次產出所有文件，或用 /opsx:continue 逐步產出。

tasks.md 範例：

1
2
3
4
5
6
7
8
9
# Tasks: 新增商品搜尋功能

## 進度：0/5

- [ ] 建立搜尋 API 端點
- [ ] 實作搜尋服務層邏輯
- [ ] 新增 Elasticsearch 索引
- [ ] 實作前端搜尋介面
- [ ] 撰寫單元測試

Step 3: 執行任務

1
/opsx:apply

AI 會：

  1. 先讀取 tasks.md 計算目前進度
  2. 逐一執行未完成的任務
  3. 完成一個就打一個勾
  4. 即時更新進度
1
2
3
4
5
- [x] 建立搜尋 API 端點
- [x] 實作搜尋服務層邏輯
- [x] 新增 Elasticsearch 索引
- [ ] 實作前端搜尋介面
- [ ] 撰寫單元測試

Step 4: 歸檔

1
/opsx:archive

將變更合併到 openspec/specs/，並移到 openspec/archive/ 保存。

OpenSpec 1.0 的重要改進

1. 工作流不再是一直線

0.x 版是線性的：proposal → apply → archive，進了 apply 就不能回頭。

1.0 版讓你想做什麼就做什麼，系統會追蹤狀態。

2. 任務進度即時更新

以前的 tasks.md 進度更新是 AI 「看心情」決定的。

現在每次執行 /opsx:apply 都會：

  1. 先讀取 tasks.md 計算進度
  2. 做完一個任務就打勾
  3. 即時更新完成比例

3. Slash Commands 變成 Skills

原本每個 AI 工具都有自己的配置格式：

  • Claude Code 用 CLAUDE.md
  • Cursor 用 .cursorrules
  • 維護起來很麻煩

現在統一放在 .claude/skills/ 目錄，支援 20+ 種 AI 工具：

  • Claude Code
  • Cursor
  • Windsurf
  • Copilot
  • Aider
  • …等等

4. 專案配置集中管理

用 openspec/config.yaml 管理專案設定：

1
2
3
4
5
6
7
8
9
10
11
12
# openspec/config.yaml
project:
  name: my-project
  tech_stack:
    - TypeScript
    - React
    - Node.js

conventions:
  - 使用函數式元件
  - 使用 Tailwind CSS
  - 測試覆蓋率需達 80%

當 AI 執行指令時，會自動載入這些設定。

支援的 AI 工具

OpenSpec 支援絕大多數主流的 AI 程式開發工具：

工具 支援方式
Claude Code Skills
Cursor Skills
Windsurf Skills
GitHub Copilot Skills
Aider Skills
Trae Skills
Qoder Skills

這表示同一個專案可以混用不同的 AI 工具，大家都能讀取相同的規格文件！

實際應用場景

場景 1：新功能開發

1
2
3
4
5
6
7
8
9
10
11
# 1. 建立提案
/opsx:new 使用者收藏功能

# 2. 快速產出所有文件
/opsx:ff

# 3. 開始實作
/opsx:apply

# 4. 完成後歸檔
/opsx:archive

場景 2：討論階段

1
2
3
4
5
6
7
8
# 先探索想法，不急著產出文件
/opsx:explore 我想要一個推薦系統...

# 討論差不多後再建立提案
/opsx:new 推薦系統

# 逐步產出，每步確認後再繼續
/opsx:continue

場景 3：團隊協作

1
2
3
4
5
# 團隊成員 A 用 Claude Code
/opsx:apply

# 團隊成員 B 用 Cursor（接手繼續）
/opsx:continue

相關工具：Spectra

如果你覺得純文字操作有點麻煩，可以試試 Spectra —— 一個 OpenSpec 的圖形介面工具。

Spectra 功能特色

  • 規格瀏覽：用圖形介面瀏覽 specs、changes、archive
  • 全文搜尋：使用 SQLite 建立索引，快速搜尋
  • 任務追蹤：視覺化的任務清單，支援拖放排序
  • 即時監視：自動偵測檔案變更
  • 多主題支援：6 種主題 × 2 種配色

下載 Spectra

OpenSpec vs 其他 SDD 工具

工具 開發者 特點
OpenSpec Fission AI 輕量、brownfield-first、跨 AI 工具
Spec-Kit GitHub 官方工具、較嚴謹
Kiro AWS 獨立 AI IDE、自動駕駛模式
BMad Method BMad Code 方法論導向

最佳實踐

1. 從小處著手

不要一次建立太大的提案，把大功能拆成多個小變更。

2. 定期歸檔

完成一個變更就立即 /opsx:archive，保持 changes/ 目錄乾淨。

3. 善用 config.yaml

把專案的技術棧、程式碼規範都寫進去，讓 AI 有明確的依據。

4. 保持規格同步

規格文件是真相來源，程式碼變更時要同步更新規格。

5. 團隊共識

確保團隊成員都了解 OpenSpec 的工作流程和目錄結構。

結語

OpenSpec 解決了 AI 輔助開發中的幾個核心問題：

  1. 需求不明確 → 透過結構化的規格文件解決
  2. AI 亂猜 → 讓 AI 根據規格實作
  3. 無法追蹤 → 所有變更都有記錄
  4. 團隊協作困難 → 統一的規格格式，跨工具支援

如果你正在使用 AI 工具進行開發，不妨試試 OpenSpec，讓你的開發流程更加可控、可靠。

參考資源

AI 開發工具
#OpenSpec #AI #SDD #Claude Code #Cursor
OpenSpec：讓 AI 寫程式更可靠的規格驅動開發工具
https://shengshengyang.github.io/2026/03/03/open-spec/
作者
Dean Yang
發布於
2026年3月3日
許可協議