核心概念概覽

OpenSpec 是您和 AI 之間的一個輕量級協定層。 您會寫下一個變更應該做什麼，AI 會起草細節內容，然後你們雙方都會審閱相同的計畫，只有在確認後才會開始編碼。本頁面就是將整個心智模型呈現在單一螢幕上。如果您需要完整的版本，Concepts 提供了詳盡的說明。

用五個詞來概括整個理念：先達成共識，再自信地建構。

五個核心概念

OpenSpec 的一切都建立在這五個概念之上。掌握這些概念，其餘細節皆為輔助。

1. Specs 是真相的來源。 一份規格（spec）描述了您的系統目前是如何運作的。它儲存在 openspec/specs/ 中，並依領域劃分 (auth/, payments/, ui/)。Specs 由需求（例如：「系統應在 30 分鐘後過期會話次」）和情境（具體的 given/when/then 範例）組成。您可以將 Specs 理解為對「這個軟體要做什麼？」這個問題所達成的唯一共識答案。

2. 一個變更是一個工作單元。 當您想要新增、修改或移除某項功能時，您就創建一個變更：這是一個位於 openspec/changes/ 中的資料夾，將該工作的所有內容集中在一個地方。包括提案（proposal）、設計、任務清單和 Spec 的編輯內容。一個變更，一個資料夾，一項功能。

3. Delta specs 描述的是「正在改變的部分」，而非整個世界。 在一個變更內部，您不需要重寫整個規格。您只需要撰寫一個小的 delta：ADDED（新增）此需求，MODIFIED（修改）那一個，REMOVED（移除）另一個。這就是 OpenSpec 擅長編輯現有系統而非僅限於全新專案的原因。您描述的是差異（diff），而不是最終目的地。

4. Artifacts (產物) 是相互建構的。 一個變更包含幾個文件，它們會依照自然順序創建，每個文件都為下一個提供基礎：

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

您可以隨時回顧其中的任何一份文件。它們是促成者（enablers），而非門檻（gates）。（詳情請見下方。）

5. Archiving (歸檔) 將變更納入真相之中。 當工作完成後，您就歸檔該變更。它的 delta specs 會合併到主規格中，而該變更資料夾則會帶著日期戳記移動到 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/ 是真相的來源（what's true）。changes/ 是您正在提議的內容（what you're proposing）。歸檔操作將一個提案納入真相之中。

您實際會執行的流程

在預設設定下，您的日常工作流程如下。您可以選擇先思考一下；然後一個指令會由 AI 起草計畫，您閱讀並調整該計畫，接著下一階段進行建構，最後一階段完成歸檔。

/opsx:explore                   →  (可選) 先與 AI 共同思考
/opsx:propose add-dark-mode     →  AI 起草提案、規格、設計和任務清單
        (您閱讀並調整計畫)
/opsx:apply                     →  AI 進行建構，並勾選任務
/opsx:archive                   →  更新規格，歸檔變更

如有疑問，請先從探索（explore）開始。 /opsx:explore 是一個零風險的思考夥伴：它會閱讀您的程式碼，列出選項，在任何產物存在之前，就將模糊的想法轉化為具體計畫。它是對抗 AI 從一個籠統的提示中建構某個東西的最佳解藥劑。是否已經完全清楚自己想要什麼？請直接跳到 /opsx:propose。無論哪種情況，探索功能都包含在預設配置中，因此它始終可用。請參閱 Explore guide。

這些是輸入於 AI 助理聊天介面中的斜線指令（slash commands）。設定 (openspec init) 是在您的終端機（terminal）上執行的。如果這個分工對您來說是新的，請先閱讀 How Commands Work；這是最常發生的困惑點。

「促成者，而非門檻」

這句話出現在 OpenSpec 的各個地方，因此這裡將其翻譯為白話文。

傳統的規格流程是瀑布式：完成規劃後，才被允許進行實作，而回溯修改會非常痛苦。OpenSpec 反對這種做法。proposal → specs → design → tasks 這個順序顯示的是「下一步可能做什麼」，而不是「您被迫必須」做什麼。

在實作過程中發現設計有誤？請編輯 design.md 並繼續進行。意識到範圍需要縮減？更新提案（proposal）。沒有任何東西會鎖住您。依賴關係僅存在於 AI 需要上下文的基礎上（沒有規格作為基礎，AI 無法撰寫出好的任務），而不是用來限制您。

這裡的力量在於誠實：真正的工作是混亂且迭代的，而 OpenSpec 允許這一點。其代價是紀律：因為沒有任何東西會強迫您向前推進，所以需要您自己來保持變更的專注性，而不是任由它蔓延失控。Workflows 指南提供了良好的習慣養成建議。

為何值得付出這點微小的額外工作量

簡單來說：OpenSpec 增加了一個步驟。在建構之前，您需要寫一份簡短的計畫。那麼，您能得到什麼呢？

• 您能在成本高昂前就發現錯誤的方向。 在一段話語的提案中糾正一個誤解是免費的。等 AI 編寫了 400 行程式碼後再修正則不是。
• 規劃和程式碼保留在同一 Codebase 中。 六個月後，規格文件會告訴您（以及下一次 AI 會議）這個系統為何以這種方式運作。
• 變更是可以被審查的。 一個變更資料夾是一個整潔的套件：閱讀提案、瀏覽差異（deltas）、檢查任務清單。無需在聊天記錄中進行考古挖掘。
• 它能適應現有的程式碼庫。 Delta 允許您在沒有先完整文件化整個應用程式的情況下，就指定對一個擁有 50,000 行程式碼的應用程式進行變更。

而誠實地說，這是一個取捨：對於一個真正微不足道的單行修復，這個儀式可能不值，這是可以接受的。OpenSpec 的設計目標是輕量化，但它並非免費的。請在「共識至關重要」的地方使用它，事實證明一旦您開始與一位能自信地建構出您模糊要求之物的 AI 合作，這種情況就發生了。

下一步該去哪裡？

• 新手？Getting Started 會完整地帶領您完成第一個變更。
• 還不確定要建什麼？請從 Explore First 開始。
• 對指令在哪裡執行感到困惑？請參閱 How Commands Work。
• 想了解所有內容的深度版本？Concepts。
• 喜歡透過範例學習？Examples & Recipes。
• 需要定義術語？Glossary。