OpenSpec最佳實踐：讓AI按規範寫代碼，不再憑感覺瞎編
整理版優先睇
OpenSpec最佳實踐：用規範對齊AI，避免亂改無謂代碼
呢篇文章來自Fission-AI團隊，介紹OpenSpec呢個開源SDD（Spec-Driven Development）框架。作者想解決嘅問題係：AI寫代碼時成日「估」開發者意圖，改咗唔應該改嘅檔案，或者做多咗你冇要求嘅功能。核心結論係：喺AI寫代碼之前，先用規範對齊「做乜」同「點做」，就可以大幅減少呢啲問題。OpenSpec嘅流程係：propose（描述變更）→ apply（按規範實現）→ archive（歸檔更新真相源）。中間多咗「對齊」一步，令你可以喺AI寫1000行代碼之前就發現方向錯咗。
文章重點提出咗七條最佳實踐，涵蓋proposal嘅out of scope、delta規範增量修改、用GIVEN/WHEN/THEN寫可測試場景、按變更複雜度揀流程、explore先行討論、verify三維度驗證、同自定義Schema。呢啲實踐嘅核心都係圍繞「控制範圍、保持增量、驗證一致」。OpenSpec同Spec Kit、Kiro嘅比較亦顯示，佢最適合棕地項目同需要並行開發嘅團隊。
最後作者提醒三個最常見嘅坑：小改動都行完整流程、proposal寫得太模糊、唔跑verify就archive。總括嚟講，OpenSpec唔係取代AI工具，而係喺AI前面加一層規範對齊，令AI唔再憑感覺亂編。
- 結論：規範先行係控制AI行為嘅關鍵，out of scope比in scope更重要，寫清楚「唔做乜」可以有效防止AI亂改。
- 方法：用delta規範增量修改，只寫變化嘅部分，避免重寫全部規範，同時支援並行開發同歷史追溯。
- 差異：OpenSpec輕量、支援棕地項目、天然並行，同Spec Kit嘅完整流程、Kiro鎖定AWS生態相比，更適合需要靈活度嘅團隊。
- 啟發：explore先行，討論清楚技術方案先propose，可以大幅提升規範質量，減少後續修改。
- 可行動點：每次apply之後、archive之前一定要跑verify，從完整性、正確性、一致性三個維度檢查，確保實現同規範一致。
問題與OpenSpec核心理念
你有冇試過叫AI加個功能，佢改咗5個檔案，其中3個你根本冇要求改？或者每次新對話，AI忘光之前嘅決策，由零開始估你嘅意圖？呢啲問題唔係AI能力唔夠，而係你冇畀佢規範。
OpenSpec係Fission-AI開發嘅開源SDD框架，核心好簡單：喺AI寫代碼之前，先對齊「做乜」同「點做」。目前GitHub上好受關注，支援Claude Code、Cursor、Copilot、Codex等25+工具。
基礎工作流：propose → apply → archive
OpenSpec有兩個核心概念：specs/係系統當前行為嘅規範，係真相源；changes/</highlight-inline>係進行中嘅變更，每個變更一個文件夾，可以並行推進。
- 1 第1步 propose：用 /opsx:propose add-dark-mode 呢類指令，AI會生成四個產物：proposal.md（點解做、範圍）、delta specs（系統行為變化）、design.md（技術方案）、tasks.md（具體步驟）。你審核呢啲文檔，確認「啱，呢個就係我要嘅」。
- 2 第2步 apply：/opsx:apply，AI按tasks.md逐項執行，每完成一項打勾。佢唔會跑偏，唔會多做，唔會「好心」幫你重構你冇要求嘅嘢。
- 3 第3步 archive：/opsx:archive，將delta specs合併到主規範（更新真相源），將變更文件夾移到 archive/。規範隨項目增長，每次archive都令主規範更完整。
四個產物職責明確：proposal.md回答「點解做、範圍係乜」；delta specs回答「系統行為有咩變化」；design.md講技術點做、架構決策；tasks.md係具體可勾選嘅任務清單。
七條最佳實踐：控制AI嘅關鍵
實踐1：proposal.md嘅「唔做乜」比「做乜」更重要
大多數人寫proposal只關注範圍，唔記得寫排除範圍。例如你只係想加深色模式顏色token，但AI可能順手重構成個CSS架構。正確做法係明確寫出out of scope，例如「唔重構現有CSS架構」、「唔改變組件內部結構」。呢個係控制AI行為最有效嘅方式。
實踐2：Delta規範用增量唔用重寫
OpenSpec最核心嘅設計係delta規範，只寫變化嘅部分，唔係重寫成個規範。咁樣可以做到並行唔衝突、審核更快、歷史可追溯。每個變更嘅delta都保留住，睇到系統點樣一步步演化。
實踐4：小變更用核心流程，大變更用擴展流程
OpenSpec有兩種profile：核心流程（core）適合大多數場景；擴展流程（workflows）適合需要更多控制嘅情況，例如逐個審核產物、手動控制節奏。關鍵判斷：如果改一行CSS就搞得掂，唔好用OpenSpec。佢嘅價值喺對齊，成本只有喺變更夠複雜時先值得。
實踐5：explore先行，propose在後
好多新手一拎到需求就跑去 /opsx:propose，結果生成嘅規範方向偏咗。正確做法係先用/opsx:explore同AI討論技術方案，分析現有代碼庫、對比唔同方案、討論利弊，討論清楚先propose。咁樣生成嘅規範質量會高好多。
實踐6：verify驗證三維度
/opsx:verify 從完整性、正確性、一致性三個維度檢查。報告分CRITICAL、WARNING、SUGGESTION三級。唔好淨係睇tasks.md啲勾打曬冇，一定要跑verify，因為AI可能標記任務完成但實際實現同規範唔一致。
實踐7：自定義Schema適配工作流
OpenSpec預設產物流係proposal→specs→design→tasks→implement，但如果團隊需要額外步驟例如「調研階段」，可以自定義Schema。Schema令你可以按需調整，唔使被工具綁死。
工具對比與常見陷阱
OpenSpec同Spec Kit、Kiro三個主流SDD工具嘅比較：OpenSpec輕量、流暢、迭代優先，天然支援並行開發；Spec Kit完整、有治理、流程嚴格；Kiro強大但鎖定IDE。建議：喺已有項目上加功能用OpenSpec（delta規範適合棕地項目），新項目從零開始可以用Spec Kit，只用AWS生態就用Kiro。
# 安裝（需要Node.js 20.19.0+）
npm install -g @fission-ai/openspec@latest
# 在項目中初始化
cd your-project
openspec init
# 選擇你用的AI工具（Claude Code、Cursor等）
# 更新AI指導文件和slash命令
openspec update
# 開始第一個變更
/opsx:propose add-user-profile
# 審核後應用
/opsx:apply
# 驗證
/opsx:verify
# 歸檔
/opsx:archive三個最常見嘅坑
- 坑1：小改動都行完整流程。改一行CSS、修一個typo，唔需要propose→apply→archive。如果AI一次對話就準確完成，直接改代碼。
- 坑2：proposal寫得太模糊。例如「加個用戶管理功能」，AI會生成一個完整用戶系統——註冊、登錄、權限、頭像、設置，遠超你預期。修復方法：明確scope同out of scope，用GIVEN/WHEN/THEN寫具體場景。
- 坑3：唔跑verify就archive。AI可能標記任務完成但實現同規範不一致。每次apply之後、archive之前，一定要跑一次verify。
