一、為什么我們需要 OpenSpec？
隨著 AI 輔助編程工具被越來越廣泛地使用，開發(fā)者們遇到了一個難以回避的痛點：AI 能看懂代碼的語法和邏輯（當下存在的結果），卻無法憑空猜出這些代碼背后的“前世今生”（早期的業(yè)務考量與架構決策）。
當你在對話框里輸入一行指令時，AI 看到的是存量的源代碼和類型定義。然而，這段邏輯當初為什么要這么設計？有哪些邊界條件是必須繞過的坑？未來的架構演進方向是什么？這些隱藏在開發(fā)者大腦或碎片化文檔中的“軟上下文（Soft Context）”，是 AI 的盲區(qū)。
OpenSpec 這一開源框架正是為了打通這種“信息斷層”而誕生的。它不單是一套目錄規(guī)范，更是幫助 AI 搞懂項目背景的“意圖翻譯器”。通過一組簡單的斜杠命令（Slash Commands），OpenSpec 能把你和 AI 的協(xié)作從“直接隨性地生成代碼”升級為“規(guī)格驅動開發(fā)”（Spec-Driven Development）。這也意味著，在生成代碼前，AI 就已經(jīng)徹底搞懂了你的需求背景與技術底線。
二、OpenSpec 與 AI Skills 的比較
OpenSpec 和 AI Skills (Agent Skills) 都是為了解決 AI 編程時代“如何讓 AI 更可靠地參與開發(fā)”的問題，但它們解決的問題完全不同，屬于兩個層級的體系。
簡單一句話總結：
- OpenSpec = 規(guī)范開發(fā)流程（Specification Driven Development）
- AI Skills = 為 AI Agent 提供可復用能力（Agent Capability Extension）
核心定位對比
| 維度 | OpenSpec | AI Skills |
|---|---|---|
| 本質 | 開發(fā)流程框架 | AI 能力擴展機制 |
| 作用 | 規(guī)范軟件開發(fā)流程 | 讓 AI 具備某種能力 |
| 解決問題 | AI 不理解需求上下文 | AI 不會做某件事情 |
| 作用層級 | 開發(fā)流程層 | 能力擴展層 |
| 主要對象 | 項目需求與規(guī)格 | AI Agent |
| 使用場景 | 讓 AI 深度參與軟件研發(fā) | 讓 AI 執(zhí)行特定的工具任務 |
三、AI 規(guī)格驅動工具：GitHub Spec Kit vs. Fission-AI OpenSpec
在“規(guī)格驅動開發(fā)（SDD）”領域，目前有兩個備受關注的開源利器，它們雖然目標一致，但設計哲學各有千秋：
- GitHub Spec Kit：由 GitHub 團隊推出，帶有濃厚的“企業(yè)級”基因。它強調嚴格的四階段驗證流（Specify → Plan → Tasks → Implement），并引入了獨特的“憲法文件（Constitution）”來約束 AI 的行為。它更像是嚴謹?shù)募軜嫀?，適合Greenfield 項目（從零開始的新項目）。
- Fission-AI OpenSpec：則更像是一位敏捷的實戰(zhàn)派。它主張“變革隔離（Change Isolation）”，為每一個小的功能變更創(chuàng)建獨立的目錄，避免上下文污染；同時它的工作流更加輕量、靈活，非常適合在Brownfield 項目（已有存量代碼的項目）中進行增量開發(fā)。
OpenSpec 的優(yōu)勢在于：只為新的 Change 建立規(guī)格。也就是說：
- 舊系統(tǒng) = 保持不動
- 新功能 = 用 Spec 管理
隨著時間推移，Spec 會逐漸積累，最終形成完整的系統(tǒng)知識庫。這就是 OpenSpec 的核心設計哲學。本文將重點介紹 Fission-AI OpenSpec，探索它如何通過簡潔的指令流，在現(xiàn)有代碼庫中釋放 AI 的最大潛力。
四、OpenSpec 快速入門
# Node.js >= 20.19.0（必須，用于支持最新的文件系統(tǒng) API）
npm install -g @fission-ai/openspec@latest
然后導航到你的項目目錄并初始化：
cd your-project
openspec init
執(zhí)行 openspec init 命令后，根據(jù)提示選擇你常用的 AI 工具（例如 Claude Code、Cursor、Antigravity 等），選擇完成后按回車確認，最后重啟 IDE 使配置生效。
五、OpenSpec 核心目錄結構
openspec/
├── config.yaml # 全局 CLI 配置文件
├── specs/ # 存放已同步的主規(guī)范文件
└── changes/ # 存放所有的變更（Changes）
├── archive/ # 已歸檔的變更目錄
└── add-order-list-page/ # 當前正在進行的變更（新增訂單列表頁面）
├── proposal.md # 變更提案（動機、變更內容、核心能力等）
├── design.md # 技術設計文檔（架構決策、風險等）
├── tasks.md # 任務清單（待辦事項列表）
└── specs/ # 該變更相關的增量規(guī)范（Delta Specs）
└── order-list-page/
└── spec.md # 訂單列表頁面的詳細功能規(guī)格
六、落地指南：業(yè)務需求如何轉化為 OpenSpec？
將現(xiàn)實中的業(yè)務需求翻譯成 AI 可理解的“規(guī)格”，是使用 OpenSpec 的關鍵所在。這不僅僅是把文字填進 Markdown，而是一次“需求工程”的提煉過程。
1. Change 拆分（Change Decomposition）
大需求不應畢其功于一役。為了讓 AI 的注意力保持集中，應當把大需求拆分為多個 Change，每個 Change 應遵循以下原則進行拆分：
- 單一能力原則：每個 Change 只解決一個核心業(yè)務點，避免“套餐式”更新導致邏輯耦合。
- 功能邊界清晰：明確定義“做什么”以及“不做什么”，防止 AI 在自動編碼時改動無關文件。
- 領域驅動隔離：按業(yè)務領域（如用戶、訂單、支付）劃分 Change 集合。因為 Change 最終會通過 Sync 機制合并到主規(guī)格庫，只有源頭 Change 的邊界清晰，才能保證最終匯總的 openspec/specs/ 知識庫不會變成一團亂麻。
2. 需求轉化核心步驟（The Transformation Flow）
在每個拆分好的 Change 中，需求轉化為代碼的核心工作流如下：
階段一：需求 → Proposal
第一步不是寫 Spec，而是寫 Proposal。Proposal 需要說明：
- 為什么要做這個功能
- 解決什么問題
- 影響哪些模塊
- 是否有替代方案
?? Proposal 的本質是：記錄架構決策。
階段二：Proposal → Design
Design 描述技術實現(xiàn)思路，例如：
- API 設計
- 數(shù)據(jù)結構
- 架構調整
- 風險分析
?? Design 解決的問題是：系統(tǒng)要怎么實現(xiàn)這個需求。
階段三：Design → Tasks
Tasks 將設計拆分為具體任務，例如：
- 新增導出 API
- 新增導出按鈕
- 新增文件下載邏輯
- 新增權限校驗
?? Tasks 是 AI 生成代碼的主要依據(jù)。
3. 規(guī)格顆粒度控制（Spec Granularity）
Specs 是開發(fā)者與 AI 之間的“契約”。顆粒度的把握直接影響代碼質量：
- 拒絕信息過載：不要在 Spec 中事無巨細地復述已有的代碼邏輯。AI 的長處是理解上下文，你應該只提供它無法通過直接閱讀源碼獲取的增量信息。
- 補充關鍵盲區(qū)：如果設計稿未出或接口文檔殘留，應在 Spec 中明確標注占位規(guī)則或 Mock 約定。
-
動態(tài)迭代優(yōu)化：OpenSpec 允許在開發(fā)過程中不斷修正 Spec。如果發(fā)現(xiàn) AI 理解有偏差，應在
changes/xxx/specs/下補充細節(jié)，然后再次執(zhí)行/opsx:apply進行增量修正。
七、工作流：從“標準”到“進階”
OpenSpec 提供了靈活的配置方案。通過 openspec config profile 命令，你可以在標準（Minimum）和全量（Full）工作流之間切換。
1. 標準工作流：追求極致效率 (Fast Track)
適合需求明確、邏輯簡單的任務。這是默認的“快車道”，只需三個關鍵動作即可完成閉環(huán)。
| 指令 | 核心作用 | 執(zhí)行時機 |
|---|---|---|
/opsx:propose |
一鍵初始化。自動創(chuàng)建目錄、編寫提案、規(guī)格、設計及任務列表。 | 明確需求，準備開始編碼。 |
/opsx:apply |
自動化執(zhí)行。AI 會按任務列表逐一修改代碼并運行測試。 | 規(guī)劃文件生成后，開始實現(xiàn)。 |
/opsx:archive |
閉環(huán)收尾。歸檔變更并將本次邏輯同步至主規(guī)格庫。 | 代碼驗證無誤，合并成果。 |
/opsx:explore |
頭腦風暴。不產(chǎn)生文件，僅與 AI 討論方案。 | 可選。正式啟動前的設計調研。 |
2. 精細工作流：深度掌控質量 (Control Mode)
對于涉及核心業(yè)務邏輯、跨模塊修改或高風險任務，建議開啟全量模式。
| 擴展指令 | 核心作用 |
|---|---|
/opsx:new |
手動起手。僅創(chuàng)建變更目錄，不生成具體文檔，由開發(fā)手動控制節(jié)奏。 |
/opsx:continue |
步進式生成。一次只生成一個規(guī)劃件（如提案），等人類評審修改后再進行下一步。 |
/opsx:ff |
補全快進。在修改了部分文檔（如修改了提案）后，讓 AI 補完剩下的規(guī)格和任務。 |
/opsx:verify |
二次校對。在歸檔前對照規(guī)格書（Specs）檢查實現(xiàn)是否有錯漏。 |
/opsx:sync |
增量同步。在長周期任務中，隨時將已確定的邏輯同步到主庫，以便其他變更參考。 |
/opsx:onboard |
新手引導。帶你用一個微型任務走一遍完整流程的交互式教程。 |
八、進階：規(guī)格的“自我生長”與迭代
很多開發(fā)者關心：“下次迭代已存在的功能時，AI 會參考之前的設計嗎？”
答案是：會，但這依賴于 OpenSpec 的 Sync（同步）機制。
-
物理傳承而非記憶：
/opsx:sync會將當前 Change 中的 Delta Specs 合并到 openspec/specs/ 主規(guī)格庫，使后續(xù)變更可以參考這些已有規(guī)格。 -
增量設計：再次迭代同一功能時，AI 會先掃描主規(guī)格庫，識別出已有的“項目憲法”，在新的方案中明確說明：“基于現(xiàn)有
order-list-page/spec.md，我們將新增...”。 - 價值積累：你每一次歸檔，都是在給 AI “喂”項目知識。隨著項目迭代，AI 會越來越懂你的業(yè)務邏輯和設計規(guī)范。
九、核心避坑與進階技巧
1. 規(guī)范同步：別讓 AI 變成“斷網(wǎng)式”協(xié)作
關鍵提醒：在執(zhí)行
/opsx:archive時，并非所有 AI 工具都會自動觸發(fā)增量規(guī)范（Delta Spec）的同步。為了確保你的架構決策能被永久記錄并傳承給下一次迭代，強烈建議在歸檔前手動執(zhí)行
/opsx:sync。
2. 精準選擇：/opsx:propose vs. /opsx:ff
兩者分別對應了開發(fā)者對 AI 信任度的兩種狀態(tài)：
| 模式 | 指令 | 邏輯比喻 | 適用場景 |
|---|---|---|---|
| 全自動 | /opsx:propose |
直線沖刺：從 0 到 100，一氣呵成。 | 需求明確、路徑標準的任務（如：增加一個工具函數(shù)）。 |
| 半自動 | /opsx:ff |
中場加油：在 N 處停下微調，再快進到 100。 | 邏輯復雜、需要人類介入設計決策的任務（如：重構核心業(yè)務邏輯）。 |
- Propose 細節(jié)：AI 會從創(chuàng)建文件夾、寫提案到任務拆解全部包辦。
-
FF 細節(jié)：先執(zhí)行
/opsx:new創(chuàng)建空變更，接著運行/opsx:continue讓 AI 生成初步的proposal.md。在你手動修改并確認核心方案無誤后，再用/opsx:ff讓 AI 補完剩下的規(guī)格和技術實現(xiàn)細節(jié)。
3. 多任務管理與靈活性
- 多任務并存：OpenSpec 支持同時開啟多個變更（Change），但同一時刻只有一個“當前激活”狀態(tài)。
-
靈活切換：想新增任務用
/opsx:new；想續(xù)接之前的任務，直接輸入/opsx:continue<change-name>。 -
動態(tài)調整：即使已經(jīng)進入編碼階段，你依然可以修改任何規(guī)劃件（如
tasks.md），修改完成后再次運行/opsx:apply，AI 會自動識別差異并更新實現(xiàn)。
十、結語
在這個 AI 編程效率百倍提升的時代，比“寫得快”更重要的，是“控得住”。OpenSpec 提供的規(guī)格驅動流程，正是我們從“AI 編碼”邁向“AI 研發(fā)管理”的關鍵一環(huán)。本文內容僅代表個人觀點，不足之處，敬請諒解。
