核心概念
本指南說明 OpenSpec 背後的核心理念及其如何協同運作。如需實際使用方式，請參閱 快速入門 和 工作流程。
設計理念
OpenSpec 建立在四大原則之上：
fluid not rigid — 無階段閘門，從最有價值的處著手
iterative not waterfall — 邊建置邊學習，邊推進邊精煉
easy not complex — 輕量設定，極少繁瑣流程
brownfield-first — 適用於既有程式碼庫，不僅限於全新專案這些原則為何重要
流暢而非僵化。 傳統規格系統將你鎖定在特定階段：先規劃、再實作、最後完成。OpenSpec 更具彈性——你可以按照對工作最有利的順序建立產出物。
迭代而非瀑布式。 需求會變化，理解會加深。一開始看似良好的方案，在接觸程式碼庫後可能不再適用。OpenSpec 擁抱這一現實。
簡易而非複雜。 某些規格框架需要大量設定、僵硬的格式或繁重的流程。OpenSpec 不給你添麻煩。數秒內完成初始化，立即開始工作，僅在需要時進行自訂。
以既有專案為優先。 大多數軟體工作並非從零開始——而是修改既有系統。OpenSpec 的增量式方法讓你可以輕鬆地描述對既有行為的變更，而不僅僅是描述全新系統。
全局概覽
OpenSpec 將您的工作組織為兩個主要領域：
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs（規格）是事實來源——它們描述系統目前的行為方式。
Changes（變更）是擬議的修改——在準備合併之前，它們存放在單獨的資料夾中。
這種分離至關重要。您可以並行處理多項變更而不會產生衝突。您可以在影響主 Specs 之前審查一項變更。當您歸檔一項變更時，其 Delta 會乾淨地合併到事實來源中。
Specs
Specs 使用結構化的需求和場景來描述系統的行為。
結構
openspec/specs/
├── auth/
│ └── spec.md # Authentication behavior
├── payments/
│ └── spec.md # Payment processing
├── notifications/
│ └── spec.md # Notification system
└── ui/
└── spec.md # UI behavior and themes按領域組織 Specs——這是指對您的系統有意義的邏輯分組。常見的模式包括：
- 按功能區域：
auth/、payments/、search/ - 按組件：
api/、frontend/、workers/ - 按有界上下文：
ordering/、fulfillment/、inventory/
Spec 格式
一個 Spec 包含需求，每個需求都有場景：
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticate關鍵元素：
| 元素 | 目的 |
|---|---|
## Purpose | 此 Spec 領域的高層級描述 |
### Requirement: | 系統必須具備的特定行為 |
#### Scenario: | 需求在實際應用中的具體範例 |
| SHALL/MUST/SHOULD | RFC 2119 關鍵字，表示需求的強度 |
為何這樣結構化 Specs
需求是「做什麼」——它們說明系統應該做什麼，而不指定實現細節。
場景是「何時」——它們提供可以驗證的具體範例。良好的場景應具備以下特點：
- 可測試（您可以為其編寫自動化測試）
- 涵蓋正常路徑和邊緣情況
- 使用 Given/When/Then 或類似的結構化格式
RFC 2119 關鍵字（SHALL, MUST, SHOULD, MAY）傳達意圖：
- MUST/SHALL —— 絕對要求
- SHOULD —— 建議，但存在例外情況
- MAY —— 可選
Spec 是什麼（以及不是什麼）
Spec 是一個行為合約，而不是實施計劃。
良好的 Spec 內容包括：
- 用戶或下游系統依賴的可觀察行為
- 輸入、輸出和錯誤條件
- 外部約束（安全性、隱私、可靠性、兼容性）
- 可以測試或明確驗證的場景
Spec 中應避免的內容：
- 內部類別/函數名稱
- 庫或框架選擇
- 逐步的實現細節
- 詳細的執行計劃（這些屬於
design.md或tasks.md）
快速測試：
- 如果實現方式的改變不會影響外部可見的行為，那麼它可能不屬於 Spec 的一部分。
保持輕量：漸進式嚴謹度
OpenSpec 旨在避免官僚主義。使用仍能確保變更可驗證的最輕量級別。
Lite Spec（預設）：
- 簡短的行为優先的需求
- 清晰的範圍和非目標
- 少數幾個具體的驗收檢查點
Full Spec（用於較高風險）：
- 跨團隊或跨倉庫的變更
- API/合約變更、遷移、安全/隱私問題
- 模糊性很可能導致昂貴返工的變更
大多數變更應保持在 Lite 模式。
人類與代理協作
在许多团队中，人类负责探索，代理负责起草工件。预期的循环如下：
- 人类提供意图、背景和约束。
- 代理将其转换为行为优先的需求和场景。
- 代理将实现细节保留在
design.md和tasks.md中，而不是spec.md。 - 验证在实施前确认结构和清晰度。
这使规范对人类易于阅读，对代理保持一致。
(註：以上段落根據原文意譯為繁體中文)
Human + Agent Collaboration
在许多团队中，人类负责探索，代理负责起草工件。预期的循环如下：
- Human provides intent, context, and constraints.
- Agent converts this into behavior-first requirements and scenarios.
- Agent keeps implementation detail in
design.mdandtasks.md, notspec.md. - Validation confirms structure and clarity before implementation.
This keeps specs readable for humans and consistent for agents.
Changes
Change 是對您系統的擬議修改，打包為一個資料夾，包含理解和實施所需的一切。
Change 結構
openspec/changes/add-dark-mode/
├── proposal.md # Why and what
├── design.md # How (technical approach)
├── tasks.md # Implementation checklist
├── .openspec.yaml # Change metadata (optional): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta specs
└── ui/
└── spec.md # What's changing in ui/spec.md每個 Change 都是自包含的。它具有：
- Artifacts（工件） —— 捕捉意圖、設計和任務的文檔
- Delta specs —— 關於新增、修改或刪除內容的規範
- Metadata（元數據） —— 此特定變更的可選配置
為何 Changes 是資料夾
將 Change 打包為資料夾有以下好處：
Everything together. Proposal, design, tasks, and specs live in one place. No hunting through different locations.
Parallel work. Multiple changes can exist simultaneously without conflicting. Work on
add-dark-modewhilefix-auth-bugis also in progress.Clean history. When archived, changes move to
changes/archive/with their full context preserved. You can look back and understand not just what changed, but why.Review-friendly. A change folder is easy to review — open it, read the proposal, check the design, see the spec deltas.
Artifacts
Artifacts 是 Change 內引導工作的文檔。
Artifact 流程
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeArtifacts 相互建構。每個 Artifact 為下一個提供背景資訊。
Artifact 類型
Proposal (proposal.md)
Proposal 在高層級捕捉意圖、範圍和方法。
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.何時更新 Proposal：
- 範圍變更（縮小或擴大）
- 意圖更清晰（對問題有更好的理解）
- 方法發生根本性轉變
Specs (delta specs in specs/)
Delta specs 描述相對於當前 Specs 的變更內容。請參見下方的 Delta Specs。
Design (design.md)
Design 捕捉技術方法和架構決策。
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)何時更新 Design：
- 實現顯示該方法不可行
- 發現更好的解決方案
- 依賴關係或約束發生變化
Tasks (tasks.md)
Tasks 是實施清單——帶有核取方塊的具體步驟。
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibilityTask 最佳實踐：
- 在標題下分組相關任務
- 使用層次編號（1.1, 1.2 等）
- 保持任務足夠小以在一次會話中完成
- 完成任務後將其標記為已完成
Delta Specs
Delta specs 是使 OpenSpec 適用於現存系統開發的關鍵概念。它們描述正在發生的變更，而不是重新陳述整個 Spec。
格式
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)Delta 部分
| 部分 | 含義 | 歸檔時發生的事情 |
|---|---|---|
## ADDED Requirements | 新行為 | 附加到主 Spec |
## MODIFIED Requirements | 已變更的行為 | 替換現有需求 |
## REMOVED Requirements | 已棄用的行為 | 從主 Spec 中刪除；當變更宣告 retire_capabilities: true 時，刪除最後一個需求會退役該功能並刪除其 Spec 文件 |
## Purpose | 全新功能的用途 | 為正在創建的主 Spec 的 Purpose 提供種子；當 Spec 已存在時被忽略 |
為何使用 Deltas 而非完整 Specs
Clarity. A delta shows exactly what's changing. Reading a full spec, you'd have to diff it mentally against the current version.
Conflict avoidance. Two changes can touch the same spec file without conflicting, as long as they modify different requirements.
Review efficiency. Reviewers see the change, not the unchanged context. Focus on what matters.
Brownfield fit. Most work modifies existing behavior. Deltas make modifications first-class, not an afterthought.
Schemas
Schemas 定義了工作流中的產物類型及其依賴關係。
Schemas 的運作方式
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # No dependencies, can create first
- id: specs
generates: specs/**/*.md
requires: [proposal] # Needs proposal before creating
- id: design
generates: design.md
requires: [proposal] # Can create in parallel with specs
- id: tasks
generates: tasks.md
requires: [specs, design] # Needs both specs and design first產物形成一個依賴圖：
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)依賴關係是啟用條件，而非閘門。 它們顯示哪些產物可以被建立，而非你必須接下來建立什麼。如果你不需要 design，可以跳過它。你可以在 design 之前或之後建立 specs——兩者都只依賴 proposal。
內建 Schemas
spec-driven（預設）
規格驅動開發的標準工作流：
proposal → specs → design → tasks → implement適用場景：大多數功能開發工作，希望在實作前先就規格達成共識。
自訂 Schemas
為團隊的工作流建立自訂 schemas：
# Create from scratch
openspec schema init research-first
# Or fork an existing one
openspec schema fork spec-driven research-first自訂 schema 範例：
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Do research first
- id: proposal
generates: proposal.md
requires: [research] # Proposal informed by research
- id: tasks
generates: tasks.md
requires: [proposal] # Skip specs/design, go straight to tasks請參閱 Customization 了解建立和使用自訂 schemas 的完整細節。
Archive
歸檔會透過將其增量規格合併至主規格並保留變更以供歷史查閱，來完成一個變更。
歸檔時會發生什麼
Before archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
After archive:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Now includes 2FA requirements
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Preserved for history
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.md歸檔流程
合併增量。 每個增量規格區段（ADDED/MODIFIED/REMOVED）會被套用到對應的主規格上。
移至歸檔。 變更資料夾會移至
changes/archive/，並加上日期前綴以維持時間順序。保留上下文。 所有產物在歸檔中保持完整。你可以隨時回溯以了解為何做出某個變更。
為何歸檔很重要
乾淨的狀態。 進行中的變更（changes/）只顯示正在進行的工作。已完成的工作會被移出，不再干擾。
稽核軌跡。 歸檔保留了每個變更的完整上下文——不僅僅是變更了什麼，還包括解釋為何變更的 proposal、解釋如何變更的 design，以及顯示已完成工作的 tasks。
規格演進。 隨著變更被歸檔，規格會自然地成長。每次歸檔都會合併其增量，逐步建立起全面的規格文件。
整體如何運作
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ CHANGE │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREATE │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ ARTIFACTS │ Creates proposal → specs → design → tasks │
│ │ │ (based on schema dependencies) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENT │ /opsx:apply │
│ │ TASKS │ Work through tasks, checking them off │
│ │ │◄──── Update artifacts as you learn │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFY │ /opsx:verify (optional) │
│ │ WORK │ Check implementation matches specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Delta specs merge into main specs │ │
│ │ CHANGE │ │ Change folder moves to archive/ │ │
│ └────────────────┘ │ Specs are now the updated source of truth │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘良性循環：
- 規格描述目前行為
- 變更提出修改建議（以增量形式）
- 實作將變更落實
- 歸檔將增量合併至規格
- 規格現在描述新的行為
- 下一個變更建立在更新後的規格之上
名詞解釋
| 術語 | 定義 |
|---|---|
| Artifact | 變更中的文件（proposal、design、tasks 或增量規格） |
| Archive | 完成變更並將其增量合併至主規格的流程 |
| Change | 對系統提出的修改建議，以包含產物的資料夾形式包裝 |
| Delta spec | 描述相對於目前規格的變更（ADDED/MODIFIED/REMOVED）的規格 |
| Domain | 規格的邏輯分組（例如 auth/、payments/） |
| Requirement | 系統必須具備的特定行為 |
| Scenario | 需求的具體範例，通常採用 Given/When/Then 格式 |
| Schema | 產物類型及其依賴關係的定義 |
| Spec | 描述系統行為的規格文件，包含需求和場景 |
| Source of truth | openspec/specs/ 目錄，包含目前已達成共識的行為 |
下一步
- Getting Started - 實際的第一步
- Workflows - 常見模式及何時使用各模式
- Commands - 完整命令參考
- Customization - 建立自訂 schemas 並設定專案