專為 AI 程式設計助手設計的規範驅動開發工具。

在 X 上關注 @0xTab 獲取更新 · 加入 OpenSpec Discord 尋求幫助與提問。

OpenSpec 透過規範驅動開發，讓人類和 AI 程式設計助手達成一致，讓您在撰寫任何程式碼之前就能確定要建構什麼。無需 API 金鑰。

AI 程式設計助手功能強大，但當需求存放在聊天記錄中時，結果會難以預測。OpenSpec 新增一個輕量的規範工作流程，在實作前鎖定意圖，提供可確定且可檢視的輸出。

主要優勢：

• 在工作開始前，人類和 AI 利害關係人就規範達成一致。
• 結構化的變更資料夾（提案、任務和規範更新）保持範圍明確且可稽核。
• 共享對提案、進行中或已封存內容的可見性。
• 與您已經在使用的 AI 工具協作：在支援的地方使用自訂 slash 命令，其他地方則使用情境規則。

• 輕量化：簡單的工作流程、無需 API 金鑰、最少的設定。
• 優先支援現有專案：不只適用於從零開始的專案。OpenSpec 將真實來源與提案分開：openspec/specs/（當前真實）和 openspec/changes/（提議的更新）。這讓差異在功能之間保持明確且易於管理。
• 變更追蹤：提案、任務和規範差異存放在一起；封存會將已核准的更新合併回規範。
• 與 spec-kit 和 Kiro 比較：這些工具在全新功能（0→1）方面表現出色。OpenSpec 在修改現有行為（1→n）時也同樣出色，特別是當更新跨越多個規範時。

請參閱OpenSpec 的比較中的完整比較。

┌────────────────────┐
│ 起草變更提案       │
│                    │
└────────┬───────────┘
         │ 與您的 AI 分享意圖
         ▼
┌────────────────────┐
│ 檢視與對齊         │
│ (編輯規範/任務)    │◀──── 回饋迴圈 ──────┐
└────────┬───────────┘                      │
         │ 已核准的計劃                     │
         ▼                                  │
┌────────────────────┐                      │
│ 實作任務           │──────────────────────┘
│ (AI 撰寫程式碼)    │
└────────┬───────────┘
         │ 交付變更
         ▼
┌────────────────────┐
│ 封存並更新         │
│ 規範（來源）       │
└────────────────────┘

1. 起草一個變更提案，捕捉您想要的規範更新。
2. 與您的 AI 助手檢視提案，直到所有人都同意。
3. 實作參考已同意規範的任務。
4. 封存變更，將已核准的更新合併回真實來源規範。

這些工具內建 OpenSpec 命令。在提示時選擇 OpenSpec 整合。

Kilo Code 會自動發現團隊工作流程。將產生的檔案儲存在 .kilocode/workflows/ 下，並使用 /openspec-proposal.md、/openspec-apply.md 或 /openspec-archive.md 從命令面板觸發它們。

這些工具會自動從 openspec/AGENTS.md 讀取工作流程指令。如果需要提醒，請要求它們遵循 OpenSpec 工作流程。深入了解 AGENTS.md 慣例。

• Node.js >= 20.19.0 - 使用 node --version 檢查您的版本

npm install -g @minidoracat/openspec-tw@latest

驗證安裝：

openspec-tw --version

導航至您的專案目錄：

cd my-project

執行初始化：

openspec-tw init

初始化期間會發生什麼：

• 系統會提示您選擇任何原生支援的 AI 工具（Claude Code、CodeBuddy、Cursor、OpenCode 等）；其他助手始終依賴共享的 AGENTS.md 存根
• OpenSpec 會自動為您選擇的工具配置 slash 命令，並始終在專案根目錄寫入一個受管理的 AGENTS.md 交接檔
• 在您的專案中建立一個新的 openspec/ 目錄結構

設定後：

• 主要 AI 工具可以在無需額外配置的情況下觸發 /openspec 工作流程
• 執行 openspec-tw list 以驗證設定並檢視任何活動變更
• 如果您的程式設計助手沒有立即顯示新的 slash 命令，請重新啟動它。Slash 命令在啟動時載入，因此重新啟動可確保它們出現

openspec-tw init 完成後，您將收到一個建議的提示，以幫助填充您的專案情境：

填充您的專案情境：
「請閱讀 openspec/project.md 並幫助我填寫有關我的專案、技術堆疊和慣例的詳細資訊」

使用 openspec/project.md 定義專案層級的慣例、標準、架構模式以及其他應在所有變更中遵循的指南。

這是一個完整的 OpenSpec 工作流程真實範例。這適用於任何 AI 工具。具有原生 slash 命令的工具會自動識別快捷方式。

首先要求您的 AI 建立一個變更提案：

您：建立一個 OpenSpec 變更提案，用於依角色和團隊新增個人資料搜尋篩選器
    （具有 slash 命令的工具的快捷方式：/openspec:proposal 新增個人資料搜尋篩選器）

AI：我將為個人資料篩選器建立一個 OpenSpec 變更提案。
    *使用 proposal.md、tasks.md、規範差異建構 openspec/changes/add-profile-filters/*

檢查變更是否正確建立並檢視提案：

$ openspec-tw list                             # 確認變更資料夾存在
$ openspec-tw validate add-profile-filters     # 驗證規範格式
$ openspec-tw show add-profile-filters         # 檢視提案、任務和規範差異

迭代規範，直到它們符合您的需求：

您：您能為角色和團隊篩選器新增驗收標準嗎？

AI：我將使用角色和團隊篩選器的情境更新規範差異。
    *編輯 openspec/changes/add-profile-filters/specs/profile/spec.md 和 tasks.md*

一旦規範看起來不錯，開始實作：

您：規範看起來不錯。讓我們實作這個變更。
    （具有 slash 命令的工具的快捷方式：/openspec:apply add-profile-filters）

AI：我將處理 add-profile-filters 變更中的任務。
    *實作來自 openspec/changes/add-profile-filters/tasks.md 的任務*
    *標記任務為完成：任務 1.1 ✓、任務 1.2 ✓、任務 2.1 ✓...*

實作完成後，封存變更：

AI：所有任務都已完成。實作已就緒。

您：請封存變更
    （具有 slash 命令的工具的快捷方式：/openspec:archive add-profile-filters）

AI：我將封存 add-profile-filters 變更。
   *執行：openspec-tw archive add-profile-filters --yes*
    ✓ 變更已成功封存。規範已更新。準備好進行下一個功能！

或在終端機中自行執行命令：

$ openspec-tw archive add-profile-filters --yes  # 無提示封存已完成的變更

注意： 具有原生 slash 命令的工具（Claude Code、CodeBuddy、Cursor、Codex）可以使用所示的快捷方式。所有其他工具都可以使用自然語言請求「建立 OpenSpec 提案」、「應用 OpenSpec 變更」或「封存變更」。

openspec-tw list               # 檢視活動變更資料夾
openspec-tw view               # 規範和變更的互動式儀表板
openspec-tw show <change>      # 顯示變更詳情（提案、任務、規範更新）
openspec-tw validate <change>  # 檢查規範格式和結構
openspec-tw archive <change> [--yes|-y]   # 將已完成的變更移至 archive/（使用 --yes 為非互動式）

當您要求 AI 助手「新增雙因素驗證」時，它會建立：

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # 當前驗證規範（如果存在）
└── changes/
    └── add-2fa/              # AI 建立整個結構
        ├── proposal.md       # 為什麼以及哪些變更
        ├── tasks.md          # 實作清單
        ├── design.md         # 技術決策（選擇性）
        └── specs/
            └── auth/
                └── spec.md   # 顯示新增內容的差異

# 驗證規範

## 目的
驗證和工作階段管理。

## 需求
### 需求：使用者驗證
系統應在成功登入時發出 JWT。

#### 情境：有效憑證
- 當使用者提交有效憑證時
- 則傳回 JWT

# 驗證差異

## 已新增的需求
### 需求：雙因素驗證
系統必須在登入期間要求第二個因素。

#### 情境：需要 OTP
- 當使用者提交有效憑證時
- 則需要 OTP 挑戰

## 1. 資料庫設定
- [ ] 1.1 將 OTP 密鑰欄位新增至使用者表
- [ ] 1.2 建立 OTP 驗證日誌表

## 2. 後端實作
- [ ] 2.1 新增 OTP 產生端點
- [ ] 2.2 修改登入流程以要求 OTP
- [ ] 2.3 新增 OTP 驗證端點

## 3. 前端更新
- [ ] 3.1 建立 OTP 輸入元件
- [ ] 3.2 更新登入流程 UI

重要： 您不需要手動建立這些檔案。您的 AI 助手會根據您的需求和現有程式碼庫產生它們。

差異是顯示規範如何變更的「補丁」：

• ## 已新增的需求 - 新功能
• ## 已修改的需求 - 變更的行為（包含完整更新的文字）
• ## 已移除的需求 - 已棄用的功能

格式要求：

• 使用 ### 需求：<名稱> 作為標題
• 每個需求至少需要一個 #### 情境： 區塊
• 在需求文字中使用「應」或「必須」

OpenSpec 的雙資料夾模型（openspec/specs/ 用於當前真實，openspec/changes/ 用於提議的更新）將狀態和差異分開。這在您修改現有功能或觸及多個規範時具有可擴展性。spec-kit 在全新/0→1 專案方面表現出色，但對於跨規範更新和演進功能提供的結構較少。

OpenSpec 將功能的每個變更分組在一個資料夾中（openspec/changes/feature-name/），使得追蹤相關規範、任務和設計變得容易。Kiro 將更新分散在多個規範資料夾中，這可能使功能追蹤更加困難。

沒有規範時，AI 程式設計助手會根據模糊的提示產生程式碼，通常會遺漏需求或新增不需要的功能。OpenSpec 透過在撰寫任何程式碼之前就所需行為達成一致，帶來可預測性。

1. 初始化 OpenSpec – 在您的儲存庫中執行 openspec-tw init。
2. 從新功能開始 – 要求您的 AI 將即將進行的工作捕捉為變更提案。
3. 逐步成長 – 每個變更都會封存到記錄系統的活文件規範中。
4. 保持靈活性 – 不同的團隊成員可以使用 Claude Code、CodeBuddy、Cursor 或任何 AGENTS.md 相容工具，同時共享相同的規範。

每當有人切換工具時執行 openspec-tw update，以便您的代理程式獲取最新的指令和 slash 命令綁定。

1. 升級套件

   npm install -g @minidoracat/openspec-tw@latest

2. 更新代理指令
   • 在每個專案中執行 openspec-tw update 以重新產生 AI 指引並確保最新的 slash 命令處於活動狀態。

• 安裝依賴項：pnpm install
• 建置：pnpm run build
• 測試：pnpm test
• 本地開發 CLI：pnpm run dev 或 pnpm run dev:cli
• 傳統提交（單行）：type(scope): subject

MIT