核心概念速覽

OpenSpec 是你與 AI 之間的輕量級約定層。 你寫下變更應該實作什麼，AI 起草細節，你們共同審閱同一份計畫，然後才開始編寫程式碼。本頁在一屏內介紹完整的思維模型。想了解詳細說明，請看概念。

用五個詞概括整個理念：先達成一致，再放心建置。

五個理念

OpenSpec 中的一切都建立在五個概念之上。理解它們，其餘內容就只是細節。

1. 規格說明是真實依據。 規格說明描述系統當前的行為，存放在 openspec/specs/ 中，並按領域（auth/、payments/、ui/）組織。規格說明由需求（例如“系統 SHALL 在 30 分鐘後使會話過期”）和情境（具體的給定/當/則範例）組成。可以把規格說明看作“這款軟體做什麼？”這一問題唯一且共同認可的答案。

2. 一個變更就是一個工作單元。 想要新增、修改或刪除行為時，就建立一個變更：在 openspec/changes/ 下建立一個資料夾，把這項工作的所有內容放在一起，包括提案、設計、任務清單和規格說明修改。一個變更，一個資料夾，一項功能。

3. 差異規格說明描述的是變更，而不是整個世界。 在變更中，你無需重寫整份規格說明，而是寫一小段差異：新增 (ADDED) 這項需求、修改 (MODIFIED) 那項需求、移除 (REMOVED) 另一項需求。這正是 OpenSpec 既適合編輯現有系統、又不僅限於從零建置的關鍵。描述差異，而非最終全貌。

4. 產物層層銜接。 一個變更包含若干文件，它們按自然順序建立，並以前一項為基礎：

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

任何時候都可以回頭修改其中任一文件。它們是助力，不是關卡。（下文詳述。）

5. 歸檔會將變更併入真實依據。 工作完成後，歸檔這個變更。其差異規格說明會合併到主規格說明中，變更資料夾則帶日期標記並移至 changes/archive/。此時，規格說明反映新的實際情況，你也可以開始下一個變更，整個迴圈就此閉合。

示意圖

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ source of truth  │  merge  │ one folder per change    │    │
│   │ how things work  │  on     │ proposal · design ·      │    │
│   │ today            │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

兩個資料夾。specs/ 存放既定事實，changes/ 存放擬議變更。歸檔會將提案納入既定事實。

實際使用的迴圈

在預設設定下，你的日常流程如下。可以先自行梳理思路；接著用一條命令起草計畫，閱讀計畫後再用下一條命令實作，最後一條命令將其歸檔。

/opsx:explore                   →  (optional) think it through with the AI first
/opsx:propose add-dark-mode     →  AI drafts proposal, specs, design, tasks
        (you read and adjust the plan)
/opsx:apply                     →  AI builds it, checking off tasks
/opsx:archive                   →  specs updated, change archived

拿不準時，先從探索開始。 /opsx:explore 是一位沒有壓力的思考夥伴：它會讀取程式碼、列出選項，並在編寫任何程式碼之前，把模糊的想法整理成具體計畫。它最能避免 AI 根據含糊的提示就“隨便建置點什麼”。如果你已經完全清楚自己要什麼？直接執行 /opsx:propose 即可。無論如何，預設設定都包含 explore，因此隨時可用。參閱探索指南。

這些斜槓命令是在 AI 助手的聊天中輸入的。專案設定 (openspec init) 則在終端中完成。如果你對這種分工感到陌生，請先閱讀命令的工作方式；這是最常見的困惑點。

“助力，而非關卡”

OpenSpec 中經常出現這句話，下面用通俗的話解釋其含義。

傳統規格說明流程是瀑布式的：必須先完成規劃，然後才能實作，回頭修改還很困難。OpenSpec 不這樣做。proposal → specs → design → tasks 的順序說明下一步可以做什麼，而不是必須做什麼。

如果在實作過程中發現設計有誤？編輯 design.md 後繼續。發現範圍應該縮小？更新提案即可。沒有任何內容會鎖死。依賴關係只是為了給 AI 提供所需上下文（沒有規格說明作為基礎，就無法寫出好的任務），並不是為了限制你。

這種做法的優點是誠實：真實工作本就雜亂且反覆迭代，OpenSpec 允許它如實發生。代價則是需要自律：沒有什麼會強迫你繼續推進，因此你需要自己讓變更保持聚焦，避免範圍不斷膨脹。工作流程指南介紹了有助於做到這一點的習慣。

為什麼這點額外投入值得

坦白說，OpenSpec 會多加一個步驟：建置之前先寫一份簡短計畫。那麼它能帶來什麼？

• 趁走錯方向還不費錢時及時發現。 在一段提案中糾正誤解幾乎不費成本；等 AI 寫完 400 行程式碼後再糾正，就不是這樣了。
• 計畫與程式碼儲存在同一個儲存庫。 六個月後，你（以及下一次 AI 會話）仍能從規格說明中瞭解系統為何如此執行。
• 變更便於審查。 一個變更資料夾就是一個整潔的工作包：閱讀提案、瀏覽差異、檢查任務即可，不必從聊天記錄中考古。
• 適用於現有程式碼庫。 有了差異規格說明，你可以為一個 50,000 行的應用編寫變更規格，而無需先記錄整個系統。

同時也要坦誠地看待代價：對真正簡單的一行修復而言，這套流程的儀式感可能不值得，沒關係。OpenSpec 的設計目標是輕量，但並非零成本。在需要達成共識時使用它——一旦你與一個會自信地實作任何模糊要求的 AI 合作，就會發現大多數時候都需要共識。

接下來讀什麼

• 剛接觸 OpenSpec？快速入門會完整演示第一個變更。
• 還不確定該建置什麼？從先探索開始。
• 不清楚命令在哪兒執行？閱讀命令的工作方式。
• 想深入瞭解以上所有內容？閱讀概念。
• 想透過範例學習？閱讀範例與配方。
• 需要術語解釋？閱讀術語表。