OpenSpec – Spec-Driven Development

Overview

OpenSpec 是一個規格驅動開發 (Spec-Driven Development, SDD) 框架，讓你在寫程式碼之前先寫規格，確保開發方向正確、減少返工。

When to Use

• 規劃新功能時
• 需要記錄功能規格時
• 變更提案管理
• 團隊協作開發
• 使用者提到 “spec”、”規格”、”SDD” 時

Quick Reference

CLI 指令 (dash spec)

OpenSpec 原生指令

SDD Workflow (五步循環)

1. SPEC (規格化)
   └── 定義功能規格 → openspec/specs/feature-name.md

2. PROPOSE (提案)
   └── 建立變更提案 → openspec/changes/change-name.md

3. IMPLEMENT (實作)
   └── 根據規格實作程式碼

4. VERIFY (驗證)
   └── 確認實作符合規格

5. ARCHIVE (歸檔)
   └── 完成後歸檔變更 → dash spec archive . change-name

File Structure

project/
└── openspec/
    ├── specs/           # 功能規格
    │   ├── auth.md
    │   └── dashboard.md
    ├── changes/         # 活動變更提案
    │   └── add-login-feature.md
    └── archive/         # 已歸檔的變更
        └── 2026-01-setup-project.md

Spec File Format

---
title: 使用者認證
status: active
created: 2026-01-17
---

# 使用者認證

## 概述
實作使用者登入/登出功能。

## 功能需求
1. 支援 Email + 密碼登入
2. 支援 Google OAuth
3. 記住登入狀態

## API 規格
- POST /api/auth/login
- POST /api/auth/logout
- GET /api/auth/me

## 相關變更
- [[add-login-feature]]

Change File Format

---
title: 新增登入功能
type: feature
status: in-progress
spec: auth
created: 2026-01-17
---

# 新增登入功能

## 變更內容
實作 Email + 密碼登入功能。

## 影響範圍
- `src/auth/` 目錄
- `src/api/routes/auth.ts`

## 測試計畫
1. 單元測試: 登入邏輯
2. 整合測試: API 端點
3. E2E 測試: 登入流程

## Checklist
- [ ] 實作登入表單
- [ ] 實作 API 端點
- [ ] 撰寫測試
- [ ] 更新文件

Best Practices

1. 先寫規格再寫程式碼

• 規格是開發的藍圖
• 減少返工和誤解
• 便於團隊溝通

2. 保持規格更新

• 實作後更新規格
• 記錄變更歷史
• 定期審視過期規格

3. 善用變更提案

• 每個功能一個變更
• 明確定義範圍
• 完成後及時歸檔

4. 使用 dash-devtools 整合

• dash validate . 自動驗證規格
• dash health . 顯示規格健康度
• dash spec status . 快速總覽

Integration with dash-devtools

驗證整合

# 自動偵測 openspec/ 並驗證
dash validate .

# 檢查項目:
# - 目錄結構完整性
# - 規格檔案格式
# - 過期變更提醒

健康評分

# 顯示規格健康度
dash health .

# 評分項目:
# - 規格覆蓋率
# - 變更處理率
# - 格式正確性

Installation

# 安裝 OpenSpec CLI
npm install -g @fission-ai/openspec@latest

# 驗證安裝
openspec --version

# 在專案中初始化
cd your-project
dash spec init .

Troubleshooting

openspec 未安裝

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

規格格式錯誤

確保每個 .md 檔案都有 YAML frontmatter:

---
title: 規格標題
status: active
---

# 內容...

過期變更警告

使用 dash spec archive . <name> 歸檔已完成的變更。

Related Resources

• OpenSpec GitHub
• Spec-Driven Development
• dash-devtools