基礎觀念

OpenSpec 核心觀念

深入了解 OpenSpec 的核心概念：Change、Capability、Scenario、Spec Delta 等關鍵名詞

核心名詞大解析

在開始使用 OpenSpec 與執行 opsx 指令之前，我們必須先理解它所定義的核心名詞。這些名詞構成了整個規格驅動開發的語彙。

1. 變更計畫 (Change)

變更計畫 (Change) 是 OpenSpec 中最基本的生命週期單元。每次當你想要在專案中「新增功能」、「修復錯誤 (Bug Fix)」或「重構程式碼」時，都應該建立一個獨立的變更計畫。

一個變更計畫在專案中的實體表現，是位於 openspec/changes/<change-id>/ 目錄下的一個子資料夾，其中 <change-id> 是該次變更的唯一代號（例如 add-openspec-tutorial-site）。在變更進行期間，所有與本次需求、設計和任務相關的檔案都會集中在此資料夾中：

proposal.md (提案)：說明這次修改的緣由（Why）、改動內容（What Changes）、受影響的能力（Capabilities）與系統衝擊（Impact）。
design.md (設計方案)：選填，記錄實作的技術細節、架構設計或資料庫結構等。
specs/ (暫存規格)：放置本次改動專屬的「規格增量」。
tasks.md (任務清單)：列出為了完成此變更而必須按順序實作的具體任務。

一次只專注於一個變更計畫，能幫助開發者（與 AI 助手）隔離無關的程式碼，確保每一次的提交 (Commit) 都是乾淨且具備原子性。

2. 能力 (Capability)

能力 (Capability) 描述的是系統所具備的某項軟體特性或功能區塊。它是對系統行為的高階抽象描述，而不是具體的程式碼類別。

在 OpenSpec 中，系統的「現況規格 (Specs)」會被拆分成多個 Capability，並在 openspec/specs/ 下以獨立的目錄或檔案進行管理。例如，在本教學網站專案中，我們拆分了以下幾個能力：

site-foundation (網站基礎與外觀)
content-collections (內容集合與格式)
code-experience (程式碼閱讀體驗)
static-search (Pagefind 靜態搜尋)

當你需要修改某個功能時，你必須明確指出你是在新增（Added）或修改（Modified）哪一個 Capability 的行為。這種結構化的方式能強迫我們將複雜的系統模組化，避免多個功能之間產生不必要的耦合。

3. 場景 (Scenario)

每個能力底下，都會包含數個具體且可測試的場景 (Scenario)。

場景使用類似 BDD (行為驅動開發) 的自然語言，定義了系統在特定操作下的預期行為。常用的格式為：

GIVEN (在某種狀態下)
WHEN (當某個操作觸發時)
THEN (系統應該做出什麼反應)

有時候也可以簡化為 WHEN / THEN 的二元結構。例如在 site-foundation 能力下的「響應式行動裝置導覽」中，就定義了如下的 Scenario：

#### Scenario: Mobile menu toggle
- **WHEN** a visitor on a viewport narrower than 768px taps the hamburger button
- **THEN** the sidebar navigation SHALL appear as an overlay drawer

SHALL / SHOULD / MAY 需求關鍵字：在 Scenario 的描述中，我們使用這些關鍵字來界定規格的強制性：

SHALL (必須)：最高強制性，若未通過則視為建置或驗收失敗。
SHOULD (應當)：建議事項，在可行範圍內應當達成。
MAY (可以)：選填或選擇性行為。

這些場景是 AI 進行實作和進行驗收測試的根本依據。AI 能精確地讀懂這些情境，並產生能百分之百符合 Scenario 描述的程式碼。

4. 規格增量 (Spec Delta)

在變更計畫進行的過程中，我們並不會直接去修改位於 openspec/specs/ 的主規格檔案，而是會在 openspec/changes/<change-id>/specs/ 下建立或修改檔案。這些存在於變更計畫內部的規格變動，就被稱為規格增量 (Spec Delta)。

當一個 Change 完成，並且通過驗收後，我們會執行歸檔。在此時，OpenSpec 工具會將變更計畫底下的「規格增量」與 openspec/specs/ 裡面的現況規格進行合併（將新增的場景加入、修改舊的場景）。這種做法類似 Git 的分支 (Branch) 與合併 (Merge) 機制，確保了在多人協作時，主規格不會在實作尚未完成前就先被污染。

5. 任務清單 (Tasks)

任務清單 (Tasks) 存放在變更計畫目錄下的 tasks.md 檔案中，是由 AI 在提案階段自動規劃出來的具體實作步驟。

每個任務都是一個檢核點：

- [ ] 代表未開始或進行中。
- [x] 代表已完成並已更新對應的代碼或規格。

在實作時，我們會遇到「🔴 人工檢查點」。這意味著這是一個關鍵的查核階段（例如專案初始化完成、基礎 layout 完成、或所有核心文章撰寫完成）。此時 AI 必須主動暫停，並通知人類開發者進行檢查，這能有效防止 AI 朝著錯誤的方向實作太深，節省修正成本。

核心名詞關係圖

這些核心概念在 OpenSpec 工作流中是如何相互搭配的呢？我們可以透過下圖來一窺究竟：

graph TD
    subgraph Repo Root
        config["openspec/config.yaml"]
        
        subgraph Specs Dir [openspec/specs/]
            capA["Capability A (site-foundation)"]
            capB["Capability B (code-experience)"]
        end
        
        subgraph Changes Dir [openspec/changes/]
            change["Change (add-openspec-tutorial-site)"]
            prop["proposal.md (說明 Why & What)"]
            tasks["tasks.md (實作步驟)"]
            delta["specs/ (規格增量 Spec Delta)"]
        end
    end
    
    change --> prop
    change --> tasks
    change --> delta
    
    delta -.->|歸檔時合併| Specs Dir
    capA -->|"包含多個"| scA["Scenarios (GIVEN/WHEN/THEN)"]

總結

Change 是每一次改動的「生命週期」。
Capability 是描述系統特性的「功能模組」。
Scenario 是功能模組下具體可驗收的「使用者情境」。
Spec Delta 是在 Change 中進行的「規格增減」。
Tasks 是引導人類與 AI 逐步實作的「地圖」。

理解了這些核心觀念後，我們就可以更清楚地看到 OpenSpec 指令是如何在這些產物之間遊走。在下一章，我們將介紹 [安裝與初始化]，說明如何在一個現有的專案中引入 OpenSpec。