初識OpenSpec

各位朋友大家好，我係小溪，見字如面。之前我哋初步認識咗GitHub開源嘅SDD工具包Spec Kit，今日我哋就嚟瞭解另一款優秀嘅SDD開源工具OpenSpec。對Spec Kit仲未熟悉嘅朋友可以睇返之前嘅內容：

• 初識Spec Kit

目前使用版本

openspec 0.16.0

優勢

• 開源免費

• 適用於 0→1 和 1→N 的項目

• 多平台支援

限制

• 需要對OpenSpec嘅使用流程有一定嘅認識

簡介

OpenSpec係一個規範驅動開發工具，專為AI編程助手設計。佢通過結構化嘅變更文件夾（提案、任務同規範更新）嚟保持範圍明確同可審計，等人類同AI利益相關者喺開始工作之前達成一致。

規範驅動開發（SDD）嘅核心理念係：先定義規範，再畀AI按規範施工。

GitHub地址：https://github.com/Fission-AI/OpenSpec

核心功能

• 🚀 輕量級：唔需要API金鑰，最簡設定

• 🔄 現有項目優先：特別適合修改現有功能 (1→n)

• 📋 變更追蹤：提案、任務同規範差異嘅完整生命週期管理

• 🤖 AI工具集成：支援多種主流AI編碼助手

點解需要OpenSpec？

傳統AI編碼助手嘅問題：

• 需求描述模糊：用自然語言一句話描述或者表達有歧義，AI只能「估」我哋嘅意圖

• 上下文缺失：AI唔知道項目嘅整體架構同約束條件，成日漏咗重要功能、加咗冇需要嘅功能

• 標準缺失：冇明確嘅輸入輸出規範，AI只能自由發揮，搞到代碼難以預測

• 文檔滯後：代碼同文檔分開，一改就過時

OpenSpec通過規範驅動開發解決呢啲問題：

• 明確共識：喺編碼之前確定所有要求，技術規範達成一致

• 結構化變更：所有相關文檔集中管理，結構化嘅變更文件夾（提案、任務同規範更新）令範圍明確且可審計

• 可審查輸出：AI根據明確規範生成代碼，共享對已提議、進行中或已存檔內容嘅可見性

• 版本控制：完整追蹤所有變更歷史

工作流程

OpenSpec嘅工作流程大致如下：

• 起草變更提案：用自然語言描述想要實現嘅功能需求，AI會分析需求、詢問關鍵細節、生成完整提案文檔、設計文檔、列出任務清單、創建規範增量

• 審查對齊：同AI助手一齊審查提案，對齊遺漏，直到規範統一，得到所有人認可

• 實施任務：嚴格按照規範實施開發任務，逐一完成任務清單，標記任務進度

• 存檔更新：將變更歸檔保存，將批准嘅規範合併到項目規範文檔

安裝配置

前置條件

• Node.js 20.19.0或以上版本

安裝OpenSpec CLI

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

喺命令行輸入以下指令驗證安裝，輸出到版本號就表示安裝成功

基本使用

支援嘅平台

命令行指令

OpenSpec提供咗一套用嚟管理OpenSpec規範嘅命令行指令，呢啲指令喺查看同驗證規範時好重要，喺命令行終端輸入 openspec -h 可以睇到完整嘅命令行幫助文檔

• init：喺項目中初始化OpenSpec，示例：openspecinit [options] [path]

• update：更新OpenSpec說明文件，示例：openspec update [path] 

• list：列出項目（默認列出變更）。使用 --specs 可以列出規範。示例：openspec list [options] 

• view：以互動式儀錶板形式展示規範同變更

• change：管理OpenSpec變更提案，⚠️已廢棄，建議用list

• archive：歸檔已完成嘅變更並更新主規範，示例：openspec archive [options] [change-name]

• spec：管理同查看OpenSpec規範

• validate：驗證變更同規範，示例：openspec validate [options] [item-name] 

• show：顯示某個變更或規範，示例：openspec show [options] [item-name] 

• help：顯示指定指令嘅幫助信息，示例：openspec help [command]

OpenSpec目錄結構

OpenSpec嘅 提案變更、驗證、執行 和 歸檔 管理嚴格依賴OpenSpec嘅目錄結構，一個完整嘅OpenSpec目錄結構大致如下：

openspec/
├── project.md             # 項目規範約定
├── AGENTS.md              # 為Agent提供的OpenSpec使用說明，一般不需要動
├── specs/                 # 源規範目錄，每次變更歸檔後會合併到這裏
│       ├── spec.md        # 源需求和場景規範
│       └── design.md      # 源技術模式
├── changes/                # 提案變更目錄
│   ├── [change-name]/     # 單個提案變更
│   │   ├── proposal.md     # 為什麼，什麼，影響
│   │   ├── tasks.md        # 實施檢查清單
│   │   ├── design.md       # 技術決策（可選；見標準）
│   │   └── specs/          # 增量變更規範
│   │       └── [capability]/
│   │           └── spec.md # ADDED/MODIFIED/REMOVED
│   └── archive/            # 已完成的提案變更

初始化項目

使用OpenSpec之前需要進行初始化，主要係喺項目中創建OpenSpec依賴嘅目錄結構。初始化項目都好簡單，直接喺命令行終端輸入指令：

$ openspec init

初始化過程分3步，第一步係OpenSpec嘅簡介，直接回車就得

第二步係AI開發工具選擇，OpenSpec兼容曬目前所有主流嘅AI開發工具，揀自己用開嘅AI開發工具會創建對應AI工具嘅自訂指令配置

回車繼續，第三步係信息確認，直接完成配置就得

初始化完成之後，OpenSpec會提供一個使用引導

Next steps - Copy these prompts to Antigravity:
────────────────────────────────────────────────────────────
1. Populate your project context:
   "Please read openspec/project.md and help me fill it out
    with details about my project, tech stack, and conventions"
2. Create your first change proposal:
   "I want to add [YOUR FEATURE HERE]. Please create an
    OpenSpec change proposal for this feature"
3. Learn the OpenSpec workflow:
   "Please explain the OpenSpec workflow from openspec/AGENTS.md
    and how I should work with you on this project"

• 梳理項目信息填充到 openspec/project.md 文件

• 創建變更提案示例

• 讓AI從 openspec/AGENTS.md 文件學習OpenSpec工作流嘅使用方式

初始化完成，我哋會得到如下嘅項目結構，包括 自訂指令、OpenSpec目錄、AGENTS.md

梳理項目功能

OpenSpec初始化完成之後，第一步係要讓AI熟悉項目，可以用初始化OpenSpec提供嘅引導建議，直接複製指導建議

AI會為我哋 熟悉項目更新 openspec/project.md、熟悉OpenSpec工作流程 、創建第一個提案

並畀出下一步建議

更新後嘅OpenSpec目錄結構如下：

如果我哋熟咗OpenSpec，都可以直接通過提示詞完成項目梳理

熟悉項目功能、技術棧等信息並填充 @project.md

創建變更提案

創建變更提案係開始一個需求嘅第一步，可以用自然語言描述需求嚟創建提案

創建一個 OpenSpec 變更提案，用於添加一個註冊登錄頁面

可以用OpenSpec提供嘅自訂指令

/openspec:proposal 添加一個註冊登錄頁面

對於描述模糊嘅需求，AI會向我哋提問，我哋針對問題作出對應回答

確定需要澄清的問題
1. 認證方式：本地存儲，不需要後端API支持，前端本地存儲即可
2. 功能範圍：不需要忘記密碼，不需要三方登錄，只提供默認賬號密碼登錄
3. 路由策略：安裝 Vue Router 來處理頁面導航，登錄後跳轉到首頁
4. 與現有變更的關係：創建新的變更提案，登錄頁面獨立實現

補充完疑問之後，AI會根據完整嘅需求再次創建提案，可以見到AI根據OpenSpec規則要求創建咗提案需要嘅目錄結構並對提案進行驗證（只有提案驗證通過先可以進行下一步）

提案創建完成之後，我哋可以得到一個新嘅變更目錄 openspec/changes/add-auth-pages，目前結構如下：

add-auth-pages
├── design.md          # 針對提案需求的設計方案
├── proposal.md        # 變更提案需求說明，包含Why、What和Impact
└── specs/
│  └── auth/
│    ├── spec.md      # 授權規範
│  └── routing/
│    ├── spec.md      # 路由規範
└── tasks.md           # 針對提案需求拆分的開發任務

提案創建完成之後都可以對提案進行反覆補充更新

驗證提案

喺提案變更之後，如果AI工具冇自動驗證，我哋都可以對提案變進行手動驗證

$ openspec validate add-auth-pages --strict

實施任務

提案同驗證都完成之後，就可以進入實施階段，可以用自然語言描述實施變更提案

實施 add-auth-pages 變更提案

都可以用OpenSpec提供嘅自訂指令

/openspec-apply add-auth-pages

AI會根據OpenSpec提供嘅變更提案規範執行開發任務，任務執行完成之後會同步更新任務狀態

實施階段都可以對規範進行補充，有唔滿意嘅地方直接提出，直到滿意為止

都可以將調整咗嘅樣式規範更新到變更提案入面

歸檔變更

實施開發完成之後，就可以進入到最後一步歸檔，歸檔變更嘅作用係將提案 specs 合併到主目錄 openspec/specs/令佢成為項目嘅正式規範。

同樣可以用自然語言描述進行歸檔變更

歸檔變更 add-auth-pages

可以用OpenSpec提供嘅自訂指令

/openspec-archive add-auth-pages

都可以用OpenSpec命令行指令

$ openspec archive add-auth-pages

歸檔完成之後可以見到，OpenSpec將 changes/add-auth-pages 提案移動到 changes/archive 目錄下並標記咗歸檔時間，同時將 changes/add-auth-pages/specs 合併到 openspec/specs 目錄下

到呢度，一個完整嘅需求變更就完成咗

點擊關注，準時接收最新消息

小夥伴們大家好，我是小溪，見字如面。前面我們初步認識了Github開源的SDD工具包Spec Kit，今天我們來了解另一款優秀的SDD開源工具OpenSpec。對Spec Kit還不瞭解的小夥伴可以看往期內容：

• 初識Spec Kit

當前使用版本

openspec 0.16.0

優勢

• 開源免費

• 適用於 0→1 和 1→N 的項目

• 多平台支持

限制

• 對OpenSpec的使用流程需要有一定的瞭解

簡介

OpenSpec是一個規範驅動開發工具，專門為AI編程助手設計。它通過結構化的變更文件夾（提案、任務和規範更新）來保持範圍的明確性和可審計性，讓人類和AI利益相關者在工作開始前就達成一致。

規範驅動開發（SDD）的核心理念是：先定義規範，再讓 AI 按規範施工。

Github地址：https://github.com/Fission-AI/OpenSpec

核心功能

• 🚀 輕量級：無需API密鑰，最小化設置

• 🔄 現有項目優先：特別適合修改現有功能 (1→n)

• 📋 變更跟蹤：提案、任務和規範差異的完整生命週期管理

• 🤖 AI工具集成：支持多種主流AI編碼助手

為什麼需要OpenSpec？

傳統AI編碼助手的問題：

• 需求描述模糊：通過自然語言一句話描述或者表達存在歧義，AI 只能"猜測"我們的意圖

• 上下文缺失：AI 不知道項目的整體架構和約束條件，經常遺漏重要功能、添加不必要的功能

• 標準缺失：沒有明確的輸入輸出規範，AI 只能自由發揮導致代碼不可預測

• 文檔滯後：代碼和文檔分離，一改就過期

OpenSpec通過規範驅動開發解決這些問題：

• 明確共識：在編碼前確定所有要求，技術規範達成一致

• 結構化變更：所有相關文檔集中管理，結構化的變更文件夾（提案、任務和規範更新）使範圍明確且可審計

• 可審查輸出：AI根據明確規範生成代碼，共享對已提議、正在進行或已存檔內容的可見性

• 版本控制：完整追蹤所有變更歷史

工作流程

OpenSpec的工作流程大致如下：

• 起草變更提案：通過自然語言描述想要實現功能需求，AI會分析需求詢問關鍵細節、生成完整提案文檔、設計文檔、羅列任務清單、創建規範增量

• 審查對齊：與AI助手一起審查提案，對齊遺漏，直到規範統一得到所有人認可

• 實施任務：嚴格按照規範實施開發任務，逐一完成任務清單，標記任務進度

• 存檔更新：變更歸檔保存，將批准的規範合併到項目規範文檔

安裝配置

前置條件

• Node.js 20.19.0及以上版本

安裝OpenSpec CLI

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

在命令行輸入以下命令驗證安裝，輸出版本號表示安裝成功

基本使用

支持的平台

命令行指令

OpenSpec提供了一套用於管理OpenSpec規範的命令行指令，這在查看和驗證規範時很重要，在命令行終端輸入 openspec -h 可以查看完整的命令行幫助文檔

• init：在項目中初始化OpenSpec，示例：openspecinit [options] [path]

• update：更新OpenSpec說明文件，示例：openspec update [path] 

• list：列出項目（默認列出變更）。使用 --specs 可列出規範。示例：openspec list [options] 

• view：以交互式儀表板形式展示規範與變更

• change：管理OpenSpec變更提案，⚠️廢棄了建議使用list

• archive：歸檔已完成的變更並更新主規範，示例：openspec archive [options] [change-name]

• spec：管理和查看OpenSpec規範

• validate：驗證變更與規範，示例：openspec validate [options] [item-name] 

• show：顯示某一變更或規範，示例：openspec show [options] [item-name] 

• help：顯示指定命令的幫助信息，示例：openspec help [command]

OpenSpec目錄結構

OpenSpec的 提案變更、驗證、執行 和 歸檔 管理嚴格依賴OpenSpec的目錄結構，一個完整的OpenSpec目錄結構大致如下：

openspec/
├── project.md             # 項目規範約定
├── AGENTS.md              # 為Agent提供的OpenSpec使用說明，一般不需要動
├── specs/                 # 源規範目錄，每次變更歸檔後會合併到這裏
│       ├── spec.md        # 源需求和場景規範
│       └── design.md      # 源技術模式
├── changes/                # 提案變更目錄
│   ├── [change-name]/     # 單個提案變更
│   │   ├── proposal.md     # 為什麼，什麼，影響
│   │   ├── tasks.md        # 實施檢查清單
│   │   ├── design.md       # 技術決策（可選；見標準）
│   │   └── specs/          # 增量變更規範
│   │       └── [capability]/
│   │           └── spec.md # ADDED/MODIFIED/REMOVED
│   └── archive/            # 已完成的提案變更

初始化項目

在使用OpenSpec之前需要進行初始化，主要是在項目中創建OpenSpec依賴的目錄結構。初始化項目也很簡單，直接在命令行終端輸入指令：

$ openspec init

初始化過程分為3步，第一步為OpenSpec的簡介，直接回車即可

第二步為AI開發工具選擇，OpenSpec兼容了所有目前主流的AI開發工具，選擇自己使用的AI開發工具會創建對應AI工具的自定義命令配置

回車繼續，第三步為信息確認，直接完成配置即可

初始化完成後，OpenSpec會提供一個使用引導

Next steps - Copy these prompts to Antigravity:
────────────────────────────────────────────────────────────
1. Populate your project context:
   "Please read openspec/project.md and help me fill it out
    with details about my project, tech stack, and conventions"
2. Create your first change proposal:
   "I want to add [YOUR FEATURE HERE]. Please create an
    OpenSpec change proposal for this feature"
3. Learn the OpenSpec workflow:
   "Please explain the OpenSpec workflow from openspec/AGENTS.md
    and how I should work with you on this project"

• 梳理項目信息填充到 openspec/project.md 文件

• 創建變更提案示例

• 讓AI從 openspec/AGENTS.md 文件學習OpenSpec工作流的使用方式

初始化完成，我們將得到如的項目結構，包括 自定義指令、OpenSpec目錄、AGENTS.md

梳理項目功能

OpenSpec初始化完成後，第一步是需要讓AI熟悉項目，可以使用初始化OpenSpec提供的引導建議，直接複製指導建議

AI會為我們 熟悉項目更新 openspec/project.md、熟悉OpenSpec工作流程 、創建第一個提案

並給出下一步建議

更新後的OpenSpec目錄結構如下：

如果我們熟悉了OpenSpec，也可以直接通過提示詞完成項目梳理

熟悉項目功能、技術棧等信息並填充 @project.md

創建變更提案

創建變更提案是開始一個需求的第一步，可以使用自然語言描述需求創建提案

創建一個 OpenSpec 變更提案，用於添加一個註冊登錄頁面

可以使用OpenSpec提供的自定義命令

/openspec:proposal 添加一個註冊登錄頁面

對於描述模糊的需求，AI會向我們提問，我真對問題做出對應回答

確定需要澄清的問題
1. 認證方式：本地存儲，不需要後端API支持，前端本地存儲即可
2. 功能範圍：不需要忘記密碼，不需要三方登錄，只提供默認賬號密碼登錄
3. 路由策略：安裝 Vue Router 來處理頁面導航，登錄後跳轉到首頁
4. 與現有變更的關係：創建新的變更提案，登錄頁面獨立實現

補充完疑問後，AI會根據完整的需求再次創建提案，可以看到AI根據OpenSpec規則要求創建了提案所需的目錄結構並對提案進行驗證（只有提案驗證通過後才能進行下一步）

提案創建完成後，我們可以得到一個新的變更目錄 openspec/changes/add-auth-pages，目前結構如下：

add-auth-pages
├── design.md          # 針對提案需求的設計方案
├── proposal.md        # 變更提案需求說明，包含Why、What和Impact
└── specs/
│  └── auth/
│    ├── spec.md      # 授權規範
│  └── routing/
│    ├── spec.md      # 路由規範
└── tasks.md           # 針對提案需求拆分的開發任務

提案創建完成後也可以對提案進行反覆補充更新

驗證提案

在提案變更後，如果AI工具沒有自動驗證，我們也可以對提案變更進行手動驗證

$ openspec validate add-auth-pages --strict

實施任務

提案及驗證都完成後，就可以進行實施階段了，可以使用自然語言描述實施變更提案

實施 add-auth-pages 變更提案

也可以使用OpenSpec提供的自定義命令

/openspec-apply add-auth-pages

AI會根據OpenSpec提供的變更提案規範執行開發任務，任務執行完成後會同步更新任務狀態

實施階段也是可以對規範進行補充的，有不滿意的地方直接提，直到滿意為止

也可以將調整後的樣式規範更新到變更提案中

歸檔變更

實施開發完成後，就可以進入到了最後一步歸檔了，歸檔變更的作用是把提案 specs 合併到主目錄 openspec/specs/使其成為項目的正式規範。

同樣可以使用自然語言描述進行歸檔變更

歸檔變更 add-auth-pages

可以使用OpenSpec提供的自定義命令

/openspec-archive add-auth-pages

也可以使用OpenSpec命令行指令

$ openspec archive add-auth-pages

歸檔完成後可以看到，OpenSpec將 changes/add-auth-pages 提案移動到了 changes/archive 目錄下並打上歸檔時間，同時將 changes/add-auth-pages/specs 合併到了 openspec/specs 目錄下

至此一個完整的需求變更就完成了

點擊關注，及時接收最新消息