不知道你有沒有過這種經(jīng)歷讓 AI 幫忙寫一個功能模塊它幾分鐘就生成了一整段邏輯清晰的代碼你甚至還沒來得及夸它測試那邊就報了一堆“不是你需求”的問題。到了下午你又重新描述了一遍需求AI 又一次爽快地重寫了一遍結(jié)果第二天產(chǎn)品經(jīng)理拿著更新后的需求文檔走過來時你突然發(fā)現(xiàn)之前的實現(xiàn)全部作廢又要重來。這套場景在最近一年里幾乎每天都在上演。AI 寫得越來越快代碼量產(chǎn)出越來越高但返工率并沒有因為“快”而降下來反而在部分團隊里變得更嚴重了。原因不難想AI 在動手之前根本不知道你到底要什么甚至連你自己也只是“大概知道要什么”。而一個模糊的需求經(jīng)過 AI 的高效執(zhí)行會被放大成一堆結(jié)構(gòu)完整、但方向跑偏的代碼。這篇文章要聊的正是怎么應(yīng)對這個問題。我會從“為什么 AI 寫得越快返工越多”這個痛點切入完整拆解一套名為 Spec Kit 的 AI 輔助開發(fā)流程思路它把開發(fā)前的工作分成需求評估、Specify、Plan、Tasks 幾個階段讓 AI 每次動手之前先把“需求、方案、任務(wù)邊界”固定下來并且讓每一次需求變化都有記錄。無論你是在用 Claude Code、Cursor還是其他 AI 編程助手這套思路都能直接參考。1. 為什么 AI 寫得越快返工反而越多先聊一個反直覺的現(xiàn)象工具效率提升通常應(yīng)該讓項目交付更快為什么 AI 編程反而讓返工變多1.1 高估了 AI 的理解能力很多人天然覺得AI 大模型訓練了那么多代碼能力那么強幾段話它肯定能理解。但實際用下來會發(fā)現(xiàn)AI 對自然語言的理解并沒有那么穩(wěn)定。它擅長的是“從你給出的信息里推斷出一個合理答案”而不是“理解你的真實業(yè)務(wù)意圖”。舉個例子。你說“給用戶列表加一個搜索功能”這句話在五個開發(fā)者心里可能是五種實現(xiàn)按用戶名模糊搜索按用戶名和手機號同時搜索支持搜索后分頁保持篩選條件搜索框輸入時防抖避免頻繁請求搜索結(jié)果為空時顯示空狀態(tài)提示。你不說清楚是哪一種AI 大概率會基于訓練數(shù)據(jù)里的“最常見實現(xiàn)”來寫。你想要的可能是 2 和 5它默認寫的是 1 和 3。結(jié)果就是代碼結(jié)構(gòu)沒錯功能也能跑但和你腦子里想的根本不是同一個東西。這其實是信息差問題不是 AI 能力問題。開發(fā)者和 AI 之間的信息差最終都要靠“返工”來補齊。1.2 代碼生成快驗證成本反而更大以前的開發(fā)模式下寫代碼本身就是梳理思路的過程。你要先想清楚接口怎么設(shè)計、數(shù)據(jù)怎么流轉(zhuǎn)、頁面怎么跳轉(zhuǎn)然后才開始敲鍵盤。雖然慢但代碼寫完你心里基本有底。AI 編程是反過來的。它幾秒鐘就把代碼全部生成出來了看上去結(jié)構(gòu)完整、注釋也有但你并沒有“跟著寫一遍”所以對這堆代碼的掌握程度是偏低的。代碼出了 bug你需要從頭到尾去讀它、測試它、甚至還要重新讓 AI 解釋它做了什么——這個驗證成本遠高于“自己敲一遍”的成本。換句話說AI 把“寫代碼”的成本壓縮到了極低但“讓代碼正確”的成本沒有變少只是換了個地方出現(xiàn)。如果 AI 寫得越多你驗證和糾偏的范圍就越大返工自然就越多。1.3 對話上下文會“漂移”用 AI 編程的另一個高頻問題是上下文不一致。AI 編程本質(zhì)上是圍繞一段對話歷史在“續(xù)寫”當對話越來越長AI 會慢慢遺忘最開始的需求約束甚至會按照你最近幾句話的方向去改代碼把之前已經(jīng)穩(wěn)定的模塊也隨手調(diào)整了。更常見的場景是你上午讓 AI 實現(xiàn)了 A 邏輯下午改成了 B 邏輯晚上又覺得還是 A 更合理。這時候你重新打開對話憑記憶描述了一遍但漏掉了一個關(guān)鍵細節(jié)。AI 給出的版本看起來和上午一樣實際上少了一個核心分支。這種問題很難在代碼層面發(fā)現(xiàn)因為代碼風格、命名習慣看起來都一致唯一缺的是那個你沒說出口的細節(jié)。返工的核心原因不是 AI 不聽話而是你的“上下文管理”失控了。1.4 需求沒有“流動狀態(tài)”管理傳統(tǒng)開發(fā)里有需求文檔、PRD、變更記錄、驗收標準每一項需求從提出到上線是有狀態(tài)的。但在 AI 編程場景里很多人把這些環(huán)節(jié)全部壓縮成了“直接對 AI 描述需求”。需求和實現(xiàn)之間缺少中間產(chǎn)物。當需求發(fā)生變化時開發(fā)者的習慣是“重新描述一遍”而不是“記錄變更再做增量”。問題是AI 沒有長期記憶新起一個對話它就忘了之前所有上下文。于是每次需求變化都要靠對話重新輸入重新生成重新驗證。一次變化一次全量返工。這就引出了 Spec Kit 要解決的問題。2. Spec Kit 是一套什么思路2.1 Spec Kit 的定義與目標Spec Kit 并不是一個嚴格意義上的開源框架或工具它更接近一套“讓 AI 編程流程可控”的工程實踐方法論。它的核心思想是在讓 AI 生成代碼之前先產(chǎn)出四類中間文檔——需求評估Requirement Review確認需求是什么、邊界在哪里、是否可做規(guī)格說明Specify用結(jié)構(gòu)化的方式把需求固定下來包含功能范圍、輸入輸出、驗收標準實現(xiàn)計劃Plan拆出技術(shù)方案、依賴關(guān)系、風險點任務(wù)清單Tasks把計劃進一步拆成原子任務(wù)每個任務(wù)都有明確產(chǎn)出和完成定義。在整個流程中Tasks 不是一次性交給 AI 的“所有需求”而是按優(yōu)先級分批下達的“最小工作單元”。AI 每完成一個 Task都要回到規(guī)格說明里做一次校驗確保沒有偏離方向。2.2 Spec Kit 的五個核心環(huán)節(jié)可以把 Spec Kit 理解成“需求進入 AI 之前的過濾器和導航儀”。完整流程包含五個環(huán)節(jié)需求提出 - Review 需求評估 - Specify 規(guī)格說明 - Plan 實現(xiàn)計劃 - Tasks 任務(wù)執(zhí)行 - 驗證與歸檔最后一個環(huán)節(jié)驗證與歸檔在多數(shù)團隊里會被忽略。它的作用是當需求發(fā)生變化時不是打開新對話重新輸入而是把變更記錄追加到規(guī)格說明里再重新生成 Plan 和 Tasks。這樣做的好處是每一次變更都有跡可循AI 不會因為對話重開就丟失上下文。2.3 Spec Kit 適合什么場景我認為 Spec Kit 最適用的不是那種“五分鐘寫個腳本”的場景而是滿足以下條件的場景需求會持續(xù)迭代后續(xù)大概率有變更功能涉及多個模塊改動面橫跨前后端或數(shù)據(jù)庫需要多人協(xié)作AI 生成的代碼要能被其他人接手維護項目規(guī)范要求有需求記錄、驗收標準或?qū)徲嬜匪荨Ｈ绻阒皇桥R時處理一個幾十行的腳本直接讓 AI 生成可能更快不需要走的這么重。但當一個需求預(yù)計會占用你半天以上的開發(fā)時間或者需要改動多份文件時Spec Kit 的性價比就會體現(xiàn)出來。3. 使用 Spec Kit 前需要建立的項目環(huán)境在正式介紹每一步做什么之前先說說項目層面的準備。Spec Kit 依賴一個基本前提AI 能在動手之前讀到它需要的規(guī)范文檔。3.1 項目目錄里預(yù)留 specs 目錄建議在你的項目根目錄下單獨建立specs/目錄用來存放所有 Spec Kit 文檔。每個需求對應(yīng)一個獨立子目錄目錄名可以用需求編號加簡短語義來命名。project-root/ ├── src/ ├── tests/ ├── docs/ └── specs/ └── US-1001-user-email-verification/ ├── 01-review.md ├── 02-specify.md ├── 03-plan.md └── 04-tasks.md這么做的原因很簡單AI 無法憑空感知需求它只能從上下文中讀取信息。當 AI 開始工作前你可以在對話中直接告訴它“請先閱讀 specs/US-1001-user-email-verification/ 下的全部文檔然后按照 Tasks 逐個執(zhí)行”。這樣即使對話中途斷開重新打開后也能通過同樣的指令恢復上下文。3.2 明確 AI 工具的上下文加載方式不同 AI 編程工具讀取文件的方式不同。Claude Code 支持通過命令或直接讀取文件路徑Cursor 可以在對話中引用文件有些工具則支持把文件內(nèi)容粘貼進提示詞中。如果的工具限制比較多也可以在提示詞中直接粘貼規(guī)格說明全文但這樣做會帶來兩個問題大模型上下文有限粘貼太多內(nèi)容會浪費 token對話一長早期內(nèi)容仍可能被忽略。所以目錄化存儲仍然是更可靠的方式配合“每次深入思考前都重新讀取 specs 目錄”這個習慣要比單純依賴對話記憶穩(wěn)定得多。3.3 版本管理上的要求Spec Kit 文檔應(yīng)該使用 Markdown 編寫并納入 Git 管理。每次需求變更不只是改代碼還要同步更新 specs 文檔并提交一次 commit。這樣做的價值在后面的“需求變化閉環(huán)”一節(jié)會具體展開。建議為 specs 文檔專門約定一個 commit message 前綴比如spec:方便以后檢索需求演化歷史git add specs/ git commit -m spec: 更新 US-1001 郵箱驗證邏輯增加驗證碼有效期 30 分鐘4. 核心流程拆解從需求評估到 Tasks這一節(jié)是文章的核心我會按順序拆解 Review、Specify、Plan、Tasks 四個階段以及需求變化時的完整閉環(huán)。4.1 Review需求評估很多團隊跳過了這一步直接把產(chǎn)品經(jīng)理的話轉(zhuǎn)述給 AI結(jié)果 AI 把“可能”“大概”“后續(xù)再優(yōu)化”這些模糊信息也都當成需求寫進了代碼。Review 階段的目標是在和 AI 討論實現(xiàn)方案之前先和人類自己對齊。你可以不寫一份正式文檔但至少要回答清楚下面幾個問題這個需求背后的真實目標是什么涉及的現(xiàn)有模塊有哪些有不做的內(nèi)容嗎例如不做郵件發(fā)送只做驗證碼校驗技術(shù)上有依賴項嗎例如依賴 Redis、依賴第三方郵件服務(wù)不做會怎樣評估優(yōu)先級這些問題可以在對話里直接拋給 AI讓它幫你補充遺漏的檢查點但最終判斷必須由你來做。AI 可以提醒你“用戶列表搜索還要考慮分頁條件重置”但它不應(yīng)該在你不表態(tài)的情況下替你決定。Review 階段結(jié)束后把結(jié)論寫入01-review.md。文檔不需要很長重點是留下判斷依據(jù)。# US-1001 用戶注冊郵箱驗證 - 需求評審 ## 需求來源 產(chǎn)品端提出用戶注冊后需要進行郵箱驗證未驗證用戶限制部分功能。 ## 評審結(jié)論 - 目標提高注冊郵箱真實性減少無效賬號 - 影響模塊注冊接口、用戶表、登錄邏輯 - 不做不引入郵件發(fā)送組件使用現(xiàn)有郵件服務(wù) - 依賴需要新增驗證碼存儲計劃復用 Redis - 風險驗證郵件可能進入垃圾箱需要提示用戶 ## 變更說明 - v1.0 初始評審確認實現(xiàn)范圍Review 階段最容易犯的錯誤是試圖把所有細節(jié)一次討論完。其實不需要這個階段只需要圈定邊界剩下更細的問題留給 Specify 處理。4.2 Specify規(guī)格說明Specify 是整套流程里最關(guān)鍵的一步。它負責把“大致方向正確”的需求變成“AI 可以直接照著執(zhí)行”的規(guī)格文檔。一份合格的規(guī)格說明不建議寫成長篇大論而是盡量結(jié)構(gòu)化。推薦包含以下內(nèi)容需求概述功能范圍做什么 / 不做什么輸入輸出定義業(yè)務(wù)流程邏輯異常與邊界情況驗收標準以郵箱驗證為例核心可以寫成下面的樣子# US-1001 用戶注冊郵箱驗證 - 規(guī)格說明 ## 需求概述 用戶注冊成功后系統(tǒng)發(fā)出含有 6 位數(shù)字驗證碼的郵件。 用戶提交驗證碼后完成郵箱驗證。驗證碼有效期 30 分鐘每位用戶最多重發(fā) 3 次。 ## 功能范圍 - 注冊時生成驗證碼并發(fā)郵件 - 提供驗證接口校驗驗證碼 - 驗證成功后更新用戶狀態(tài) - 支持重新發(fā)送驗證碼受限次數(shù)內(nèi) ## 不做范圍 - 不實現(xiàn)郵件模板編輯功能 - 不做驗證碼圖形驗證碼 - 不做管理員后臺手動驗證 ## 輸入輸出定義 - 請求接口POST /api/v1/users/{userId}/email-verification - 請求參數(shù)code: string(6) - 成功響應(yīng)200 { verified: true } - 失敗響應(yīng)400 { message: 驗證碼錯誤或已過期 } ## 業(yè)務(wù)流程 1. 用戶注冊成功 - 生成驗證碼 2. 驗證碼存 Redis有效期 1800 秒 3. 發(fā)送郵件調(diào)用現(xiàn)有郵件服務(wù) 4. 用戶提交驗證碼 5. 校驗通過 - 更新用戶 email_verified true 6. 校驗失敗 - 返回錯誤并保留剩余重試次數(shù) ## 異常場景 - 驗證碼過期提示重新發(fā)送 - 重發(fā)超過 3 次提示 24 小時后再試 - 郵件發(fā)送失敗注冊接口仍返回成功但記錄發(fā)送失敗日志 ## 驗收標準 - 注冊成功后用戶收到含驗證碼的郵件 - 30 分鐘內(nèi)提交正確驗證碼驗證成功 - 驗證碼過期后提交返回明確錯誤提示 - 同一用戶重發(fā)驗證碼超過 3 次后接口拒絕并返回提示 - 驗證成功后再次提交同一驗證碼返回“已失效”這樣一份規(guī)格信息密度高、歧義少AI 可以直接依據(jù)它來寫代碼。相比日常對話描述它最大的價值是把“你腦子里的假設(shè)”變成了“雙方都能看到的基線”。4.3 Plan實現(xiàn)計劃規(guī)格說明解決的是“做什么”Plan 解決的是“怎么實現(xiàn)”。在很多 AI 編程工具里有一個“Plan 模式”或者“規(guī)劃模式”它會先分析文件結(jié)構(gòu)、閱讀相關(guān)代碼然后生成一份修改計劃。這個計劃應(yīng)當包含涉及文件清單每個文件的改動方向依賴關(guān)系哪些改動先做哪些后做潛在風險點驗證方式繼續(xù)用郵箱驗證的例子。假設(shè)項目是 Spring Boot RedisPlan 可以寫成# US-1001 實現(xiàn)計劃 ## 涉及文件 - UserController.java新增驗證接口、重發(fā)接口 - UserService.java新增驗證碼生成、校驗、重發(fā)邏輯 - UserRepository.java查詢用戶信息 - EmailService.java已有郵件接口無需改動 - RedisConfig.java已配置好 Redis無需改動 ## 實施順序 1. 在 UserService 中新增 generateVerificationCode() 2. 在 UserService 中新增 verifyEmail(userId, code) 3. 在 UserService 中新增 resendVerification(userId) 4. 在 UserController 中暴露兩個 POST 接口 5. 補異常類和錯誤碼 ## 風險點 - Redis key 設(shè)計建議使用 verify:email:{userId} - 并發(fā)重發(fā)需要限制重發(fā)頻率建議加 setnx 鎖 - 驗證碼安全性避免日志輸出驗證碼 ## 驗證方式 - 單元測試覆蓋驗證碼邏輯 - 接口測試驗證超時和錯誤碼場景Plan 的價值在于給 AI 一個“先看全局再動手”的機會。很多返工都是因為 AI 只見樹木不見森林為了改一個接口順手改了不相關(guān)的配置甚至幫你在實體類里加了一個它覺得“應(yīng)該有”的字段。有了 Plan你可以先行攔住這些跑偏。4.4 Tasks任務(wù)拆解與執(zhí)行Plan 定完之后進入 Tasks 階段。Tasks 是真正交給 AI 逐條執(zhí)行的指令。任務(wù)拆解有幾個原則每個 Task 都要能獨立驗證每個 Task 的改動范圍盡量小每個 Task 完成后要回到規(guī)格說明對照檢查不要一次性把全部 Task 交給 AI。列表形式任務(wù)的示例如下# US-1001 任務(wù)拆解 - [ ] Task 1在 UserService 中新增 generateVerificationCode 方法 - 產(chǎn)出生成 6 位數(shù)字驗證碼寫入 Redis - 完成定義單元測試通過 - [ ] Task 2在 UserService 中新增 verifyEmail 方法 - 產(chǎn)出校驗 Redis 中的驗證碼更新用戶郵箱驗證狀態(tài) - 完成定義正確、過期、重復提交均有測試覆蓋 - [ ] Task 3新增 resendVerification 方法 - 產(chǎn)出基于重發(fā)次數(shù)限制邏輯進行發(fā)送 - 完成定義超過 3 次后拒絕重發(fā) - [ ] Task 4在 UserController 中新增接口 - 產(chǎn)出POST /api/v1/users/{userId}/email-verification - 完成定義接口返回與規(guī)格說明一致當你開始讓 AI 干活時注意不要一次把四個 Task 全丟給它。更穩(wěn)妥的做法是請先完成 Task 1完成后對照 specs 文檔檢查再繼續(xù) Task 2。這樣做的好處是每個階段產(chǎn)物都可以及時糾偏。如果 Task 1 的驗證碼存儲方式有了偏差你只需要調(diào)整一個小點而不是等到 AI 把四個 Task 全部完成后你從一大片代碼里找問題。4.5 每次需求變化都走一次小閉環(huán)Spec Kit 真正體現(xiàn)優(yōu)勢的地方是需求變化后的處理方式。假設(shè)產(chǎn)品臨時提了一個新要求驗證碼改成 4 位數(shù)字并把有效期從 30 分鐘縮短到 10 分鐘。傳統(tǒng)的 AI 協(xié)作方式是你重新打開對話說“驗證碼改成 4 位的時間改成 10 分鐘”AI 改了代碼但 Redis key、日志描述、前端提示語可能都沒跟上。Spec Kit 的方式是先改文檔再改代碼。修改02-specify.md把驗證碼位數(shù)改為 4有效期改為 600 秒。追加變更記錄## 變更記錄 - v1.1 2025-06-10驗證碼位數(shù)由 6 位改為 4 位有效期由 30 分鐘改為 10 分鐘重新審視 Plan看是否有涉及文件變化。把變更后的差異點交給 AI讓它只改受影響的部分。這種方式看起來多了兩步文檔操作但換來的是每次需求變化的范圍都是可控的AI 不會借著一個小改動把無關(guān)模塊也重寫一遍。而且由于變更記錄存在文檔里即使兩周后有人接手也能通過 git 歷史還原當時的決策邏輯。5. 完整實戰(zhàn)用 Spec Kit 實現(xiàn)一個郵箱驗證功能為了讓你更直觀地理解完整流程這一節(jié)我?guī)阌靡粋€模擬項目走一遍。假設(shè)項目是一個 Spring Boot 3 的后端服務(wù)使用 Redis 存儲驗證碼已有郵件發(fā)送服務(wù)。需求是“用戶注冊后需要郵箱驗證”。5.1 第一步需求評估# US-1001 用戶注冊郵箱驗證 - 需求評審 ## 評審結(jié)論 - 目標驗證注冊郵箱真實性 - 不做不實現(xiàn)圖形驗證碼、不做郵件模板 - 依賴已有 Redis 配置、已有 EmailService - 影響范圍用戶表、注冊接口、登錄邏輯登錄時檢查是否已驗證 ## 打開問題 - 是否需要支持未驗證用戶重新發(fā)送郵件暫定支持這一步檢查有意義的問題是這個需求會改變注冊流程嗎不會向注冊接口增加阻塞驗證是異步的。如果不確認可以等確認完再進入下一步。5.2 第二步編寫規(guī)格說明# US-1001 用戶注冊郵箱驗證 - 規(guī)格說明 ## 輸入輸出 - 發(fā)送驗證碼POST /api/v1/users/{userId}/email-verification/send - 參數(shù)無 - 成功響應(yīng)200 { sent: true } - 提交驗證碼POST /api/v1/users/{userId}/email-verification - 參數(shù)code: string(6) - 成功響應(yīng)200 { verified: true } - 失敗響應(yīng)400 { message: 驗證碼錯誤或已過期 } ## 業(yè)務(wù)規(guī)則 - 驗證碼有效期 30 分鐘 - 同一用戶最多重發(fā) 3 次 - 驗證成功后Redis 中的驗證碼立即刪除 - Redis keyverify:email:{userId}5.3 第三步制定實現(xiàn)計劃# US-1001 實現(xiàn)計劃 ## 文件清單 - src/main/java/com/example/demo/controller/UserController.java - src/main/java/com/example/demo/service/UserService.java - src/main/java/com/example/demo/service/EmailService.java復用 - src/main/java/com/example/demo/repository/UserRepository.java ## 調(diào)用流程 UserController - UserService - RedisTemplate - EmailService5.4 第四步拆解并執(zhí)行任務(wù)這里演示一個用戶服務(wù)核心邏輯的最小實現(xiàn)片段。以下代碼不是完整項目而是展示 Spec Kit 如何引導我們完成一個 Task。// 文件路徑src/main/java/com/example/demo/service/UserService.java Service public class UserService { private static final String VERIFY_CODE_PREFIX verify:email:; private static final long VERIFY_CODE_EXPIRE_SECONDS 1800; private static final int MAX_RESEND_COUNT 3; private final RedisTemplateString, String redisTemplate; private final EmailService emailService; public UserService(RedisTemplateString, String redisTemplate, EmailService emailService) { this.redisTemplate redisTemplate; this.emailService emailService; } /** * Task 1: 生成驗證碼并發(fā)送郵件。 */ public void sendVerificationCode(Long userId, String email) { String code String.format(%06d, ThreadLocalRandom.current().nextInt(1000000)); String key VERIFY_CODE_PREFIX userId; String sendCountKey key :count; // 檢查重發(fā)次數(shù) String countStr redisTemplate.opsForValue().get(sendCountKey); int count countStr null ? 0 : Integer.parseInt(countStr); if (count MAX_RESEND_COUNT) { throw new BusinessException(重發(fā)次數(shù)已達上限請 24 小時后再試); } // 保存驗證碼和重發(fā)次數(shù) redisTemplate.opsForValue().set(key, code, Duration.ofSeconds(VERIFY_CODE_EXPIRE_SECONDS)); redisTemplate.opsForValue().increment(sendCountKey); redisTemplate.expire(sendCountKey, Duration.ofDays(1)); emailService.sendCodeEmail(email, code); } /** * Task 2: 校驗驗證碼。 */ public boolean verifyEmail(Long userId, String code) { String key VERIFY_CODE_PREFIX userId; String savedCode redisTemplate.opsForValue().get(key); if (savedCode null || !savedCode.equals(code)) { return false; } // 驗證成功后刪除驗證碼 redisTemplate.delete(key); return true; } }這段代碼的關(guān)鍵點有ThreadLocalRandom.current().nextInt(1000000)用來生成 0 到 999999 之間的數(shù)再用%06d格式化成 6 位數(shù)字避免出現(xiàn) 5 位驗證碼Redis key 帶上了業(yè)務(wù)前綴verify:email:避免和其他緩存數(shù)據(jù)沖突重發(fā)次數(shù)單獨用一個 key 存儲并設(shè)置 1 天過期避免無限重發(fā)驗證成功后立即刪除 key防止同一個驗證碼被重復使用。在真實項目中BusinessException應(yīng)該是項目里已有的統(tǒng)一異常類EmailService的sendCodeEmail方法也需要先確認簽名。AI 生成代碼時可能會按自己的理解創(chuàng)建新類這是最常見的跑偏點。這時只要對照 Plan 文件就能很快發(fā)現(xiàn)它多創(chuàng)建了哪些類及時糾偏。5.5 第五步驗收與歸檔代碼跑通后建議用驗收清單檢查一下注冊后用戶能收到驗證碼郵件嗎驗證碼過期后提交是否返回了明確錯誤重發(fā)超過 3 次是否被拒絕驗證成功后再次提交是否返回失敗Redis 里驗證碼 key 有沒有正常刪除確認無誤后把specs/下的文檔提交到 Git。歸檔這一步的意義是讓這次需求決策留下記錄。下次如果有人問“為什么這個驗證碼設(shè)置成 30 分鐘而不是 10 分鐘”直接看變更記錄就能還原當時的背景。6. 常見問題與排查思路在引入 Spec Kit 這類流程時容易遇到下面一些問題。問題現(xiàn)象常見原因解決思路AI 不按照規(guī)格文檔執(zhí)行提示詞沒有明確要求先讀文檔在對話開頭強制指定“先閱讀 specs 目錄再開始寫代碼”規(guī)格文檔寫了AI 還是自由發(fā)揮規(guī)格里存在 AI 難以理解的模糊表達把“業(yè)務(wù)規(guī)則”改成“輸入輸出 異常分支”文檔維護太耗時把規(guī)格文檔當論文寫控制篇幅只寫“會變的東西”需求變化后 AI 改了無關(guān)代碼對話上下文被污染重新開始對話先把變更點寫進規(guī)格再讓 AI 做增量修改Tasks 拆得太粗每個 Task 涉及多個文件難以驗證堅持“一個 Task 一個核心產(chǎn)出”驗收標準不夠精確描述全是“正常情況”增加異常場景明確“什么情況下必須失敗”另外有一種情況也值得注意有些開發(fā)者會用一段很長的提示詞把整個 Spec Kit 流程一次性描述給 AI然后讓 AI 自己完成全部流程。效果通常不太理想因為長上下文會導致 AI 遺忘早期約束而且它生成的文檔質(zhì)量也沒有人工梳理那么準確。更合適的做法是文檔由人來寫AI 負責執(zhí)行和驗證。7. 最佳實踐與工程建議7.1 規(guī)格文檔不是越詳細越好Spec Kit 最大的成本在于維護文檔。如果你把每一行代碼的細節(jié)都寫進規(guī)格等于寫了兩遍代碼反而拖慢效率。比較好的尺度是寫“需求邊界”不寫“具體實現(xiàn)”寫“驗收標準”不寫“測試用例細節(jié)”寫“異常分支”不寫“堆棧日志”。換句話說規(guī)格文檔應(yīng)該描述“什么是錯的”而不是“怎么把代碼寫對”。因為后者是 AI 擅長的事情。7.2 每次變更至少留下一行記錄很多團隊在需求穩(wěn)定時做得很好但只要需求開始快速變化文檔就會被拋棄。最典型的場景是測試說“驗證碼過期時間改成 5 分鐘”你隨手改了代碼常量但規(guī)格文檔里寫的還是 30 分鐘。從這一刻起文檔和代碼就開始分叉Spec Kit 的可靠性也就消失了。為了預(yù)防這個問題建議把文檔更新當成需求變更的一部分凡是改代碼之前必須先在規(guī)格文檔里追加變更記錄。不需要寫長篇大論一行就夠。## 變更記錄 - v1.2驗證碼過期時間由 30 分鐘修改為 5 分鐘原因產(chǎn)品側(cè)反饋過期時間過長等積累到一定數(shù)量還可以利用這段變更記錄做一次復盤看看哪些需求變更其實是前期評審沒想清楚導致的。這比單純把鍋甩給“產(chǎn)品需求又變了”更有價值。7.3 給 AI 設(shè)定“執(zhí)行上限”一個可以顯著減少返工的做法是每輪對話里限制 AI 的操作范圍。例如下面這種提示方式你只需要完成 Task 2不要修改除 UserService 之外的任何文件。如果發(fā)現(xiàn)需要改動其他文件先告知我再決定?！跋雀嬖V我再決定”這個約束非常有用。它能把 AI 從“全能執(zhí)行者”拉回“受限助手”的位置。AI 仍然可以發(fā)現(xiàn)潛在問題但決策權(quán)始終在開發(fā)者手里。7.4 每周或每個迭代做一次規(guī)格回顧如果你的團隊在長期維護一個 AI 輔助開發(fā)的項目可以每個迭代抽 30 分鐘做一次規(guī)格回顧哪些需求變更特別頻繁有沒有一個功能連續(xù)改了三次以上對應(yīng)規(guī)格文檔里第一次評審的結(jié)論是否存在偏差下一次如何提前規(guī)避這個過程不復雜但它能把“返工數(shù)據(jù)”轉(zhuǎn)化為下一輪迭代的輸入讓團隊逐漸減少無效返工。7.5 安全與數(shù)據(jù)合規(guī)提醒最后補充一點安全提醒。把需求描述、規(guī)格文檔、代碼上下文交給 AI 工具時注意不要包含以下內(nèi)容用戶真實手機號、郵箱等個人敏感信息數(shù)據(jù)庫連接字符串、密鑰、Token內(nèi)部安全策略細節(jié)未公開的商業(yè)邏輯。建議在項目里準備一套“脫敏模板”在把需求交給 AI 時把文檔中的真實用戶名、業(yè)務(wù)敏感字段替換成測試數(shù)據(jù)。同時注意AI 生成的代碼里有時會硬編碼一些路徑或密鑰提交前要做一次敏感信息掃描。8. 總結(jié)回到最初的問題AI 寫得越快為什么返工反而越多因為 AI 并不是在“理解需求后寫代碼”而是在“基于有限上下文做推斷”。當需求本身不夠具體、變化過程沒有記錄、驗證標準不夠清晰時AI 的高效只會讓錯誤方向上的代碼產(chǎn)出更快。Spec Kit 提供的是一種約束先評估、再規(guī)格化、再計劃、最后拆任務(wù)。它沒有增加太多復雜度卻能把“模糊需求”變成“可驗證的基線”讓 AI 每一次生成代碼之前都有一個明確的參照系。更重要的是它把需求變化從“重新描述一遍”變成“文檔追加一次變更”讓變化有記錄、有邊界、可追溯。如果你正在使用 AI 編程工具做稍大規(guī)模的功能開發(fā)我建議從下一個需求開始試試先在項目里建一個specs/目錄把需求評估、規(guī)格說明、實現(xiàn)計劃、任務(wù)清單四步走一遍。哪怕只做前兩步你也會發(fā)現(xiàn) AI 生成的代碼明顯比之前更接近你要的東西。希望這篇文章能幫你減少一些無效返工把 AI 的“快”真正轉(zhuǎn)化到有效交付上。