OpenSpec 快速上手：讓你和 AI 在寫程式前先講好要做什麼

用 AI coding assistant 寫程式時，最痛的往往不是它不會寫，而是它「很有自信地寫錯東西」——因為需求只存在你當下那句模糊的 prompt 裡。OpenSpec 是一套輕量的 spec-driven development（SDD）框架，它在你和 AI 之間加了一層「先講好、再動手」的協議層：你把一個變更該做什麼寫成規格，AI 幫你補齊細節，兩邊看著同一份計畫，確認後才開始寫 code。讀完這篇，你能在自己的專案裝好 OpenSpec，跑完第一個「提案 → 實作 → 歸檔」的完整循環，並說得出每一步背後在做什麼。

OpenSpec GitHub Repository — 專案原始碼與官方 README

這是什麼？什麼時候會用到？

想像你請一位很厲害但很衝的工程師幫你做功能。你只丟一句「幫我加個深色模式」，他二話不說寫了 400 行 code——結果方向跟你想的不一樣，重來一次成本很高。AI coding assistant 就是這位工程師。

OpenSpec 做的事，就是在他動手前先攔一下：把「要做什麼、為什麼做、怎麼做、分幾步」寫成幾份簡短的文件，你看過、調整過，再讓 AI 照著實作。這些文件和你的 code 放在同一個 repo 裡，所以三個月後你（或下一次的 AI session）打開專案，還看得懂當初為什麼這樣設計。

什麼時候會用到？

  • 你已經在用 Claude Code、Cursor、Codex 這類 AI 工具寫 code，但常常覺得「它做出來的不是我要的」。
  • 你在一個既有的、很大的專案（brownfield）上加功能，不想從零把整個系統文件化。
  • 你想讓一個功能的計畫是可審查、可追溯的，而不是埋在一長串聊天記錄裡。

OpenSpec 刻意設計得很輕。真正一行就能改完的小修正，它可能是多餘的；但只要「你和 AI 對需求的理解要一致」這件事有價值——通常比你想的更常見——它就派得上用場。

最快用起來

OpenSpec 是一個 npm 全域套件，需要 Node.js 20.19.0 以上。安裝並在你的專案裡初始化：

npm install -g @fission-ai/openspec@latest

cd your-project
openspec init
Code language: CSS (css)

openspec init 會在專案裡建立一個 openspec/ 目錄，並幫你選用的 AI 工具（支援 25+ 種）寫入對應的 slash command 設定。接著，你就回到 AI assistant 的對話框裡工作，跑完一個完整循環：

/opsx:explore                   ← （選用）先跟 AI 把想法想清楚
/opsx:propose add-dark-mode     ← AI 起草提案、規格、設計、任務清單
        （你讀一遍，覺得不對就調整）
/opsx:apply                     ← AI 照著任務清單實作，逐項打勾
/opsx:archive                   ← 規格更新，這個變更歸檔，準備下一個

一個關鍵區別，也是新手最常卡住的地方：openspec ...（例如 openspec init）是打在終端機的指令；/opsx:...（例如 /opsx:propose）是打在AI 對話框裡的 slash command，就是你平常叫它寫 code 的那個框。沒有另外的「互動模式」要開，直接在 chat 裡輸入斜線指令，AI 就會接手。

範例背後發生了什麼事

上面那四行看起來只是打了幾個指令，但每一步都對應到 OpenSpec 的一個核心動作。我們拆開來看。

openspec init：建立一個「真相 + 提案」的雙資料夾結構

初始化後，專案裡多了這樣一個結構：

openspec/
├── specs/      ← 真相：系統「現在」怎麼運作，依領域分（auth/、payments/、ui/…）
└── changes/    ← 提案：每個變更一個資料夾，裡面放這次要改的所有東西

背後的原理是 OpenSpec 把「系統現況」和「你想做的改動」分成兩堆。specs/ 是大家同意的、對「這個軟體現在做什麼」的唯一答案；changes/ 是還在進行、尚未拍板的提案。這個分法讓計畫和實作有一個明確的交界，也讓每個變更都是一個可以獨立審查的小包裹。

/opsx:propose：把一句話變成一份可審查的計畫

當你輸入 /opsx:propose add-dark-mode，AI 會在 openspec/changes/add-dark-mode/ 底下產生幾份文件：

✓ proposal.md   — 為什麼做、要改什麼（intent 與 scope）
✓ specs/        — 這次變更的 delta 規格（新增/修改/移除哪些需求）
✓ design.md     — 技術上打算怎麼做
✓ tasks.md      — 實作用的任務清單（有 checkbox）

背後原理是：這幾份 artifact 是按自然順序、一份餵給下一份的——先有「為什麼」（proposal），才知道要定義哪些「行為」（specs），才談得上「怎麼實作」（design），最後拆成「步驟」（tasks）。這一步的真正價值在於：修正一個「一段話的提案」裡的誤解是免費的；等 AI 寫完 400 行才發現理解錯了，代價就大了。你在這裡讀計畫、調整計畫，是整個流程最省成本的攔截點。

/opsx:apply：照著任務清單把 code 寫出來

/opsx:apply 讓 AI 讀取 tasks.md，一項一項實作並打勾。因為它手上有 proposal、specs、design 當作 context，它不是在猜你要什麼，而是在執行一份你已經同意的計畫。實作過程中如果發現設計不對，你隨時可以回頭改 design.md 或縮小 proposal.md 的範圍再繼續——沒有任何一步會被鎖死。

/opsx:archive：把提案折疊回「真相」

功能做完後，/opsx:archive 會把這次變更的 delta 規格合併進主 specs/：新增的需求被附加、修改的需求取代舊版、移除的需求被刪掉；變更資料夾則移到 changes/archive/ 並蓋上日期戳記。這一步之後，你的 specs/ 就描述了系統的新現況，循環閉合，準備好下一個變更。

核心概念

理解下面五個概念，OpenSpec 其他用法你大多能舉一反三。這也是官方 Core Concepts at a Glance 濃縮的心智模型。

  • Spec（規格）是真相：規格描述系統「現在」的行為，住在 openspec/specs/，依領域分類。它由 requirement（「系統 SHALL 在閒置 30 分鐘後讓 session 過期」）和 scenario（具體的 given/when/then 例子）組成。它是「這個軟體做什麼」這個問題唯一、被同意過的答案。
  • Change（變更）是一個工作單位：想新增、修改或移除某個行為時，你開一個 change，也就是 openspec/changes/ 裡的一個資料夾，把這件事相關的所有東西——提案、設計、任務、規格改動——都放在一起。一個變更、一個資料夾、一個功能。
  • Delta spec（差異規格）只描述「改了什麼」：在一個變更裡，你不重寫整份規格，只寫一小段差異：ADDED（新增）這條需求、MODIFIED（修改）那條、REMOVED（移除）另一條。這正是 OpenSpec 擅長改造既有系統、而不只是從零開專案的關鍵——你描述的是 diff，不是整個目的地。
  • Artifact 是「enabler，不是 gate」：proposal → specs → design → tasks 這個順序，指的是「接下來變得可能做什麼」，而不是「你被強迫先做完什麼」。這不是瀑布式的階段閘門。實作到一半發現設計錯了，就回去改 design.md 繼續走；沒有任何一步會卡死你。順序存在只是為了讓 AI 有足夠 context（沒有規格就寫不出好任務），不是為了框住你。
  • Archive 讓循環閉合：歸檔時，變更的 delta 規格合併回主規格，變更資料夾移進 archive/。你的規格於是描述了新的現實——這就是為什麼 OpenSpec 能在專案長期演進中，一直保持「規格 = 現況」而不飄移。

使用方向

裝好之後，依你的情境挑對應的用法：

  • 還不確定要做什麼：先用 /opsx:explore。它是一個零風險的思考夥伴，會讀你的 code、權衡選項，把一個模糊的想法收斂成具體計畫，全程還沒產生任何 artifact。想深入看 Explore 指南。
  • 已經知道要做什麼：直接 /opsx:propose <你想做的東西>，讓 AI 起草整包計畫再開工。搭配用法可參考 Workflows 指南。
  • 在既有大型專案上導入：不需要先把整個系統文件化——靠 delta spec 就能只針對這次變更下規格。詳見 Existing Projects 指南。
  • 想要更完整的指令流程：預設 core profile 提供 explore、propose、apply、sync、archive；用 openspec config profile 切換到擴充 profile，再跑 openspec update，就能啟用 /opsx:new、/opsx:continue、/opsx:verify 等指令。
  • 團隊 / 跨 repo 協作：當一個功能橫跨多個 repo、需求由某個團隊擁有並被其他團隊引用時，可以看還在 beta 的 Stores User Guide，把規劃放進一個獨立的 repo 共享。

想要一頁看懂整個心智模型，Core Concepts at a Glance 是最好的起點；需要更完整的第一次操作，就從官方 Getting Started 開始。

Vibe Coding：把工具用進你的專案

以下是你可以直接給 AI（Claude Code、Cursor、Copilot 等）的 prompt 指令，把本文介紹的 OpenSpec 概念套進你自己的專案。替換掉角括號 <...> 裡跟你專案相關的部分即可。

在新專案導入 OpenSpec 並跑完第一個循環

場景：你剛用 openspec init 初始化好一個新專案，想讓 AI 帶著你走完一次完整的「提案 → 實作 → 歸檔」循環，順便理解每一步在做什麼。

給 AI 的指令：

這個專案已經用 OpenSpec 初始化過了，openspec/ 目錄和 slash command 都設定完成。我想加一個功能：<用一句話描述你要的功能，例如：讓使用者可以把文章加入收藏清單>。請先執行 /opsx:propose add-favorites，在 openspec/changes/add-favorites/ 底下產生 proposal.md、delta 規格、design.md 和 tasks.md。產完之後，用條列方式向我說明：這次變更的 intent 與 scope 是什麼、你在 delta 規格裡 ADDED 了哪些需求、design.md 打算怎麼實作。先不要寫任何 code，等我 review 過 proposal 再繼續。

效果：AI 會用 /opsx:propose 產出四份可審查的 artifact，並停在計畫階段讓你檢查，把「修正一段話的成本」留在最便宜的攔截點，而不是等它寫完幾百行才發現方向錯了。

在既有大型專案上用 delta spec 局部導入

場景：你有一個已經很龐大的 brownfield 專案，不想也不可能先把整個系統文件化，只想針對接下來要改的地方下規格。

給 AI 的指令：

這是一個既有的大型專案，我不打算把整個 codebase 都文件化。我只想針對接下來這個變更寫規格：<描述你要改的行為，例如：把 session 逾時從 60 分鐘改成 30 分鐘，並在逾時前 5 分鐘提醒使用者>。請用 OpenSpec 的 brownfield 做法：只針對這次變更寫 delta 規格，用 ADDED / MODIFIED / REMOVED 標記需求的差異，不要重寫或臆測系統其他部分的既有規格。先跑 /opsx:propose，並在 delta 規格裡用 given/when/then 的 scenario 具體描述新行為。

效果：AI 只會描述「這次改了什麼」的 diff，而不是整個系統的現況，讓你能在幾乎沒有前置文件化成本的情況下，把 spec-driven 的紀律套進既有專案。

用 /opsx:explore 把模糊想法收斂成計畫

場景：你其實還沒想清楚要做什麼，只有一個模糊方向，想先跟 AI 討論、權衡選項，還不想產生任何 artifact。

給 AI 的指令：

我有一個還很模糊的想法：<描述你的模糊需求，例如：我覺得現在的通知系統很吵，想讓它更聰明一點，但還不確定該怎麼做>。請用 OpenSpec 的 /opsx:explore，先讀我的 code、理解現況，然後跟我一起權衡幾種可能的方向、各自的取捨是什麼。這個階段先不要產生 proposal 或任何 artifact，我們先把方向聊清楚，等收斂出具體計畫，我再叫你 /opsx:propose。

效果：AI 進入零風險的思考夥伴模式，讀 code、攤開選項、幫你把方向收斂，全程不落地任何檔案，等你想清楚了再進入正式提案。

讓 AI 照著已同意的計畫實作並逐項打勾

場景：proposal 你已經 review 過、覺得沒問題，準備讓 AI 進入實作階段。

給 AI 的指令：

openspec/changes/<你的變更名稱>/ 底下的 proposal、specs、design 我都看過也同意了。現在請執行 /opsx:apply，讀 tasks.md 一項一項實作，每完成一項就在 tasks.md 打勾。實作時請以 proposal 和 delta 規格為準，不要自行擴充範圍。如果你實作到一半發現 design.md 有問題，先停下來告訴我，我們一起改 design 或縮小 proposal 的範圍，再繼續——不要默默偏離計畫。

效果：AI 會把手上的 proposal / specs / design 當作 context 去執行一份你已同意的計畫，而不是在猜你要什麼，並在偏離風險出現時回頭跟你對齊，而非硬幹到底。

歸檔變更，讓規格重新等於現況

場景：功能做完、驗證過了，你想把這次變更的 delta 規格折疊回主規格，讓 specs/ 重新描述系統的新現實。

給 AI 的指令：

<變更名稱> 這個功能已經實作完成也驗證過了。請執行 /opsx:archive，把這次變更的 delta 規格合併回 openspec/specs/：ADDED 的需求附加進去、MODIFIED 的取代舊版、REMOVED 的刪掉，然後把變更資料夾移到 changes/archive/ 並蓋上日期戳記。合併完成後，請告訴我主 specs/ 有哪些領域的規格被更新了，讓我確認「規格 = 現況」沒有飄移。

效果：AI 會把提案折疊回真相、完成一次閉環，確保專案長期演進時 specs/ 始終等於系統當下的真實行為，下一個變更也能站在正確的現況上開始。

延伸閱讀

0
標籤

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *