openspec 最佳實戰：不改 OpenSpec 源碼，只改一段配置，代碼質量從不可控到 80 分（修正版）
整理版優先睇
任務粒度係控制 AI 代碼質量的最大槓桿，只改一段配置就能覆蓋 80% 嘅質量問題
呢篇文章係術哥喺「術哥無界」系列嘅一篇實戰文檔，佢專注 AI 編程同工具鏈最佳實踐。作者想解決嘅問題係：點樣唔改 OpenSpec 源碼，就用最少改動大幅提升 AI 生成代碼嘅質量。佢透過 3 輪 Lab 實測，發現 5 個質量改進方向中性價比最高嘅係「任務粒度控制」——只要喺 OpenSpec 嘅 tasks instruction 入面加一段嚴格嘅模板同禁止事項，就可以令 AI 生成嘅每個 step 拆到 2-5 分鐘粒度，而且附完整代碼同命令。整體結論係：源頭控制比事後審查有效得多，20% 嘅改動可以帶嚟 80% 嘅質量提升。
文章詳細介紹咗三步配置法：第一，創建 config.yaml 提供全局上下文同規則；第二，fork schema 並升級 tasks 嘅 instruction，加入嚴格格式同禁止事項；第三，插入 review 工件做結構化安全網。然後佢畫咗完整嘅 6 個 Phase 日常工作流，由 explore 到 archive，並指出三層防線嘅設計哲學——第一層做重、第二層做輕、第三層做快。最後畀咗幾個實戰坑點同技巧，例如 rules key 要匹配 artifact id、complex change 要拆細等。
- 任務粒度係控制 AI 代碼質量最大嘅槓桿，只改一段 instruction 就能覆蓋 80% 嘅質量問題，性價比遠超其他方向。
- 粗粒度任務畀 AI 自由發揮空間，導致夾帶私貨；細粒度任務（2-5 分鐘 step + 完整代碼）壓縮模糊空間，AI 只能照單執行。
- 三步配置：創建 config.yaml（上下文+規則）→ fork schema 升級 tasks instruction（嚴格模板+禁止事項）→ 插入 review 工件（結構化安全網）。
- 日常開發 6 個 Phase：explore（需求澄清）→ propose（生成工件）→ 人工檢查 review → apply（執行 tasks）→ verify（一致性驗證）→ archive（歸檔）。
- 三層防線設計：源頭控制佔 80% 質量，過程檢查（review+verify）做安全網，人工兜底只花 1-2 分鐘睇完成狀態。
OpenSpec v1.3.1 官方文檔
Fission-AI/OpenSpec 項目
Superpowers writing-plans skill 設計文檔
用於參考任務粒度設計公開資料
問題根源：任務太粗，AI 就會自由發揮
3 輪 Lab 跑落，有個發現反覆出現：AI 喺 apply 階段會夾帶私貨。例如 Lab 1 裸跑嗰陣，AI 從 change name 推斷曬全部需求，結果 tasks.md 出現咗個冇人提過嘅需求——ISO 8601 時間戳格式變更，仲要係 breaking change。
問題根因唔係 AI 能力，而係畀佢嘅任務描述太粗。粗粒度任務例如「實現用戶註冊接口」，AI 就會自行猜測要做乜；細粒度任務包括埋「寫失敗測試」「運行測試」「寫最小實現」「確認通過」每個 step 嘅完整代碼同命令，AI 就冇發揮空間。
你畀嘅指令有模糊空間，AI 就會填滿呢個空間
2/8 法則：任務粒度先係嗰個 20%
上篇文章驗證咗 5 個升級方向，從性價比排序會完全唔同。升級 tasks instruction 只需要改一個字段嘅一段文字，唔改源碼、唔裝工具、唔調整 DAG，效果係令 AI 喺生成 tasks.md 階段就將任務拆到 2-5 分鐘粒度。20% 嘅改動，覆蓋 80% 嘅質量提升。
20% 嘅改動，覆蓋 80% 嘅質量提升
加 Code Review 或驗證工作流，效果大概得 20% 額外提升
其他方向如加代碼審查、開啟 expanded workflow、寫更細嘅 rules，投入產出比都遠低於任務粒度控制。Rules 係文本約束，AI 有時跟有時唔跟；加 review 工件需要 fork schema、寫模板、調依賴鏈，配置成本高。
三步配置：從不可控到 80 分
三步配置好簡單：畀 AI 足夠精確嘅上下文 → 畀 AI 足夠嚴格嘅執行指令 → 插一道自動檢查。每步只改一個文件。第一步創建 config.yaml，提供全局上下文同按工件分組嘅規則。
schema: with-review
context: |
技術棧：TypeScript, Express, Vitest
測試命令：npx vitest run
所有新功能必須遵循 TDD 節奏——先寫失敗測試，再寫實現代碼
rules:
specs:
- 每個數據字段嘅變更，必須覆蓋 null、空值、越界三種異常場景
- Scenario 必須使用 #### 四級標題，否則歸檔時唔生效
design:
- 涉及數據庫 migration 嘅設計，必須包含回滾方案
tasks:
- 每個 task 必須包含完整嘅測試代碼同實現代碼
- 每組 task 嘅第一步必須係寫失敗測試，最後一步必須係驗證通過
review:
- 重點檢查 tasks.md 嘅粒度係咪達到 2-5 分鐘一個 step
- 檢查係咪有佔位符（TBD、TODO、implement later）第二步係核心改動：fork 現有 schema，然後將 tasks artifact 嘅 instruction 替換成嚴格模板。每個 task 必須遵循「涉及文件→寫失敗測試→運行確認失敗→寫最小實現→運行確認通過→提交」嘅 5 步格式，並附完整代碼同命令。
禁止事項：TBD、TODO、implement later、『添加適當嘅錯誤處理』、『為以上代碼寫測試』
第三步插入 review 工件，作為 design 同 tasks 之間嘅閘門。review 從五個維度審查：邊界條件、回滾方案、測試覆蓋、向後兼容、任務粒度。tasks 嘅 requires 改為 [review]，確保冇 review 就唔會開始生成 tasks。
review 工件係閘門：冇 review，tasks 就唔會開始生成
不過 review 係自己審自己，結論偏寬鬆。對質量有硬性要求嘅項目，review 適合做初審，唔適合做終審。
完整工作流：6 個 Phase 嘅日常開發
配置係一次性，日常開發就係反覆跑 6 個 Phase。每個 Phase 對應一條 OpenSpec 命令，AI 做完一步你確認一步。Phase 1 係需求澄清（explore），可選但推薦，喺 propose 之前先諗清楚模糊地帶。
Explore 階段嘅需求澄清係產出質量提升嘅主要來源
Phase 2 一鍵生成工件（propose），用 with-review schema 會一次產出 proposal.md、specs/、design.md、review.md、tasks.md。關鍵係 tasks.md 因為 instruction 升級而粒度足夠細。Phase 3 人工檢查（1-2 分鐘），重點睇 review.md 嘅任務粒度狀態同關鍵建議。
人工檢查只需掃一眼 review.md，重點係任務粒度維度同 tasks.md 建議
Phase 4 按任務執行（apply），AI 照住 tasks.md 逐個實現。Phase 5 一致性驗證（verify），檢查實現係咪 match spec 意圖，但只係文本檢查，唔係運行驗證。Phase 6 歸檔（archive），歸檔前掃一眼所有 task 嘅完成狀態。
- Phase 1：explore — 需求澄清，決策矩陣幫手理清思路
- Phase 2：propose — 一鍵生成 5 個工件
- Phase 3：人工檢查 review — 1-2 分鐘掃讀
- Phase 4：apply — 按 tasks.md 逐個執行
- Phase 5：verify — 文本一致性檢查
- Phase 6：archive — 歸檔前確認完成狀態
verify 只做文本一致性檢查，代碼能唔能跑要靠測試框架同 CI
三層防線：80% 靠源頭控制
三步配置搭好之後，日常開發有三層防線，但重要性差好遠。第一層係源頭控制，即係 tasks instruction 升級，貢獻 80% 嘅質量。問題喺源頭消滅，後面防線只需處理遺漏。
第二層係過程檢查，包括 review 工件同 verify 命令，處理邊界條件遺漏、回滾方案缺失、spec 同代碼不一致等問題。第三層係 archive 前嘅人工檢查，1-2 分鐘掃一眼完成狀態，兜埋邊界情況。
rules 嘅 key 必須同 artifact id 完全一致，寫錯就靜默失效
實戰坑點仲有：openspec schema fork 係 experimental，升級要留意 changelog；context 窗口壓力大時先 /clear 再 apply；複雜變更拆做多個獨立 change，每個只做一件事。技巧方面，propose 唔一定會問需求，想控制需求就先跑 explore；工件係 Markdown 可以手動改，tasks 粒度唔夠直接編輯就得。
⚠️ 修正重發說明：呢篇文章第一次發嘅時候因為 code block 嵌套搞到排版亂曬，已經整返好，內容冇變過。
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 108 篇，AI 編程最佳實戰「2026」系列第 33
大家好，歡迎嚟到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一個專注於 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫嘅技術實踐者同開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
圖 1：任務粒度——代碼質量最大嘅槓桿
說明：呢篇文嘅內容係根據 OpenSpec（Fission-AI/OpenSpec）v1.3.1 官方文檔、筆者之前兩篇文章（《OpenSpec 最佳實戰：4 步覆盤 + 5 項升級》、《3 輪實測驗證 5 個質量升級方向》）嘅實測數據，以及 Superpowers writing-plans skill 嘅公開設計文檔分析整理出嚟。文中嘅配置模板同參數建議只係參考，實際效果請以你嘅業務數據同環境測試結果為準。如果有實際使用經驗，歡迎喺留言區分享交流。
上篇文章用 3 輪 Lab 驗證咗 5 個質量升級方向。結論表貼出嚟，答案一眼就明：5 個方向都有效，但性價比差好遠。
有啲改動要 fork schema、插入新工件、調整依賴鏈，搞一大輪質量確係好咗。但有個方向令我好意外——只係改一段配置文字，唔改 OpenSpec 源碼，唔裝外部工具，效果反而 cover 咗 80% 嘅質量問題。
呢個方向就係：任務粒度控制。
今日呢篇係「OpenSpec 項目實戰」系列第 1 期，定位係方法論篇。先講清楚點解任務粒度係嗰個 20%，再講三步配置點樣做，最後畫一張完整嘅日常工作流程全景圖。由第 2 期開始，會用一個真實項目「shuge AI Toolbox」，用呢套方法論由零開始搭建，逐期展開。
1. 問題根源：任務太粗疏，AI 就會自由發揮
3 輪 Lab 跑完，有一個發現成日出現：AI 喺 apply 階段夾帶私貨。
Lab 1 就咁跑嘅時候，AI 由 todo-priority 呢個 change name 推斷曬全部需求。結果 tasks.md 入面出現咗一個冇人提過嘅需求——ISO 8601 時間戳格式變更。呢個係 breaking change，但 propose 階段根本冇人要求做呢件事。
AI 做咗啲咩？佢自行解釋咗需求，然後自行決定咗實現範圍。
呢個問題嘅根本原因唔係 AI 嘅能力，而係我哋畀佢嘅任務描述太粗疏。睇一個對比就明。
粗粒度任務係咁樣：
- [ ] 1.1 實現用戶註冊接口
- [ ] 1.2 添加輸入校驗
- [ ] 1.3 處理異常情況
三個 task，每個都係一句說話描述。AI 收到呢種 task 會做啲咩？佢會猜——註冊接口使唔使發 email？驗證規則是乜？異常情況具體指邊啲？估完就自己寫，寫完你一睇，唔啱。
細粒度任務係咁樣：
### 任務 1：郵箱格式校驗
- [ ] 第 1 步：寫失敗測試
```typescript
test('無效郵箱格式返回 400', () => {
const result = register({ email: 'abc' });
expect(result.status).toBe(400);
});
```
- [ ] 第 2 步：運行測試——確認失敗
命令：`npx vitest run tests/auth.test.ts`
預期：FAIL — function is not defined
- [ ] 第 3 步：寫最小實現
（完整代碼）
- [ ] 第 4 步：運行測試——確認通過
命令：`npx vitest run tests/auth.test.ts`
預期：PASS
每個 step 附咗完整代碼、運行命令、預期輸出。AI 收到呢種 task 仲可以發揮啲咩？跟住做就得啦。
圖 2：任務粒度對比——粗任務留咗發揮空間畀 AI，細任務將空間壓縮到零
因果鏈好清楚：
任務粗 → AI 自行解釋 → 自行決定範圍 → 夾帶私貨
任務細 + 附代碼 → AI 只需執行 → 沒有解釋空間 → 夾不了私貨
講到底，呢個唔係 AI 能力嘅問題，而係指令質量嘅問題。你畀嘅指令有模糊空間，AI 就會填滿呢個空間。你將模糊空間壓縮到零，AI 就只能照單執行。
2. 2/8 法則：任務粒度先係嗰個 20%
上篇文章驗證咗 5 個升級方向。如果由性價比角度重新排序，畫面會完全唔同。
| 升級 tasks 嘅 instruction | 極高 | ||
3 輪實測嘅結論支持呢個排序：
Lab 2 加咗 Rules + Explore，產出質量主要來自 Explore 嘅需求澄清，rules 本身嘅效果好難單獨量化。點解？因為 rules 係文字約束，AI 有時跟有時唔跟，你冇辦法保證每次都生效。
Lab 3 自定義 Schema 插入 Review 工件，tasks.md 由 19 個增加到 22 個，新增嘅 3 個 task 都有明確嘅 review 建議來源。但成條鏈路要 fork schema、寫 review 模板、調整依賴關係，配置成本唔低。
而升級 tasks 嘅 instruction 呢？只需要改一個字段入面嘅一段文字。唔改 OpenSpec 源碼，唔裝外部工具，唔調整 DAG 依賴鏈。效果係令 AI 喺生成 tasks.md 嘅階段就將任務拆到 2-5 分鐘粒度，每個 step 附完整代碼。
20% 嘅改動，cover 咗 80% 嘅質量提升。 呢個就係 2/8 法則。
餘下嘅 80% 改動（審查 + 驗證 + CI）可以帶嚟幾多額外提升？大約 20%。佢哋係安全網，唔係主力。
咁呢 20% 嘅改動具體點樣做？
3. 三步配置：由不可控到 80 分
三步配置嘅思路好簡單：畀 AI 夠精確嘅上下文 → 畀 AI 夠嚴格嘅執行指令 → 插一道自動檢查。每步只改一個檔案。
第 1 步：建立 config.yaml（上下文 + 規則）
呢個檔案畀 AI 提供全局上下文同按工件分組嘅規則。放喺項目根目錄嘅 openspec/config.yaml：
schema: with-review
context:|
技術棧：TypeScript, Express, Vitest
測試命令：npx vitest run
所有新功能必須遵循 TDD 節奏——先寫失敗測試，再寫實現代碼
rules:
specs:
-每個數據字段的變更，必須覆蓋null、空值、越界三種異常場景
-Scenario必須使用#### 四級標題，否則歸檔時不生效
design:
-涉及數據庫migration的設計，必須包含回滾方案
tasks:
-每個task必須包含完整的測試代碼和實現代碼
-每組task的第一步必須是寫失敗測試，最後一步必須是驗證通過
review:
-重點檢查tasks.md的粒度是否達到2-5分鐘一個step
-檢查是否有佔位符（TBD、TODO、implementlater）
幾個要點：
context字段注入所有工件，話畀 AI 知你嘅技術棧、測試指令、編碼規範rules按 artifact ID 分組，key 一定要同 schema 入面嘅 artifact id 完全一致rules 喺 prompt 中以約束條件嘅形式傳遞，相當於畀 AI 畫紅線
完整配置文件見附件：
articles/attachments/config.yaml
第 2 步：Fork Schema，升級 tasks 嘅 instruction
這是核心改動。
先 fork 一個現有嘅 schema：
openspec schema fork spec-driven with-review
注意：
openspec schema fork目前標記為 experimental，之後嘅版本可能有變化。
然後在 openspec/schemas/with-review/schema.yaml 入面，揾到 id: tasks 嘅 artifact，將佢嘅 instruction 字段換成下面呢段：
instruction: |
創建細粒度的實現計劃。每個任務的工作量應在 2-5 分鐘之間。
每個任務必須遵循以下格式：
-涉及文件（精確路徑）
-第1步：寫失敗測試（附完整測試代碼）
-第2步：運行測試——確認失敗（附命令+預期輸出）
-第3步：寫最小實現（附完整實現代碼）
-第4步：運行測試——確認通過（附命令+預期輸出）
-第5步：提交（附git命令）
禁止事項（出現即視為計劃不合格）：
-TBD、TODO、implementlater
-「添加適當的錯誤處理」（必須寫出具體代碼）
-「為以上代碼寫測試」（必須寫出具體測試代碼）
-只描述做什麼但不展示怎麼做
呢段 instruction 做咗兩件事：
第一，畀 AI 一個嚴格嘅任務模板。 每個 task 一定要包含 5 個 step，由寫失敗測試到提交，每步附完整代碼同指令。AI 冇發揮空間。
第二，列咗一堆禁止事項。 呢啲都係 AI 常見嘅偷懶行為——寫個 TBD 等你填，講一句「添加適當嘅錯誤處理」就算完成。而家出現呢啲就直接判定計劃唔合格。
完整 instruction 內容見附件：
articles/attachments/tasks-instruction.yaml
第 3 步：插入 review 工件（配套措施）
喺前兩步嘅基礎上，畀 schema 加一個 review 工件，放喺 design 同 tasks 之間：
# schema.yaml 中的新增工件
-id:review
generates:review.md
template:review.md
description:五維審查-檢查設計方案和Spec的完整性
instruction:|
從五個維度審查所有工件的完整性和質量。
審查維度：
1. 邊界條件 2. 回滾方案 3. 測試覆蓋
4. 向後兼容 5. 任務粒度（最重要）
requires:[proposal,specs,design]
然後將 tasks 嘅 requires 從 [specs, design] 改為 [review]。咁樣依賴鏈變成：
proposal → specs → design → review → tasks → APPLY
review 工件係個閘門：冇 review，tasks 就唔會開始生成。審查結論入面會明確標註每個維度嘅狀態（✅ 通過 / ⚠️ 警告 / ❌ 失敗），tasks.md 會參考 review 嘅建議嚟決定拆分方向。
坦白講，呢步嘅效果比前兩步温和。3 輪實測發現，自己審自己嘅審查結論偏寬鬆——4 Pass + 1 Warning 睇落唔錯，但換成人類審查可能更嚴格。不過作為一道結構化嘅安全網，佢都仲有價值。
完整 review instruction 見附件：
articles/attachments/review-instruction.yamlreview 模板檔案見附件：articles/attachments/review-template.md
圖 3：三步配置——由上下文注入到指令升級再到自動審查
三步做完，日常開發嘅工作流係點樣？
4. 完整工作流：6 個 Phase 嘅日常開發
配置係一次過嘅，日常開發就不斷跑 6 個 Phase。每個 Phase 對應一條 OpenSpec 指令，AI 做完一步你就確認一步。
Phase 1：需求澄清
/opsx:explore
可選但推薦。喺 propose 之前，先將模糊地帶諗清楚：字段類型點樣揀、邊界條件有邊啲、遷移策略係乜。Explore 會畫出決策矩陣幫你理清思路。
3 輪實測嘅結論係：Explore 階段嘅需求澄清，係產出質量提升嘅主要來源。Lab 2 嘅 rules 本身效果唔係咁容易量化，但 Explore + propose 嘅組合比單獨 propose 可靠得多——需求係你講嘅，唔係 AI 估嘅。
Phase 2：一鍵生成工件
/opsx:propose
propose 內部會自動建立 change 目錄，然後按依賴順序生成全部工件。用 with-review schema 嘅話，一次產出 5 個檔案：proposal.md、specs/、design.md、review.md、tasks.md。
關鍵係 tasks.md——因為我哋升級咗 instruction，呢度嘅每個 task 都係 2-5 分鐘粒度、附完整代碼同指令嘅。
Phase 3：人工檢查（1-2 分鐘）
呢一步只需要睇一睇 review.md。重點睇兩個地方：
任務粒度嗰個維度嘅狀態：係 ✅ 定係 ⚠️？ 整體評估入面對 tasks.md 嘅關鍵建議
如果 review 話 tasks.md 粒度唔夠或者有佔位符，手動改一改 tasks.md 再繼續。OpenSpec 嘅工件都係 Markdown 檔案，直接編輯就得。
Phase 4：按任務執行
/opsx:apply
AI 讀取所有工件之後，按 tasks.md 入面嘅順序逐個實現。因為每個 step 都有完整代碼同指令，AI 只需要跟住做——冇發揮空間。
Phase 5：一致性驗證（安全網）
/opsx:verify
注意：verify 需要 expanded workflow 先用得。
verify 檢查實現係咪匹配 spec 嘅意圖。本質係文字層面嘅一致性檢查，唔係運行驗證。代碼跑唔跑得掂，仲要靠測試框架同 CI。但作為一道安全網，佢可以發現「spec 入面寫咗要做 A，代碼入面做咗 B」呢類問題。
你喺項目入面用過類似嘅 6 步工作流嗎？有冇邊個 Phase 你覺得可以慳返？歡迎喺留言區傾下。
Phase 6：歸檔
/opsx:archive
將成個 change 目錄歸檔。歸檔前建議睇一睇所有 task 嘅完成狀態，確認冇遺漏。
5. 三層防線：唔係所有防線都一樣重要
三步配置整好之後，日常開發入面其實有三層防線喺度運作。但佢哋嘅重要性唔同級數。
圖 4：三層防線——80% 嘅質量來自源頭控制
第一層：源頭控制（tasks instruction 升級）→ 貢獻 80% 嘅質量
呢個係成篇文章嘅核心。透過升級 instruction，令 AI 喺生成 tasks.md 嘅時候就將每個 step 拆到 2-5 分鐘、附上完整代碼。問題喺源頭就已經消滅咗，後面嘅防線只需要處理遺漏。
第二層：過程檢查（review + verify）→ 安全網
review 工件喺 design 同 tasks 之間插入一道結構化審查。verify 喺 apply 之後做一致性檢查。呢兩道防線處理嘅係第一層漏咗嘅問題——邊界條件遺漏、回滾方案缺失、spec 同代碼不一致。
第三層：收尾確認（archive 前嘅人工檢查）→ 兜底
睇一睇 review.md 嘅結論同 tasks.md 嘅完成狀態，1-2 分鐘嘅事。呢個係人嘅防線，處理前兩層冇 cover 到嘅邊界情況。
三層防線嘅設計哲學：第一層做重，第二層做輕，第三層做快。 唔好嘗試喺每一層都做 100% 嘅檢查——嗰係喺每個環節都投入 80% 嘅精力，換嚟 20% 嘅邊際提升。
6. 實戰注意事項
坑點同技巧都係 3 輪 Lab 入面踩過嘅，每條一句說話。
坑點：
rules 嘅 key 一定要同 artifact id 完全一致。寫成 task而不是tasks，規則就會靜默失效，唔會報錯。openspec schema fork目前係 experimental 功能，之後嘅版本指令格式可能變，升級嘅時候留意 changelog。verify 唔做運行驗證，只做文字一致性檢查。代碼跑唔跑得掂，要靠測試框架。 review 係自己審自己，結論偏寬鬆。對質量有硬性要求嘅項目，review 適合初審，唔適合終審。 context 窗口壓力。apply 階段 AI 需要同時持有所有工件資訊，複雜變更嘅時候建議先 /clear再 apply。
技巧：
複雜變更（5 個檔案以上）拆成多個獨立 change，每個只做一件事。上下文壓力細，AI 冇咁容易遺忘。 propose 唔一定會問需求——change name 夠清晰時 AI 可能 skip 咗確認直接生成。想控制需求就先跑一次 Explore。 工件都係 Markdown 檔案，隨時可以手動改。propose 生成嘅 tasks 粒度唔夠？直接編輯 tasks.md，唔使重新跑 propose。 instruction 入面多寫「禁止事項」比多寫「建議事項」更有效。AI 對否定約束嘅遵循度高過模糊嘅正面指導。
下一期預告
呢篇方法論講完咗點解任務粒度係嗰個 20%，三步配置點樣做，日常工作流係點樣。
第 2 期開始實戰。我會用呢套方法論，由零開始搭建一個真實項目——shuge AI Toolbox。第 2 期嘅內容：
用 Explore 澄清項目需求，確定 MVP 範圍 執行 propose 生成 5 個工件，逐個檢查產出質量 重點睇 tasks.md 嘅粒度係咪真係達到 2-5 分鐘一個 step
如果你都想跟住做，建議先將三步配置跑通：建立 config.yaml、fork schema、升級 instruction。具體配置文件下一期會放喺公開嘅代碼倉庫作為附件，讀者可以直接拎嚟改。
系列持續更新中，關注唔會迷路。
好啦，多謝你睇我嘅文章，如果鍾意可以點讚轉發畀需要嘅朋友，我哋下一期再見！敬請期待！
掃碼關注，獲取更多 AI 工具嘅實戰經驗同最佳實踐。唔好錯過每一篇乾貨！
⚠️ 修正重發說明：本文首發版因代碼塊嵌套導致排版錯亂，已修復，內容無變動。
🚩 2026 年「術哥無界」系列實戰文檔 X 篇原創計劃 第 108 篇，AI 編程最佳實戰「2026」系列第 33
大家好，歡迎來到 術哥無界 | ShugeX ｜ 運維有術。
我是術哥，一名專注於 AI 編程、AI 智能體、Agent Skills、MCP、雲原生、AIOps、Milvus 向量數據庫的技術實踐者與開源佈道者！
Talk is cheap, let's explore。無界探索，有術而行。
圖 1：任務粒度——代碼質量最大的槓桿
說明：本文內容基於 OpenSpec（Fission-AI/OpenSpec）v1.3.1 官方文檔、筆者前兩篇文章（《OpenSpec 最佳實戰：4 步覆盤 + 5 項升級》、《3 輪實測驗證 5 個質量升級方向》）的實測數據，以及 Superpowers writing-plans skill 的公開設計文檔分析整理而成。文中的配置模板和參數建議僅供參考，實際效果請以你的業務數據和環境測試結果為準。如果有實際使用經驗，歡迎在評論區分享交流。
上篇文章用 3 輪 Lab 驗證了 5 個質量升級方向。結論表貼出來，答案一目瞭然：5 個方向都有效，但性價比天差地別。
有些改動需要 fork schema、插入新工件、調依賴鏈，折騰一圈下來質量確實好了。但有個方向讓我意外——只改一段配置文本，不碰 OpenSpec 源碼，不裝外部工具，效果卻覆蓋了 80% 的質量問題。
這個方向就是：任務粒度控制。
今天這篇是「OpenSpec 項目實戰」系列第 1 期，定位方法論篇。先把為什麼任務粒度是那個 20% 講清楚，再說三步配置怎麼做，最後畫一張完整的日常工作流全景圖。從第 2 期開始，會拿一個真實項目「shuge AI Toolbox」，用這套方法論從零搭建，逐期展開。
1. 問題根源：任務太粗，AI 就會自由發揮
3 輪 Lab 跑下來，有一個發現反覆出現：AI 在 apply 階段夾帶私貨。
Lab 1 裸跑的時候，AI 從 todo-priority 這個 change name 推斷了全部需求。結果 tasks.md 裏出現了一個沒人提過的需求——ISO 8601 時間戳格式變更。這是個 breaking change，但 propose 階段根本沒人要求做這件事。
AI 做了什麼？它自行解釋了需求，然後自行決定了實現範圍。
這個問題的根因不在 AI 的能力，而在我們給它的任務描述太粗了。看一個對比就明白。
粗粒度任務長這樣：
- [ ] 1.1 實現用戶註冊接口
- [ ] 1.2 添加輸入校驗
- [ ] 1.3 處理異常情況
三個 task，每個都是一句話描述。AI 拿到這種 task 會做什麼？它會猜——註冊接口要不要發郵件？校驗規則是什麼？異常情況具體指哪些？猜完了就自己寫，寫完了你一看，不對。
細粒度任務長這樣：
### 任務 1：郵箱格式校驗
- [ ] 第 1 步：寫失敗測試
```typescript
test('無效郵箱格式返回 400', () => {
const result = register({ email: 'abc' });
expect(result.status).toBe(400);
});
```
- [ ] 第 2 步：運行測試——確認失敗
命令：`npx vitest run tests/auth.test.ts`
預期：FAIL — function is not defined
- [ ] 第 3 步：寫最小實現
（完整代碼）
- [ ] 第 4 步：運行測試——確認通過
命令：`npx vitest run tests/auth.test.ts`
預期：PASS
每個 step 附了完整代碼、運行命令、預期輸出。AI 拿到這種 task 還能發揮什麼？照着做就行了。
圖 2：任務粒度對比——粗任務給 AI 留了發揮空間，細任務把空間壓縮到零
因果鏈很清楚：
任務粗 → AI 自行解釋 → 自行決定範圍 → 夾帶私貨
任務細 + 附代碼 → AI 只需執行 → 沒有解釋空間 → 夾不了私貨
說到底，這不是 AI 能力的問題，是指令質量的問題。你給的指令有模糊空間，AI 就會填滿這個空間。你把模糊空間壓縮到零，AI 就只能照單執行。
2. 2/8 法則：任務粒度才是那個 20%
上篇文章驗證了 5 個升級方向。如果從性價比角度重新排序，畫面會完全不一樣。
| 升級 tasks 的 instruction | 極高 | ||
3 輪實測的結論支撐這個排序：
Lab 2 加了 Rules + Explore，產出質量主要來自 Explore 的需求澄清，rules 本身的效果很難單獨量化。為什麼？因為 rules 是文本約束，AI 有時候遵循有時候不遵循，你沒法保證每次都生效。
Lab 3 自定義 Schema 插入 Review 工件，tasks.md 從 19 個增加到 22 個，新增的 3 個 task 都有明確的 review 建議來源。但整條鏈路需要 fork schema、寫 review 模板、調整依賴關係，配置成本不低。
而升級 tasks 的 instruction 呢？只需要改一個字段裏的一段文字。不改 OpenSpec 源碼，不裝外部工具，不調整 DAG 依賴鏈。效果是讓 AI 在生成 tasks.md 的階段就把任務拆到 2-5 分鐘粒度，每個 step 附完整代碼。
20% 的改動，覆蓋 80% 的質量提升。 這就是 2/8 法則。
剩下的 80% 改動（審查 + 驗證 + CI）能帶來多少額外提升？大概 20%。它們是安全網，不是主力。
那這 20% 的改動具體怎麼做？
3. 三步配置：從不可控到 80 分
三步配置的思路很簡單：給 AI 足夠精確的上下文 → 給 AI 足夠嚴格的執行指令 → 插一道自動檢查。每步只改一個文件。
第 1 步：創建 config.yaml（上下文 + 規則）
這個文件給 AI 提供全局上下文和按工件分組的規則。放在項目根目錄的 openspec/config.yaml：
schema: with-review
context:|
技術棧：TypeScript, Express, Vitest
測試命令：npx vitest run
所有新功能必須遵循 TDD 節奏——先寫失敗測試，再寫實現代碼
rules:
specs:
-每個數據字段的變更，必須覆蓋null、空值、越界三種異常場景
-Scenario必須使用#### 四級標題，否則歸檔時不生效
design:
-涉及數據庫migration的設計，必須包含回滾方案
tasks:
-每個task必須包含完整的測試代碼和實現代碼
-每組task的第一步必須是寫失敗測試，最後一步必須是驗證通過
review:
-重點檢查tasks.md的粒度是否達到2-5分鐘一個step
-檢查是否有佔位符（TBD、TODO、implementlater）
幾個要點：
context字段注入所有工件，告訴 AI 你的技術棧、測試命令、編碼規範rules按 artifact ID 分組，key 必須和 schema 裏的 artifact id 完全一致rules 在 prompt 中以約束條件的形式傳遞，相當於給 AI 畫紅線
完整配置文件見附件：
articles/attachments/config.yaml
第 2 步：Fork Schema，升級 tasks 的 instruction
這是核心改動。
先 fork 一個現有的 schema：
openspec schema fork spec-driven with-review
注意：
openspec schema fork目前標記為 experimental，後續版本可能有變化。
然後在 openspec/schemas/with-review/schema.yaml 中，找到 id: tasks 的 artifact，把它的 instruction 字段替換成下面這段：
instruction: |
創建細粒度的實現計劃。每個任務的工作量應在 2-5 分鐘之間。
每個任務必須遵循以下格式：
-涉及文件（精確路徑）
-第1步：寫失敗測試（附完整測試代碼）
-第2步：運行測試——確認失敗（附命令+預期輸出）
-第3步：寫最小實現（附完整實現代碼）
-第4步：運行測試——確認通過（附命令+預期輸出）
-第5步：提交（附git命令）
禁止事項（出現即視為計劃不合格）：
-TBD、TODO、implementlater
-「添加適當的錯誤處理」（必須寫出具體代碼）
-「為以上代碼寫測試」（必須寫出具體測試代碼）
-只描述做什麼但不展示怎麼做
這段 instruction 做了兩件事：
第一，給 AI 一個嚴格的任務模板。 每個 task 必須包含 5 個 step，從寫失敗測試到提交，每步附完整代碼和命令。AI 沒有發揮空間。
第二，列了一堆禁止事項。 這些都是 AI 常見的偷懶行為——寫個 TBD 讓你自己填，說一句「添加適當的錯誤處理」就算完成了。現在出現這些就直接判定計劃不合格。
完整 instruction 內容見附件：
articles/attachments/tasks-instruction.yaml
第 3 步：插入 review 工件（配套措施）
在前兩步的基礎上，給 schema 加一個 review 工件，放在 design 和 tasks 之間：
# schema.yaml 中的新增工件
-id:review
generates:review.md
template:review.md
description:五維審查-檢查設計方案和Spec的完整性
instruction:|
從五個維度審查所有工件的完整性和質量。
審查維度：
1. 邊界條件 2. 回滾方案 3. 測試覆蓋
4. 向後兼容 5. 任務粒度（最重要）
requires:[proposal,specs,design]
然後把 tasks 的 requires 從 [specs, design] 改為 [review]。這樣依賴鏈變成：
proposal → specs → design → review → tasks → APPLY
review 工件是個閘門：沒有 review，tasks 就不會開始生成。審查結論裏會明確標註每個維度的狀態（✅ 通過 / ⚠️ 警告 / ❌ 失敗），tasks.md 會參考 review 的建議來決定拆分方向。
坦率說，這一步的效果比前兩步温和。3 輪實測發現，自己審自己的審查結論偏寬鬆——4 Pass + 1 Warning 看着不錯，但換成人類審查可能更嚴格。不過作為一道結構化的安全網，它還是有價值的。
完整 review instruction 見附件：
articles/attachments/review-instruction.yamlreview 模板文件見附件：articles/attachments/review-template.md
圖 3：三步配置——從上下文注入到指令升級再到自動審查
三步做完，日常開發的工作流長什麼樣？
4. 完整工作流：6 個 Phase 的日常開發
配置是一次性的，日常開發就是反覆跑 6 個 Phase。每個 Phase 對應一條 OpenSpec 命令，AI 做完一步你確認一步。
Phase 1：需求澄清
/opsx:explore
可選但推薦。在 propose 之前，先把模糊地帶想清楚：字段類型怎麼選、邊界條件有哪些、遷移策略是什麼。Explore 會畫出決策矩陣幫你理清思路。
3 輪實測的結論是：Explore 階段的需求澄清，是產出質量提升的主要來源。Lab 2 的 rules 本身效果不太容易量化，但 Explore + propose 的組合比單獨 propose 可靠得多——需求是你說的，不是 AI 猜的。
Phase 2：一鍵生成工件
/opsx:propose
propose 內部會自動創建 change 目錄，然後按依賴順序生成全部工件。用 with-review schema 的話，一次產出 5 個文件：proposal.md、specs/、design.md、review.md、tasks.md。
關鍵是 tasks.md——因為我們升級了 instruction，這裏的每個 task 都是 2-5 分鐘粒度、附完整代碼和命令的。
Phase 3：人工檢查（1-2 分鐘）
這一步只需要掃一眼 review.md。重點看兩個地方：
任務粒度那個維度的狀態：是 ✅ 還是 ⚠️？ 整體評估裏對 tasks.md 的關鍵建議
如果 review 說 tasks.md 粒度不夠或者有佔位符，手動改一下 tasks.md 再往下走。OpenSpec 的工件都是 Markdown 文件，直接編輯就行。
Phase 4：按任務執行
/opsx:apply
AI 讀取所有工件後，按 tasks.md 裏的順序逐個實現。因為每個 step 都有完整代碼和命令，AI 只需要照着做——沒有發揮空間。
Phase 5：一致性驗證（安全網）
/opsx:verify
注意：verify 需要 expanded workflow 才能使用。
verify 檢查實現是否匹配 spec 意圖。本質是文本層面的一致性檢查，不是運行驗證。代碼能不能跑，還得靠測試框架和 CI。但作為一道安全網，它能發現「spec 裏寫了要做 A，代碼裏做的是 B」這類問題。
你在項目中用過類似的 6 步工作流嗎？有沒有哪個 Phase 你覺得可以省掉？歡迎在評論區聊聊。
Phase 6：歸檔
/opsx:archive
將整個 change 目錄歸檔。歸檔前建議掃一眼所有 task 的完成狀態，確認沒有遺漏。
5. 三層防線：不是所有防線都一樣重要
三步配置搭好之後，日常開發中其實有三層防線在工作。但它們的重要性不在一個量級。
圖 4：三層防線——80% 的質量來自源頭控制
第一層：源頭控制（tasks instruction 升級）→ 貢獻 80% 的質量
這是整篇文章的核心。通過升級 instruction，讓 AI 在生成 tasks.md 的時候就把每個 step 拆到 2-5 分鐘、附上完整代碼。問題在源頭就被消滅了，後面的防線只需要處理遺漏。
第二層：過程檢查（review + verify）→ 安全網
review 工件在 design 和 tasks 之間插入一道結構化審查。verify 在 apply 後做一致性檢查。這兩道防線處理的是第一層漏掉的問題——邊界條件遺漏、回滾方案缺失、spec 和代碼不一致。
第三層：收尾確認（archive 前的人工檢查）→ 兜底
掃一眼 review.md 的結論和 tasks.md 的完成狀態，1-2 分鐘的事。這是人的防線，處理前兩層沒覆蓋到的邊界情況。
三層防線的設計哲學：第一層做重，第二層做輕，第三層做快。 不要試圖在每一層都做 100% 的檢查——那是在每個環節都投入 80% 的精力，換來 20% 的邊際提升。
6. 實戰注意事項
坑點和技巧都是 3 輪 Lab 裏踩過的，每條一句話。
坑點：
rules 的 key 必須和 artifact id 完全一致。寫成 task而不是tasks，規則就靜默失效了，不會報錯。openspec schema fork目前是 experimental 功能，後續版本命令格式可能變化，升級時留意 changelog。verify 不做運行驗證，只做文本一致性檢查。代碼能不能跑，得靠測試框架。 review 是自己審自己，結論偏寬鬆。對質量有硬性要求的項目，review 適合初審，不宜終審。 context 窗口壓力。apply 階段 AI 需要同時持有所有工件信息，複雜變更時建議先 /clear再 apply。
技巧：
複雜變更（5 個文件以上）拆成多個獨立 change，每個只做一件事。上下文壓力小，AI 不容易遺忘。 propose 不一定會問需求——change name 足夠清晰時 AI 可能跳過確認直接生成。想控制需求就先跑一遍 Explore。 工件都是 Markdown 文件，隨時可以手動改。propose 生成的 tasks 粒度不夠？直接編輯 tasks.md，不用重跑 propose。 instruction 裏多寫「禁止事項」比多寫「建議事項」更有效。AI 對否定約束的遵循度高於模糊的正面指導。
下一期預告
這篇方法論講完了為什麼任務粒度是那個 20%，三步配置怎麼做，日常工作流長什麼樣。
第 2 期開始實戰。我會用這套方法論，從零開始搭建一個真實項目——shuge AI Toolbox。第 2 期的內容：
用 Explore 澄清項目需求，確定 MVP 範圍 執行 propose 生成 5 個工件，逐個檢查產出質量 重點看 tasks.md 的粒度是不是真的達到了 2-5 分鐘一個 step
如果你也想跟着做，建議先把三步配置跑通：創建 config.yaml、fork schema、升級 instruction。具體配置文件下一期會放在公開的代碼倉庫作為附件，讀者可以直接拿來改。
系列持續更新中，關注不迷路。
好啦，謝謝你觀看我的文章，如果喜歡可以點贊轉發給需要的朋友，我們下一期再見！敬請期待！
掃碼關注，獲取更多 AI 工具的實戰經驗和最佳實踐。不錯過每一篇乾貨！