引言：完美的流程，崩塌的結(jié)果

最近我在使用 Spec Kit 做需求開(kāi)發(fā)。這套工具宣稱通過(guò)標(biāo)準(zhǔn)化的 7 個(gè)步驟——Specify（定義）、Clarify（澄清）、Plan（計(jì)劃）、Tasks（任務(wù)）、Analyze（分析）、Checklist（檢查）、Implement（實(shí)現(xiàn)）——來(lái)生成高質(zhì)量代碼。

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

但現(xiàn)實(shí)給了我一記響亮的耳光。當(dāng)我滿懷期待地跑到第 7 步 Implement 時(shí)，生成的代碼完全不可用：數(shù)據(jù)庫(kù)方言錯(cuò)了、重復(fù)造了已有的輪子、業(yè)務(wù)邏輯不僅沒(méi)對(duì)齊甚至還跑偏了。

這讓我意識(shí)到一個(gè)殘酷的真相：在 AI 輔助編程中，如果缺乏嚴(yán)格的每一步把控，AI 就會(huì)陷入“幻覺(jué)”，原本的“自動(dòng)駕駛”會(huì)變成“事故現(xiàn)場(chǎng)”。

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

核心復(fù)盤：蝴蝶效應(yīng)與“全自動(dòng)”陷阱

我在這次實(shí)踐中最大的教訓(xùn)是：不要相信 AI 的默認(rèn)假設(shè)。

Spec Kit 的流程是一個(gè)鏈?zhǔn)椒磻?yīng)。第 1 步的 Specify 如果有 1% 的偏差，到了第 3 步 Plan 就會(huì)變成技術(shù)選型的錯(cuò)誤，到了第 7 步 Implement 就會(huì)變成幾百行完全跑不通的垃圾代碼。這就是 AI 編程的蝴蝶效應(yīng)。

以下是具體的踩坑現(xiàn)場(chǎng)與應(yīng)對(duì)策略：

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

? 踩坑現(xiàn)場(chǎng)：
在第 2 步 Clarify 時(shí)，AI 會(huì)像面試官一樣問(wèn)我不清楚的地方。我當(dāng)時(shí)只顧著回答它的問(wèn)題，卻忽略了檢查它基于第一步生成的 specify.md。
結(jié)果： AI 在文檔里悄悄“腦補(bǔ)”了一些我沒(méi)提到、但它認(rèn)為合理的邏輯，或者定義了錯(cuò)誤的數(shù)據(jù)結(jié)構(gòu)。

? 避坑策略：

• 回溯檢查：不要只看 Question，一定要回頭精讀 specify.md 的 Summary 和 Description。
• 不僅僅是澄清：除了回答 AI 的問(wèn)題，還要主動(dòng)思考：“你生成的文檔是否包含了我沒(méi)說(shuō)、但我默認(rèn)你該知道的約束？”如果不包含，立刻補(bǔ)充。

2. Plan（技術(shù)方案）：張冠李戴的重災(zāi)區(qū)

? 踩坑現(xiàn)場(chǎng)：
這是最容易翻車的地方。AI 往往不知道你項(xiàng)目的具體技術(shù)棧細(xì)節(jié)。

• 案例 A：我的項(xiàng)目明明是 PostgreSQL，AI 生成的 Plan 里卻打算用 MySQL 的方言寫(xiě) SQL，甚至引入 MySQL 的驅(qū)動(dòng)依賴。
• 案例 B：項(xiàng)目里規(guī)定用 MyBatis-Plus，AI 卻在 Plan 里規(guī)劃了一套 JPA 的實(shí)體類。

? 避坑策略：

• 上下文注入：在這一步，必須強(qiáng)制檢查技術(shù)棧。
• 明確否決：如果 Plan 里出現(xiàn)了錯(cuò)誤的技術(shù)選型（例如用錯(cuò)了數(shù)據(jù)庫(kù)、ORM 框架），必須立刻打回重做，絕不能想著“生成代碼后再改”。Plan 錯(cuò)了，后面的代碼不僅是錯(cuò)的，還是不可挽回的錯(cuò)。

3. Tasks（任務(wù)拆解）：拒絕重復(fù)造輪子

? 踩坑現(xiàn)場(chǎng)：
AI 作為一個(gè)“外來(lái)戶”，它不知道你項(xiàng)目里有什么。

• 現(xiàn)象：AI 生成的 Tasks 里，赫然列著“配置數(shù)據(jù)庫(kù)連接池”、“編寫(xiě) Redis 工具類”、“搭建日志切面”。
• 后果：這些基礎(chǔ)設(shè)施（Infrastructure）在現(xiàn)有代碼里早就有了！如果照著執(zhí)行，你的項(xiàng)目里就會(huì)出現(xiàn)兩個(gè) RedisUtil，兩套鑒權(quán)邏輯，導(dǎo)致代碼極其臃腫甚至沖突。

? 避坑策略：

• 做減法：毫不留情地刪除所有“基建類”任務(wù)。
• 強(qiáng)制復(fù)用：在 Task 描述里明確標(biāo)注：“使用現(xiàn)有的 com.example.common.RedisUtil，不要新建”。

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

? 踩坑現(xiàn)場(chǎng)：
經(jīng)歷了前面幾步的折騰，人容易產(chǎn)生疲勞感。到了第 6 步 Checklist，我當(dāng)時(shí)的心態(tài)是：“差不多得了，快生成代碼吧?！?于是看都沒(méi)看細(xì)則就點(diǎn)了通過(guò)。
結(jié)果： AI 生成代碼時(shí)徹底放飛自我，剛才在 Plan 里沒(méi)攔住的錯(cuò)誤，在這里全部變成了具體的 Bug。

? 避坑策略：

• 逐條審計(jì)：這步必須一個(gè)一個(gè)檢查，不要放過(guò)任何疑點(diǎn)。
• 腦內(nèi)預(yù)演：看到 Checklist 時(shí)，腦子里要預(yù)演一遍生成的代碼大概長(zhǎng)什么樣。如果這一步?jīng)]把控住，AI 就會(huì)偏離你的初衷。只有這一步對(duì)了，Implement 才會(huì)是你想要的代碼。

方法論總結(jié)：從“指揮官”轉(zhuǎn)變?yōu)椤皩徲?jì)員”

通過(guò)這次踩坑，我總結(jié)了一套使用 Spec Kit（或其他 AI 編程 Agent）的標(biāo)準(zhǔn)作業(yè)程序（SOP）：

1. 角色轉(zhuǎn)換

不要把自己當(dāng)成只會(huì)下命令的指揮官（Commander），要把自己當(dāng)成極其嚴(yán)格的代碼審計(jì)員（Auditor）。AI 是實(shí)習(xí)生，你是 Tech Lead。

2. 前置約束（Pre-Prompt）

不要等到 AI 犯錯(cuò)再改。在開(kāi)始流程前，最好貼一段“項(xiàng)目上下文聲明”：

Project Context:

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

3. 零容忍原則

每一步都需要嚴(yán)格把控，一個(gè)問(wèn)題都不要放過(guò)。
如果在 Plan 階段發(fā)現(xiàn)一個(gè)小偏差，不要幻想 AI 在 Implement 階段會(huì)自動(dòng)修正。相反，這個(gè)偏差會(huì)被放大 10 倍。

4. 持續(xù)迭代你的 prompt.md 資產(chǎn)

這是最高階的玩法。AI 犯過(guò)的錯(cuò)，不要讓它犯第二次。
Spec Kit 的核心配置通常在于 prompt.md 文件。每當(dāng)你發(fā)現(xiàn) AI 在某個(gè)環(huán)節(jié)踩坑（比如總是忘記加 @Builder 注解，或者總是想自己寫(xiě) Util 類），請(qǐng)立刻將這條規(guī)則補(bǔ)充進(jìn)你的 prompt.md 中。
隨著你不斷地“喂養(yǎng)”和修繕這個(gè)文件，它會(huì)變成一份“不懂你的人絕對(duì)用不好的”核心技術(shù)資產(chǎn)。你的 AI Agent 會(huì)越來(lái)越懂你的代碼風(fēng)格，效率也會(huì)呈現(xiàn)指數(shù)級(jí)上升。

結(jié)語(yǔ)

AI 編程工具確實(shí)能提升效率，但它目前還做不到“完全托管”。它能幫我們省去寫(xiě)樣板代碼的手速，但無(wú)法替代我們對(duì)技術(shù)方案的判斷力。

如果你也想用 Spec Kit 做出想要的代碼，請(qǐng)記?。?strong>時(shí)刻保持警惕，把每一步的輸出都當(dāng)成必須要 Code Review 的代碼來(lái)看待，并不斷打磨你的 Prompt 資產(chǎn)。

只有這樣，AI 才能成為你的神隊(duì)友，而不是那個(gè)坑你的實(shí)習(xí)生。

本文由mdnice多平臺(tái)發(fā)布