引言：完美的流程，崩塌的結果

最近我在使用 Spec Kit 做需求開發。這套工具宣稱通過標準化的 7 個步驟——Specify（定義）、Clarify（澄清）、Plan（計劃）、Tasks（任務）、Analyze（分析）、Checklist（檢查）、Implement（實現）——來生成高質量代碼。

我的初衷是美好的：輸入需求，喝杯咖啡，輸出代碼。

但現實給了我一記響亮的耳光。當我滿懷期待地跑到第 7 步 Implement 時，生成的代碼完全不可用：數據庫方言錯了、重複造了已有的輪子、業務邏輯不僅沒對齊甚至還跑偏了。

這讓我意識到一個殘酷的真相：在 AI 輔助編程中，如果缺乏嚴格的每一步把控，AI 就會陷入“幻覺”，原本的“自動駕駛”會變成“事故現場”。

今天這篇博客，就是一次血淚覆盤。我總結了 Spec Kit 流程中的“避坑指南”，希望大家能少走彎路。

核心覆盤：蝴蝶效應與“全自動”陷阱

我在這次實踐中最大的教訓是：不要相信 AI 的默認假設。

Spec Kit 的流程是一個鏈式反應。第 1 步的 Specify 如果有 1% 的偏差，到了第 3 步 Plan 就會變成技術選型的錯誤，到了第 7 步 Implement 就會變成幾百行完全跑不通的垃圾代碼。這就是 AI 編程的蝴蝶效應。

以下是具體的踩坑現場與應對策略：

1. Specify & Clarify（定義與澄清）：別隻顧着答題

❌ 踩坑現場：
在第 2 步 Clarify 時，AI 會像面試官一樣問我不清楚的地方。我當時只顧着回答它的問題，卻忽略了檢查它基於第一步生成的 specify.md。
結果： AI 在文檔裏悄悄“腦補”了一些我沒提到、但它認為合理的邏輯，或者定義了錯誤的數據結構。

✅ 避坑策略：

• 回溯檢查：不要只看 Question，一定要回頭精讀 specify.md 的 Summary 和 Description。
• 不僅僅是澄清：除了回答 AI 的問題，還要主動思考：“你生成的文檔是否包含了我沒説、但我默認你該知道的約束？”如果不包含，立刻補充。

2. Plan（技術方案）：張冠李戴的重災區

❌ 踩坑現場：
這是最容易翻車的地方。AI 往往不知道你項目的具體技術棧細節。

• 案例 A：我的項目明明是 PostgreSQL，AI 生成的 Plan 裏卻打算用 MySQL 的方言寫 SQL，甚至引入 MySQL 的驅動依賴。
• 案例 B：項目裏規定用 MyBatis-Plus，AI 卻在 Plan 裏規劃了一套 JPA 的實體類。

✅ 避坑策略：

• 上下文注入：在這一步，必須強制檢查技術棧。
• 明確否決：如果 Plan 裏出現了錯誤的技術選型（例如用錯了數據庫、ORM 框架），必須立刻打回重做，絕不能想着“生成代碼後再改”。Plan 錯了，後面的代碼不僅是錯的，還是不可挽回的錯。

3. Tasks（任務拆解）：拒絕重複造輪子

❌ 踩坑現場：
AI 作為一個“外來户”，它不知道你項目裏有什麼。

• 現象：AI 生成的 Tasks 裏，赫然列着“配置數據庫連接池”、“編寫 Redis 工具類”、“搭建日誌切面”。
• 後果：這些基礎設施（Infrastructure）在現有代碼裏早就有了！如果照着執行，你的項目裏就會出現兩個 RedisUtil，兩套鑑權邏輯，導致代碼極其臃腫甚至衝突。

✅ 避坑策略：

• 做減法：毫不留情地刪除所有“基建類”任務。
• 強制複用：在 Task 描述裏明確標註：“使用現有的 com.example.common.RedisUtil，不要新建”。

4. Checklist（檢查清單）：最後的防線

❌ 踩坑現場：
經歷了前面幾步的折騰，人容易產生疲勞感。到了第 6 步 Checklist，我當時的心態是：“差不多得了，快生成代碼吧。” 於是看都沒看細則就點了通過。
結果： AI 生成代碼時徹底放飛自我，剛才在 Plan 裏沒攔住的錯誤，在這裏全部變成了具體的 Bug。

✅ 避坑策略：

• 逐條審計：這步必須一個一個檢查，不要放過任何疑點。
• 腦內預演：看到 Checklist 時，腦子裏要預演一遍生成的代碼大概長什麼樣。如果這一步沒把控住，AI 就會偏離你的初衷。只有這一步對了，Implement 才會是你想要的代碼。

方法論總結：從“指揮官”轉變為“審計員”

通過這次踩坑，我總結了一套使用 Spec Kit（或其他 AI 編程 Agent）的標準作業程序（SOP）：

1. 角色轉換

不要把自己當成只會下命令的指揮官（Commander），要把自己當成極其嚴格的代碼審計員（Auditor）。AI 是實習生，你是 Tech Lead。

2. 前置約束（Pre-Prompt）

不要等到 AI 犯錯再改。在開始流程前，最好貼一段“項目上下文聲明”：

Project Context:

• DB: PostgreSQL (Not MySQL)
• ORM: MyBatis-Plus
• Infra: 禁止創建新的 DB/Redis 配置，必須複用 src/common 下的代碼。

3. 零容忍原則

每一步都需要嚴格把控，一個問題都不要放過。
如果在 Plan 階段發現一個小偏差，不要幻想 AI 在 Implement 階段會自動修正。相反，這個偏差會被放大 10 倍。

4. 持續迭代你的 prompt.md 資產

這是最高階的玩法。AI 犯過的錯，不要讓它犯第二次。
Spec Kit 的核心配置通常在於 prompt.md 文件。每當你發現 AI 在某個環節踩坑（比如總是忘記加 @Builder 註解，或者總是想自己寫 Util 類），請立刻將這條規則補充進你的 prompt.md 中。
隨着你不斷地“餵養”和修繕這個文件，它會變成一份“不懂你的人絕對用不好的”核心技術資產。你的 AI Agent 會越來越懂你的代碼風格，效率也會呈現指數級上升。

結語

AI 編程工具確實能提升效率，但它目前還做不到“完全託管”。它能幫我們省去寫樣板代碼的手速，但無法替代我們對技術方案的判斷力。

如果你也想用 Spec Kit 做出想要的代碼，請記住：時刻保持警惕，把每一步的輸出都當成必須要 Code Review 的代碼來看待，並不斷打磨你的 Prompt 資產。

只有這樣，AI 才能成為你的神隊友，而不是那個坑你的實習生。

本文由mdnice多平台發佈