系列文章: Openspec (4/6)
specs、changes、artifacts：搞懂 OpenSpec 的三個核心概念
你可以不懂原理就直接用 OpenSpec 的指令，大概也能跑起來——但等你遇到第一個「欸這個指令到底在幹嘛」的時刻，就得回來補這篇。不如現在先把三個核心概念搞清楚，後面每一步都會更好理解。
Specs：你的系統現在長什麼樣
openspec/specs/ 是真相來源——描述你的系統目前如何運作。
不是你想要的未來，是現在。
按 domain 分資料夾：
openspec/specs/
├── auth/
│ └── spec.md # 登入、驗證、session 怎麼運作
├── payments/
│ └── spec.md # 付款流程
└── ui/
└── spec.md # UI 行為與主題
每個 spec.md 裡面，長這樣：
# Auth Specification
## Purpose
應用程式的認證與 session 管理。
## Requirements
### Requirement: User Authentication
系統 SHALL 在登入成功後發送 JWT token。
#### Scenario: Valid credentials
- GIVEN 使用者輸入正確的帳號密碼
- WHEN 提交登入表單
- THEN 回傳 JWT token
- AND 導向 dashboard
#### Scenario: Invalid credentials
- GIVEN 使用者輸入錯誤的帳號密碼
- WHEN 提交登入表單
- THEN 顯示錯誤訊息
- AND 不發送 token幾個重點：
Requirement 寫「系統應該做什麼」，不寫「怎麼實作」——用的是 RFC 2119 的用詞：
- SHALL / MUST — 絕對要求，沒有例外
- SHOULD — 建議，但有例外情況可以不做
- MAY — 可選
Scenario 寫「具體例子」，用 Given/When/Then 結構，每個 scenario 要能被驗證——你能從這個 scenario 寫出一個自動化測試。
Spec 不寫的東西：類別名稱、用哪個 library、資料庫怎麼設計——那些是 design.md 的事。Spec 只管「用戶或下游系統看到的行為」。
Changes：每個修改都有自己的資料夾
openspec/changes/ 放的是進行中的修改——每一個你想新增或修改的功能，都活在這裡，有自己的資料夾，直到完成後 archive 才會合併。
openspec/changes/
└── add-dark-mode/
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── ui/
└── spec.md ← 這次修改的 delta spec
多個修改可以同時進行，互不干擾——因為每個都在自己的資料夾裡，不會打架。
Artifacts：每個修改裡的四個文件
一個 change 資料夾裡通常有四個 artifact，各司其職：
| Artifact | 回答什麼問題 |
|---|---|
proposal.md |
為什麼要做這件事？範圍是什麼？ |
specs/ |
有哪些行為會新增、修改、或移除？ |
design.md |
技術上怎麼做？架構決策是什麼？ |
tasks.md |
具體要做哪些事？（勾選清單） |
這四個 artifact 有依賴關係，但不強迫你照順序：
proposal → specs → design → tasks → 實作
↑ ↑ ↑ │
└──────────┴────────┴──────────────┘
實作過程中發現問題，隨時可以回頭更新
proposal.md 說「為什麼」——這次改動的動機、影響範圍、大致方向。不用很長，能說清楚就好。
specs/（delta spec）說「有哪些行為在變」——用 ADDED/MODIFIED/REMOVED 三個區段標示：
# Delta for UI
## ADDED Requirements
### Requirement: Theme Selection
系統 SHALL 讓用戶切換 light / dark 主題。
#### Scenario: 手動切換
- GIVEN 用戶在任何頁面
- WHEN 點擊主題切換按鈕
- THEN 主題立即切換
- AND 偏好設定保存，重開頁面後仍然生效
## MODIFIED Requirements
（略）
## REMOVED Requirements
（略）Archive 的時候，ADDED 的會加進主 spec，MODIFIED 的會覆蓋舊版，REMOVED 的會刪掉。
design.md 說「怎麼做」——技術方案、架構決策、選哪個 library、資料流怎麼設計。這裡才是寫實作細節的地方，spec 不用碰。
tasks.md 是勾選清單——AI 跑 /opsx:apply 的時候，就是按照這份清單一條一條做：
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 建立 ThemeContext 管理 light/dark state
- [ ] 1.2 在 CSS 加入 custom properties
- [ ] 1.3 實作 localStorage 偏好保存
## 2. UI Components
- [ ] 2.1 建立 ThemeToggle 元件
- [ ] 2.2 加入設定頁面三者的關係，一句話版
specs 是現況，changes 是在進行中的修改，artifacts 是每個修改裡用來說清楚「要做什麼、怎麼做、具體任務」的四份文件。
Archive 之後，changes 裡的 delta spec 合併進 specs，changes 資料夾搬到 archive 存檔，循環繼續。
搞清楚這三個概念之後，下一篇帶你跑完 /opsx:propose → apply → archive 這條最核心的流程——每個指令做了什麼、你要確認什麼、什麼時候該繼續往下走。