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