Back to Details

openspec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenSpec - Spec-Driven Development

OpenSpec - Spec-Driven Development

Overview

Overview

OpenSpec 是一個規格驅動開發 (Spec-Driven Development, SDD) 框架，讓你在寫程式碼之前先寫規格，確保開發方向正確、減少返工。
OpenSpec is a Spec-Driven Development (SDD) framework that allows you to write specifications before writing code, ensuring the correct development direction and reducing rework.

When to Use

When to Use

  • 規劃新功能時
  • 需要記錄功能規格時
  • 變更提案管理
  • 團隊協作開發
  • 使用者提到 "spec"、"規格"、"SDD" 時
  • When planning new features
  • When you need to document feature specifications
  • For change proposal management
  • For team collaborative development
  • When the user mentions "spec", "specification", or "SDD"

Quick Reference

Quick Reference

CLI 指令 (dash spec)

CLI Commands (dash spec)

指令功能
dash spec init .
初始化 OpenSpec
dash spec list .
列出活動變更
dash spec view .
互動式儀表板
dash spec show . <name>
顯示變更詳情
dash spec validate . <name>
驗證規格格式
dash spec archive . <name>
歸檔完成的變更
dash spec status .
快速狀態總覽
CommandFunction
dash spec init .
Initialize OpenSpec
dash spec list .
List active changes
dash spec view .
Interactive dashboard
dash spec show . <name>
Show change details
dash spec validate . <name>
Validate specification format
dash spec archive . <name>
Archive completed changes
dash spec status .
Quick status overview

OpenSpec 原生指令

OpenSpec Native Commands

指令功能
openspec init
初始化
openspec list
列出變更
openspec view
互動式儀表板
openspec show <name>
顯示詳情
openspec validate <name>
驗證格式
openspec archive <name>
歸檔變更
CommandFunction
openspec init
Initialize
openspec list
List changes
openspec view
Interactive dashboard
openspec show <name>
Show details
openspec validate <name>
Validate format
openspec archive <name>
Archive changes

SDD Workflow (五步循環)

SDD Workflow (5-Step Cycle)

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
1. SPEC (Specification)
   └── Define feature specifications → openspec/specs/feature-name.md

2. PROPOSE (Proposal)
   └── Create change proposal → openspec/changes/change-name.md

3. IMPLEMENT (Implementation)
   └── Implement code according to specifications

4. VERIFY (Verification)
   └── Confirm implementation meets specifications

5. ARCHIVE (Archiving)
   └── Archive changes after completion → dash spec archive . change-name

File Structure

File Structure

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

Spec File Format

Spec File Format

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

使用者認證

User Authentication

概述

Overview

實作使用者登入/登出功能。
Implement user login/logout functionality.

功能需求

Functional Requirements

  1. 支援 Email + 密碼登入
  2. 支援 Google OAuth
  3. 記住登入狀態
  1. Support Email + Password login
  2. Support Google OAuth
  3. Remember login status

API 規格

API Specifications

  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/me
  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/me

相關變更

Related Changes

  • [[add-login-feature]]
undefined
  • [[add-login-feature]]
undefined

Change File Format

Change File Format

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

新增登入功能

Add Login Feature

變更內容

Change Content

實作 Email + 密碼登入功能。
Implement Email + Password login functionality.

影響範圍

Scope of Impact

  • src/auth/
    目錄
  • src/api/routes/auth.ts
  • src/auth/
    directory
  • src/api/routes/auth.ts

測試計畫

Test Plan

  1. 單元測試: 登入邏輯
  2. 整合測試: API 端點
  3. E2E 測試: 登入流程
  1. Unit Tests: Login logic
  2. Integration Tests: API endpoints
  3. E2E Tests: Login flow

Checklist

Checklist

  • 實作登入表單
  • 實作 API 端點
  • 撰寫測試
  • 更新文件
undefined
  • Implement login form
  • Implement API endpoints
  • Write tests
  • Update documentation
undefined

Best Practices

Best Practices

1. 先寫規格再寫程式碼

1. Write Specifications Before Writing Code

  • 規格是開發的藍圖
  • 減少返工和誤解
  • 便於團隊溝通
  • Specifications are the blueprint for development
  • Reduce rework and misunderstandings
  • Facilitate team communication

2. 保持規格更新

2. Keep Specifications Updated

  • 實作後更新規格
  • 記錄變更歷史
  • 定期審視過期規格
  • Update specifications after implementation
  • Record change history
  • Regularly review outdated specifications

3. 善用變更提案

3. Make Good Use of Change Proposals

  • 每個功能一個變更
  • 明確定義範圍
  • 完成後及時歸檔
  • One change per feature
  • Clearly define the scope
  • Archive promptly after completion

4. 使用 dash-devtools 整合

4. Integrate with dash-devtools

  • dash validate .
    自動驗證規格
  • dash health .
    顯示規格健康度
  • dash spec status .
    快速總覽
  • dash validate .
    Automatically validate specifications
  • dash health .
    Show specification health status
  • dash spec status .
    Quick overview

Integration with dash-devtools

Integration with dash-devtools

驗證整合

Validation Integration

bash
undefined
bash
undefined

自動偵測 openspec/ 並驗證

Automatically detect openspec/ and validate

dash validate .
dash validate .

檢查項目:

Check items:

- 目錄結構完整性

- Directory structure integrity

- 規格檔案格式

- Specification file format

- 過期變更提醒

- Outdated change reminders

undefined
undefined

健康評分

Health Score

bash
undefined
bash
undefined

顯示規格健康度

Show specification health status

dash health .
dash health .

評分項目:

Scoring items:

- 規格覆蓋率

- Specification coverage rate

- 變更處理率

- Change processing rate

- 格式正確性

- Format correctness

undefined
undefined

Installation

Installation

bash
undefined
bash
undefined

安裝 OpenSpec CLI

Install OpenSpec CLI

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

驗證安裝

Verify installation

openspec --version
openspec --version

在專案中初始化

Initialize in project

cd your-project dash spec init .
undefined
cd your-project dash spec init .
undefined

Troubleshooting

Troubleshooting

openspec 未安裝

openspec not installed

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

規格格式錯誤

Incorrect specification format

確保每個 .md 檔案都有 YAML frontmatter:
markdown
---
title: 規格標題
status: active
---
Ensure each .md file has YAML frontmatter:
markdown
---
title: Specification Title
status: active
---

內容...

Content...

undefined
undefined

過期變更警告

Outdated change warning

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

Related Resources

Related Resources