核心概念
本指南說明 OpenSpec 背後的核心理念及其相互關係。實際應用請參閱快速入門與工作流程。
設計哲學
OpenSpec 建基於四大原則：
流暢而非僵化 — 無階段閘門，按實際需求推進
迭代而非瀑布 — 邊建構邊學習，持續優化調整
簡易而非複雜 — 輕量化設定，最低限度程序
棕地優先 — 適用於現有程式碼庫，不限於全新專案原則的重要性
流暢而非僵化。 傳統規格將您鎖定於固定流程：先規劃、再實作、最後完成。OpenSpec 則更具彈性——您可以依工作需求自由選擇建立產物的順序。
迭代而非瀑布。 需求會改變，理解會深化。初期看似可行的方案，在檢視程式碼庫後可能不再適用。OpenSpec 擁抱這項現實。
簡易而非複雜。 部分規格框架需要大量設定、僵化格式或繁重流程。OpenSpec 不會阻礙您的工作。數秒內完成初始化，立即開始作業，僅在必要時自訂設定。
棕地優先。 多數軟體開發並非從零開始——而是修改現有系統。OpenSpec 採用的差異化方法，能輕鬆定義對既有行為的變更，而非僅描述新系統。
整體架構
OpenSpec 將您的工作組織成兩個主要部分：
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ 事實來源 │◄─────│ 提出的修改 │ │
│ │ 您的系統目前如何運作 │ 合併 │ 每個變更 = 一個資料夾 │ │
│ │ │ │ 包含產出差異與增量 │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘規格是事實來源 — 它們描述您的系統目前如何運作。
變更是提出的修改 — 它們存放在獨立的資料夾中，直到您準備好合併它們。
這種分離是關鍵。您可以並行處理多個變更而不會產生衝突。您可以在變更影響主要規格之前進行審查。當您歸檔一個變更時，其增量可以順利合併到事實來源中。
協調工作區
工作區支援目前處於測試階段。以下所述的本機視圖模式是當前的發展方向，但外部自動化、整合和長期運作的工作流程仍應將命令行為、狀態檔案和 JSON 輸出視為不斷演進的。
以下命令提供了開啟本機視圖（連結至關聯的儲存庫或資料夾）的初始設定流程。
當單一儲存庫負責規劃、實作和歸檔流程時，儲存庫本機的 OpenSpec 專案是正確的預設設定。有些工作跨越多個儲存庫或資料夾。對於這種情況，OpenSpec 協調工作區是一個機器本機的視圖，它將關聯路徑、開啟器狀態和代理設定整合在一起。
工作區的心智模型如下：
text
工作區 = 背景儲存、行動方案、儲存庫和資料夾的私有本機視圖
背景儲存 = 持久的共享背景容器
行動方案 = 背景儲存內的持久協調背景
連結 = 工作區可以在本機解析的儲存庫或資料夾的穩定名稱
變更 = 一個計劃中的工作單元；實作應在擁有該工作的儲存庫中進行工作區的結構與儲存庫本機專案不同：
text
getGlobalDataDir()/workspaces/<workspace-name>/
├── workspace.yaml # 私有本機視圖記錄
├── AGENTS.md # 生成的運行時指引
└── <workspace-name>.code-workspace # 生成的編輯器工作區檔案儲存庫本機的 OpenSpec 狀態保持現有結構：
text
repo-root/
└── openspec/
├── specs/
└── changes/這個區別很重要。工作區資料夾是用於開啟和檢查關聯儲存庫或資料夾的本機協調介面。每個儲存庫的 openspec/ 目錄仍然是儲存庫擁有的規格、儲存庫本機變更和實作規劃的所在地。使用者不需要在工作區資料夾內執行儲存庫本機的 openspec init。
穩定的連結名稱是工作區引用儲存庫和資料夾的方式。私有工作區記錄保留如 api、web 或 checkout 之類的名稱，並將它們映射到此運行時的本機路徑。
yaml
# workspace.yaml
version: 1
name: platform
context: null
links:
api: /repos/api
web: /repos/web當工作區開啟一個行動方案時，context 記錄選定的背景儲存綁定和行動方案 ID。透過登錄選擇的儲存可透過 ID 保持可攜性；透過路徑選擇的儲存則故意保留運行時本機路徑，因為 workspace.yaml 是私有的本機狀態。
yaml
context:
kind: initiative
store:
id: platform
selector:
kind: registry
id: platform
initiative:
id: billing-launch關聯的路徑可以是完整的儲存庫、大型單一儲存庫內的資料夾或其他現有資料夾。它們在參與工作區規劃之前，不需要具備儲存庫本機的 openspec/ 狀態。後續的實作、驗證或歸檔工作流程可能需要更多的儲存庫就緒條件，但規劃的可見性始於連結。
text
多儲存庫：
api -> /repos/api
web -> /repos/web
大型單一儲存庫：
billing -> /repos/platform/services/billing
checkout -> /repos/platform/apps/checkout受管理的工作區位於標準的 OpenSpec 資料目錄下：
text
getGlobalDataDir()/workspaces這意味著當設定 XDG_DATA_HOME 時為 $XDG_DATA_HOME/openspec/workspaces，在 Unix 風格的回退路徑為 ~/.local/share/openspec/workspaces，在原生 Windows 回退路徑為 %LOCALAPPDATA%\openspec\workspaces。原生 Windows Shell、PowerShell 和 WSL2 各自為運行 OpenSpec 的運行時保留路徑字串。此基礎不會在 D:\repo、/mnt/d/repo 和 UNC WSL 路徑之間進行轉換。
OpenSpec 仍然可以讀取較舊的測試版工作區根目錄作為相容性輸入，但受管理的工作區現在使用上述的根 workspace.yaml 記錄。工作區資料夾對其自身的私有本機視圖仍具權威性。
工作區的可見性不等於變更承諾。當 OpenSpec 需要知道哪些儲存庫或資料夾是相關時，就設定工作區；當您準備好規劃一項功能、修復、專案或其他工作單元時，再建立變更。
常用命令：
bash
# 引導式設定
openspec workspace setup
# 適合自動化的設定
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex-cli
# 從本機登錄查看已知工作區
openspec workspace list
openspec workspace ls
# 為選定的工作區新增或修復連結
openspec workspace link /repos/api
openspec workspace link api-service /repos/api
openspec workspace relink api-service /new/path/to/api
# 檢查此機器可以解析什麼
openspec workspace doctor
openspec workspace doctor --workspace platform
# 重新整理工作區本機的指引和代理技能
openspec workspace update
openspec workspace update --workspace platform --tools codex,claude
# 開啟關聯的工作集合
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor
# 作為本機工作區視圖開啟一個行動方案
openspec workspace open --initiative billing-launch --store platform
openspec workspace open --initiative billing-launch --store-path /repos/platform-contextworkspace setup 總是在標準工作區位置建立工作區，將其記錄在本機登錄中，顯示工作區位置，並要求至少連結一個儲存庫或資料夾。互動式設定會詢問偏好的開啟器，並可為選定的代理安裝 OpenSpec 技能。非互動式設定僅在提供 --opener codex-cli、--opener claude、--opener github-copilot 或 --opener editor 時才會儲存該設定。
工作區技能僅安裝在工作區根目錄中。作用中的全域設定檔選擇要生成哪些工作流程技能；--tools 選擇哪些代理接收這些技能。工作區的設定和更新不會建立斜線命令檔案，即使全域交付包含命令也是如此。執行 openspec workspace update 以重新整理工作區本機的指引，並在不編輯關聯儲存庫或資料夾的情況下，新增、重新整理或移除受管理的工作區本機技能目錄。
OpenSpec 也會維護根工作區的開啟檔案：AGENTS.md 中 OpenSpec 管理的指引區塊，以及用於 VS Code 和 GitHub Copilot-in-VS-Code 開啟的機器本機 <workspace-name>.code-workspace 檔案。受管理的工作區不是儲存庫，因此 OpenSpec 不會建立預設的工作區 .gitignore 或預設的工作區層級 changes/ 目錄。
維護的 VS Code 工作區會先列出有效的關聯儲存庫或資料夾，然後是附加時的行動方案背景，最後是 OpenSpec 工作區檔案。VS Code 將這些項目顯示為一個多根工作區。
workspace open 使用儲存的偏好開啟器開啟關聯的工作集合，除非為該次會話傳遞了 --agent <tool> 或 --editor。同時傳遞兩種開啟器覆蓋將導致錯誤。根工作區開啟使關聯的儲存庫和資料夾可見以供探索和提供背景；實作工作在使用者明確要求後才開始。
workspace link 和 workspace relink 僅記錄現有資料夾；它們不會建立、複製、移動、初始化或編輯關聯的儲存庫或資料夾。在成功連結或重新連結後，OpenSpec 會重新整理受管理的指引和 VS Code 工作區檔案。
需要一個工作區的工作區命令可以使用 --workspace <name> 從任何位置執行。如果您在工作區資料夾或子目錄內執行它們，OpenSpec 將使用當前的工作區。如果有多個已知工作區可用且您未傳遞 --workspace <name>，人工命令會顯示一個選擇器；--json 和 --no-interactive 會因結構化狀態錯誤而失敗，而不是提示。
直接的工作區命令支援用於腳本的 JSON 輸出。JSON 回應將主要資料保存在 workspace、workspaces 或 link 物件中，並將警告或錯誤報告在 status 陣列中。正常物件使用 status: []。
規格
規格使用結構化的需求與情境來描述您系統的行為。
結構
openspec/specs/
├── auth/
│ └── spec.md # 認證行為
├── payments/
│ └── spec.md # 付款處理
├── notifications/
│ └── spec.md # 通知系統
└── ui/
└── spec.md # 使用者介面行為與主題依據領域來組織規格 — 那些對您的系統而言具有意義的邏輯分群。常見的模式有：
- 依據功能區域：
auth/、payments/、search/ - 依據元件：
api/、frontend/、workers/ - 依據限界上下文：
ordering/、fulfillment/、inventory/
規格格式
一份規格包含需求，而每個需求都有情境：
markdown
# 認證規格
## 目的
應用程式的認證與工作階段管理。需求
需求：使用者驗證
系統 SHALL 在成功登入後簽發一個 JWT 令牌。
情境：有效憑證
- GIVEN 一個擁有有效憑證的使用者
- WHEN 該使用者提交登入表單
- THEN 一個 JWT 令牌被回傳
- AND 使用者被重新導向至儀表板
情境：無效憑證
- GIVEN 無效的憑證
- WHEN 使用者提交登入表單
- THEN 一條錯誤訊息被顯示
- AND 沒有令牌被簽發
需求：工作階段過期
系統 MUST 在 30 分鐘不活動後使工作階段過期。
情境：閒置逾時
- GIVEN 一個已驗證的工作階段
- WHEN 30 分鐘過去且沒有活動
- THEN 工作階段被標記為無效
- AND 使用者必須重新進行驗證
**關鍵元素：**
| 元素 | 目的 |
|---------|---------|
| `## Purpose` | 本規格所屬領域的高階描述 |
| `### Requirement:` | 系統必須具備的特定行為 |
| `#### Scenario:` | 需求實際應用的具體範例 |
| SHALL/MUST/SHOULD | 表示需求強度的 RFC 2119 關鍵詞 |
### 為何要以這種結構撰寫規格
**需求是 "做什麼"** — 它們陳述系統應該做什麼，但不指定實現方式。
**情境是 "何時發生"** — 它們提供可供驗證的具體範例。良好的情境：
- 是可測試的（您可以為其編寫自動化測試）
- 涵蓋正常路徑和邊緣情況
- 使用 Given/When/Then 或類似的結構化格式
**RFC 2119 關鍵詞**（SHALL、MUST、SHOULD、MAY）傳達意圖：
- **MUST/SHALL** — 絕對要求
- **SHOULD** — 建議，但存在例外
- **MAY** — 可選
### 規格是什麼（以及不是什麼）
規格是一份**行為契約**，而非實現計畫。
好的規格內容包含：
- 使用者或下游系統所依賴的可觀察行為
- 輸入、輸出和錯誤條件
- 外部約束（安全性、隱私、可靠性、相容性）
- 可測試或可明確驗證的情境
應避免在規格中包含：
- 內部的類別/函數名稱
- 函式庫或框架的選擇
- 逐步的實現細節
- 詳細的執行計畫（這些應歸屬於 `design.md` 或 `tasks.md`）
快速檢驗：
- 如果實現可以在不改變外部可觀察行為的情況下發生變化，那麼它可能不屬於規格。
### 保持輕量：漸進式嚴謹性
OpenSpec 旨在避免繁文縟節。使用足以使變更可驗證的最輕量級層級。
**輕量級規格（預設）：**
- 簡短、以行為為先的需求
- 清晰的範圍和非目標
- 一些具體驗收檢查
**完整規格（用於更高風險）：**
- 跨團隊或跨倉庫的變更
- API/契約變更、遷移、安全/隱私考量
- 歧義可能導致昂貴重工的變更
大多數變更應維持在輕量級模式。
### 人機協作
在許多團隊中，人類進行探索，而智慧體起草文件。預期的迴圈如下：
1. 人類提供意圖、脈絡和約束條件。
2. 智慧體將此轉換為以行為為先的需求和情境。
3. 智慧體將實現細節保留在 `design.md` 和 `tasks.md` 中，而非 `spec.md`。
4. 驗證在實現前確認結構和清晰度。
這使得規格對人類而言可讀，對智慧體而言則保持一致。
## 變更
變更是對您系統的一項擬議修改，以一個包含理解與實現所需一切的資料夾形式呈現。
### 變更結構openspec/changes/add-dark-mode/ ├── proposal.md # 為何與是什麼 ├── design.md # 如何做（技術方法） ├── tasks.md # 實現檢查清單 ├── .openspec.yaml # 變更中繼資料（可選） └── specs/ # 差異規格 └── ui/ └── spec.md # ui/spec.md 中正在變更的內容
每個變更都是自包含的。它包含：
- **文件** — 捕獲意圖、設計和任務的文件
- **差異規格** — 關於正在新增、修改或移除內容的規格說明
- **中繼資料** — 針對此特定變更的可選配置
### 為何變更是資料夾
將變更打包為資料夾具有幾個優點：
1. **所有內容集中。** 提案、設計、任務和規格都位於一處。無需到處尋找。
2. **平行工作。** 多個變更可以同時存在而不衝突。可以在進行 `fix-auth-bug` 的同時開發 `add-dark-mode`。
3. **清晰的歷史。** 歸檔時，變更會連同其完整脈絡一起移至 `changes/archive/`。您不僅可以回顧改變了什麼，還能理解其原因。
4. **審查友好。** 變更資料夾易於審查 — 打開它，閱讀提案，檢查設計，查看規格差異。
## 文件
文件是變更中指導工作的文件。
### 文件流程proposal ──────► specs ──────► design ──────► tasks ──────► implement │ │ │ │ 為何 是什麼 如何做 要採取的
- 範圍 變更內容 方法 步驟
文件層層遞進。每個文件為下一個文件提供脈絡。
### 文件類型
#### 提案 (`proposal.md`)
提案在高層級捕捉**意圖**、**範圍**和**方法**。
```markdown
# 提案：新增深色模式
## 意圖
使用者要求新增深色模式選項，以減少夜間使用時的眼睛疲勞，並符合系統偏好設定。
## 範圍
涵蓋範圍：
- 設定中的主題切換
- 系統偏好偵測
- 在 localStorage 中保存偏好設定
不涵蓋範圍：
- 自訂色彩主題（未來工作）
- 每頁主題覆寫
## 方法
使用 CSS 自訂屬性進行主題設定，並透過 React 上下文進行狀態管理。首次載入時偵測系統偏好設定，允許手動覆寫。何時更新提案：
- 範圍變更（縮小或擴大）
- 意圖闡明（對問題有更好的理解）
- 方法根本性轉變
規格（specs/ 中的差異規格）
差異規格描述相對於當前規格正在變更的內容。請參閱下方的 差異規格。
設計 (design.md)
設計捕捉技術方法和架構決策。
markdown
# 設計：新增深色模式
## 技術方法
主題狀態透過 React 上下文管理，以避免屬性逐層傳遞。CSS 自訂屬性實現執行時切換，無需切換類別。
## 架構決策
### 決策：使用上下文而非 Redux
使用 React 上下文管理主題狀態，原因：
- 簡單的二元狀態（淺色/深色）
- 沒有複雜的狀態轉換
- 避免引入 Redux 相依性
### 決策：使用 CSS 自訂屬性
使用 CSS 變數而非 CSS-in-JS，原因：
- 相容於現有樣式表
- 沒有執行時開銷
- 瀏覽器原生解決方案
## 資料流
```
ThemeProvider (上下文)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS 變數（套用到 :root）
```
## 檔案變更
- `src/contexts/ThemeContext.tsx` (新增)
- `src/components/ThemeToggle.tsx` (新增)
- `src/styles/globals.css` (修改)何時更新設計：
- 實現時發現方法不可行
- 發現更好的解決方案
- 相依性或約束條件發生變化
任務 (tasks.md)
任務是實現檢查清單 — 帶有核取方塊的具體步驟。
markdown
# 任務
## 1. 主題基礎設施
- [ ] 1.1 建立包含淺色/深色狀態的 ThemeContext
- [ ] 1.2 為顏色新增 CSS 自訂屬性
- [ ] 1.3 實現 localStorage 持久化
- [ ] 1.4 新增系統偏好偵測
## 2. 使用者介面元件
- [ ] 2.1 建立 ThemeToggle 元件
- [ ] 2.2 在設定頁面新增切換按鈕
- [ ] 2.3 更新 Header 以包含快速切換
## 3. 樣式
- [ ] 3.1 定義深色主題色彩配置
- [ ] 3.2 更新元件以使用 CSS 變數
- [ ] 3.3 為無障礙功能測試對比度比率任務最佳實踐：
- 將相關任務分組在標題下
- 使用階層式編號（1.1、1.2 等）
- 保持任務小到可在一個工作階段內完成
- 完成後勾選任務
差異規格
差異規格是使 OpenSpec 適用於既有系統開發的關鍵概念。它們描述正在變更的內容，而非重述整個規格。
格式
markdown
# 驗證功能差異
## 新增需求
### 需求：雙因素驗證
系統 MUST 支援基於 TOTP 的雙因素驗證。
#### 情境：2FA 註冊
- GIVEN 一個未啟用 2FA 的使用者
- WHEN 該使用者在設定中啟用 2FA
- THEN 一個 QR 碼被顯示用於設定驗證應用程式
- AND 使用者必須在啟用前輸入驗證碼進行驗證
#### 情境：2FA 登入
- GIVEN 一個已啟用 2FA 的使用者
- WHEN 該使用者提交有效憑證
- THEN 一個 OTP 質詢被呈現
- AND 登入僅在有效 OTP 後完成
## 修改需求
### 需求：工作階段過期
系統 MUST 在 15 分鐘不活動後使工作階段過期。
（先前：30 分鐘）
#### 情境：閒置逾時
- GIVEN 一個已驗證的工作階段
- WHEN 15 分鐘過去且沒有活動
- THEN 工作階段被標記為無效
## 移除需求
### 需求：記住我
（已棄用，改用 2FA。使用者應在每個工作階段重新驗證。）差異區段
| 區段 | 含義 | 歸檔時的處理方式 |
|---|---|---|
## ADDED Requirements | 新行為 | 附加到主規格 |
## MODIFIED Requirements | 已變更行為 | 替換現有需求 |
## REMOVED Requirements | 已棄用行為 | 從主規格中刪除 |
為何使用差異而非完整規格
清晰性。 差異精確顯示正在變更的內容。閱讀完整規格時，您需要在腦海中與當前版本進行差異比對。
避免衝突。 只要修改不同的需求，兩個變更可以觸及同一個規格檔案而不發生衝突。
審查效率。 審查者看到的是變更部分，而非未變更的脈絡。專注於重要的地方。
適用於既有系統。 大多數工作都是修改現有行為。差異將修改提升為一等公民，而非事後考慮。
結構
結構定義了工作流程的工作項目類型及其相依性。
結構如何運作
yaml
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # 無相依性，可優先建立
- id: specs
generates: specs/**/*.md
requires: [proposal] # 需要先有提案才能建立
- id: design
generates: design.md
requires: [proposal] # 可與規格並行建立
- id: tasks
generates: tasks.md
requires: [specs, design] # 需要先有規格與設計工作項目形成相依關係圖：
提案
(根節點)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
規格 設計
(相依於: (相依於:
提案) 提案)
│ │
└─────────────┬─────────────┘
│
▼
任務
(相依於:
規格, 設計)相依性是促成因素，而非閘道。 它們顯示的是哪些項目可以建立，而不是你必須接下來建立什麼。如果不需要設計，可以跳過它。你可以在設計之前或之後建立規格——兩者都只相依於提案。
內建結構
spec-driven (預設)
用於規格驅動開發的標準工作流程：
提案 → 規格 → 設計 → 任務 → 實作適用於：大多數需要在實作前就規格達成共識的功能開發工作。
自訂結構
為你的團隊工作流程建立自訂結構：
bash
# 從頭建立
openspec schema init research-first
# 或分叉現有的結構
openspec schema fork spec-driven research-first自訂結構範例：
yaml
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # 先進行研究
- id: proposal
generates: proposal.md
requires: [research] # 基於研究的提案
- id: tasks
generates: tasks.md
requires: [proposal] # 跳過規格/設計，直接進入任務建立與使用自訂結構的完整細節，請參閱 自訂。
封存
封存透過將增量規格合併到主規格中並為歷史記錄保留變更來完成一個變更。
封存時會發生什麼
封存前：
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ 合併
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
封存後：
openspec/
├── specs/
│ └── auth/
│ └── spec.md # 現已包含 2FA 需求
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # 為歷史記錄保留
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.md封存流程
- 合併增量。 每個增量規格區段（已新增/已修改/已移除）都會套用到對應的主規格。
- 移至封存。 變更資料夾移動到
changes/archive/並加上日期前綴以便按時間順序排列。 - 保留上下文。 所有工作項目在封存中都保持完整。你隨時可以回溯了解變更的原因。
為什麼封存很重要
乾淨的狀態。 活動中的變更 (changes/) 僅顯示進行中的工作。已完成的工作會移出視線。
稽核軌跡。 封存保留了每個變更的完整上下文——不僅是變更了什麼，還有解釋為何變更的提案、解釋如何變更的設計，以及顯示已完成工作的任務。
規格演進。 隨著變更被封存，規格會有機地成長。每個封存都會合併其增量，隨著時間累積建構出全面的規格。
各部分如何協同運作
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC 流程 │
│ │
│ ┌────────────────┐ │
│ │ 1. 開始 │ /opsx:propose (核心) 或 /opsx:new (擴展) │
│ │ 變更 │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. 建立 │ /opsx:ff 或 /opsx:continue (擴展工作流程) │
│ │ 工作項目 │ 依序建立 提案 → 規格 → 設計 → 任務 │
│ │ │ (依據結構相依性) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. 實作 │ /opsx:apply │
│ │ 任務 │ 逐一完成任務，並核對完成 │
│ │ │◄──── 學習過程中更新工作項目 │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. 驗證 │ /opsx:verify (可選) │
│ │ 工作 │ 檢查實作是否符合規格 │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. 封存 │────►│ 增量規格合併至主規格 │ │
│ │ 變更 │ │ 變更資料夾移至 archive/ │ │
│ └────────────────┘ │ 規格現為更新後的事實來源 │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘良性循環：
- 規格描述當前行為
- 變更提議修改（作為增量）
- 實作使變更成真
- 封存將增量合併至規格
- 規格現在描述新的行為
- 下一次變更建立在更新後的規格之上
術語表
| 術語 | 定義 |
|---|---|
| 工作項目 | 變更中的一份文件（提案、設計、任務或增量規格） |
| 封存 | 完成變更並將其增量合併到主規格的過程 |
| 變更 | 對系統的一項提議修改，以包含工作項目的資料夾形式打包 |
| 增量規格 | 相對於當前規格描述變更（已新增/已修改/已移除）的規格 |
| 領域 | 規格的邏輯分組（例如 auth/、payments/） |
| 需求 | 系統必須具備的特定行為 |
| 情境 | 需求的具體範例，通常採用 Given/When/Then 格式 |
| 結構 | 工作項目類型及其相依性的定義 |
| 規格 | 描述系統行為的規格說明，包含需求與情境 |
| 事實來源 | openspec/specs/ 目錄，包含當前已達成共識的行為 |