1. 從一句模糊需求到能跑的應(yīng)用中間到底隔著什么這兩年我參與過不少“把想法變成應(yīng)用”的項目有幫朋友做的小工具也有團(tuán)隊內(nèi)部孵化的效率產(chǎn)品。一個很明顯的感受是AI 把“寫代碼”這件事的門檻拉低了但把“把需求真正落地”這件事的難度反而暴露得更徹底了。以前大家卡在不會寫代碼現(xiàn)在代碼能生成了卡點轉(zhuǎn)移到了另外幾個地方——需求本身說不清楚、生成出來的東西對不上真實場景、改著改著就失控、最后沒人敢上線。我見過太多這樣的場景某位同學(xué)興沖沖地說“我要做一個能自動整理會議紀(jì)要的應(yīng)用”然后打開 AI 對話窗口噼里啪啦生成了一堆代碼跑起來發(fā)現(xiàn)連輸入格式都沒定義清楚更別提什么“自動整理”到底整理成什么樣。折騰兩天熱情耗盡項目擱置。問題不在于 AI 不行而在于從“一個念頭”到“一個能用的應(yīng)用”之間缺了一條可執(zhí)行的路徑。這篇文章想聊的就是我自己反復(fù)驗證過的一條路徑文檔驅(qū)動 實測修訂。核心思路很樸素——先把需求寫成文檔讓文檔成為唯一的“事實來源”然后基于文檔生成代碼再用真實測試去反向修訂文檔和代碼循環(huán)往復(fù)直到應(yīng)用真正可用。它解決的不是“怎么寫代碼”而是“怎么保證寫出來的東西是對的”。適合所有手里有個想法、想把它變成應(yīng)用但又不確定從哪下手的人不管你是剛?cè)腴T的新手還是已經(jīng)能寫點代碼但總在落地環(huán)節(jié)翻車的開發(fā)者。我把它拆成四個部分來講整體設(shè)計思路、文檔驅(qū)動的核心細(xì)節(jié)、實測修訂的完整流程、以及踩坑排查的實錄。每一部分都盡量給到能直接抄作業(yè)的步驟和參數(shù)而不是泛泛而談。2. 整體設(shè)計思路為什么是“文檔驅(qū)動 實測修訂”2.1 先想清楚AI 時代落地的真正瓶頸在哪很多人以為 AI 時代做應(yīng)用的瓶頸是“技術(shù)實現(xiàn)”其實不是。我做過一個粗略的統(tǒng)計在自己經(jīng)手的十幾個小項目里真正花在“寫代碼”上的時間不到三成剩下七成全部消耗在需求澄清、方案對齊、測試驗證和反復(fù)修訂上。AI 能幫你把這三成壓縮到一成甚至更少但如果你沒有一套方法去處理那七成整體效率反而可能下降——因為生成速度太快錯誤積累得也快。舉個具體的例子。假設(shè)你要做一個“批量重命名文件”的小工具。需求聽起來一句話就說完了但真正落地時你會發(fā)現(xiàn)一堆沒定義的東西重命名規(guī)則是前綴、后綴還是替換要不要保留原擴(kuò)展名遇到重名怎么辦要不要支持撤銷這些如果不在文檔里寫清楚AI 生成出來的代碼大概率只覆蓋了你腦子里想的那一種情況剩下全是坑。所以我的判斷是AI 時代落地的瓶頸從“實現(xiàn)能力”轉(zhuǎn)移到了“定義能力”和“驗證能力”。文檔驅(qū)動解決定義問題實測修訂解決驗證問題。這兩件事做好了AI 才能真正成為加速器而不是混亂制造機(jī)。2.2 文檔驅(qū)動讓“事實來源”只有一個文檔驅(qū)動的核心思想是把所有關(guān)于這個應(yīng)用“應(yīng)該是什么樣”的信息全部收斂到一份文檔里。這份文檔不是寫給領(lǐng)導(dǎo)看的匯報材料也不是產(chǎn)品經(jīng)理那種幾十頁的 PRD而是一份給 AI 看、也給自己看的“施工圖”。為什么強(qiáng)調(diào)“唯一事實來源”因為在實際操作中最容易出亂子的地方就是信息不一致。你腦子里想的是一個版本跟 AI 描述的是另一個版本生成出來的代碼是第三個版本測試的時候又發(fā)現(xiàn)跟預(yù)期不符。三個版本互相打架你根本不知道改哪里。文檔驅(qū)動就是強(qiáng)制你把它們統(tǒng)一起來文檔寫什么AI 就生成什么測試發(fā)現(xiàn)不對先改文檔再改代碼。我自己的文檔模板通常包含這幾塊一句話目標(biāo)這個應(yīng)用到底解決什么問題一句話說清楚。輸入輸出定義用戶給什么應(yīng)用返回什么格式是什么。核心功能列表按優(yōu)先級排列哪些必須有哪些可以后加。邊界與異常什么情況下不處理出錯時怎么反饋。驗收標(biāo)準(zhǔn)怎么算做完了用什么測試用例來驗證。這份文檔不需要很長我做過的最小版本只有半頁紙但它必須是可執(zhí)行的——每一條都能對應(yīng)到具體的代碼行為或測試用例。寫不清楚的地方就是還沒想清楚的地方這時候不要急著讓 AI 生成代碼先把文檔補(bǔ)完。2.3 實測修訂用真實反饋反向驅(qū)動文檔寫得再好也只是假設(shè)。實測修訂就是把這個假設(shè)放到真實環(huán)境里跑一遍用實際結(jié)果去修正文檔和代碼。這里的關(guān)鍵是“實測”兩個字——不是自己隨便點兩下看看而是要有明確的測試用例和預(yù)期結(jié)果。我的做法是在文檔的“驗收標(biāo)準(zhǔn)”部分直接寫好一組測試用例每條包含輸入、預(yù)期輸出、實際輸出三列。生成代碼后逐條跑一遍對不上的地方先判斷是文檔寫錯了還是代碼寫錯了。如果是文檔寫錯了改文檔如果是代碼沒按文檔來改代碼。改完再跑直到全部通過。這個循環(huán)聽起來很笨但實測下來非常穩(wěn)。因為它把“我覺得應(yīng)該沒問題”變成了“我驗證過沒問題”。AI 生成的東西最大的風(fēng)險就是看起來對、跑起來錯而實測修訂就是專門治這個的。2.4 這套路徑適合誰不適合誰說句實在話這套方法不是萬能的。它適合那些需求相對明確、可以拆成小步驟、有明確輸入輸出的應(yīng)用比如小工具、腳本、內(nèi)部效率應(yīng)用、原型驗證。它不太適合那種需求本身就在劇烈變化、或者需要大量主觀判斷的項目比如創(chuàng)意類產(chǎn)品、強(qiáng)交互的復(fù)雜前端。另外它對使用者的要求是你得愿意花時間寫文檔、跑測試。如果你只想“一句話讓 AI 生成一個完整應(yīng)用”那這套方法可能會讓你覺得麻煩。但根據(jù)我的經(jīng)驗省下來的返工時間遠(yuǎn)遠(yuǎn)超過寫文檔花的時間。3. 文檔驅(qū)動的核心細(xì)節(jié)一份能直接喂給 AI 的施工圖3.1 文檔的四個必備模塊少一個都會翻車我把文檔拆成四個模塊每個模塊都有明確的用途缺一個都會在后續(xù)環(huán)節(jié)出問題。第一個模塊是目標(biāo)與范圍。這里要寫清楚三件事這個應(yīng)用是給誰用的、解決什么問題、不解決什么問題。最后一條特別重要因為 AI 很容易“過度發(fā)揮”你讓它做個計算器它可能給你加上歷史記錄、主題切換、導(dǎo)出功能。明確寫出“本期不做”的清單能省掉大量無用功。第二個模塊是輸入輸出契約。這是整個文檔里最需要精確的部分。輸入是什么類型、什么格式、有沒有默認(rèn)值、允不允許為空輸出是什么結(jié)構(gòu)、什么類型、錯誤時返回什么。我習(xí)慣用表格來寫一目了然。項目類型必填說明輸入文件路徑字符串是支持絕對路徑和相對路徑重命名規(guī)則字符串是支持 prefix、suffix、replace 三種是否保留擴(kuò)展名布爾否默認(rèn) true重名處理策略字符串否默認(rèn) skip可選 overwrite、rename第三個模塊是核心功能列表。按優(yōu)先級排用 P0、P1、P2 標(biāo)注。P0 是必須有的沒有就不算完成P1 是重要的但可以稍后P2 是錦上添花。這樣在時間和精力有限時你知道先保什么。第四個模塊是驗收標(biāo)準(zhǔn)。這是實測修訂的依據(jù)。每條標(biāo)準(zhǔn)都要可驗證不能寫“運行流暢”這種沒法測的話。我通常直接寫成測試用例的形式后面會詳細(xì)講。3.2 怎么把模糊需求翻譯成可執(zhí)行文檔這是很多人卡住的地方腦子里有個想法但不知道怎么寫成文檔。我的經(jīng)驗是用“追問法”把模糊需求一層層剝開。拿“自動整理會議紀(jì)要”這個需求舉例。第一層追問輸入是什么是錄音、文字記錄還是聊天記錄第二層整理成什么是摘要、待辦列表還是結(jié)構(gòu)化紀(jì)要第三層輸出給誰看是給自己回顧還是發(fā)給團(tuán)隊第四層什么算整理好了是覆蓋所有要點還是只抓關(guān)鍵決策每追問一層需求就清晰一分。追問到你能寫出具體的輸入輸出和驗收標(biāo)準(zhǔn)時文檔就差不多了。這個過程我通常會借助 AI 來加速——把模糊需求丟給 AI讓它幫我列出所有需要澄清的問題然后我逐個回答。這比我自己想快得多而且不容易漏。提示追問法的一個實用技巧是假設(shè)你要把這個應(yīng)用交給一個完全不了解背景的人去實現(xiàn)他需要知道哪些信息才能做對。把這些信息寫下來就是文檔的雛形。3.3 文檔寫完后先做一次“自檢”文檔寫完不要急著生成代碼先做一次自檢。我通常檢查這幾項有沒有互相矛盾的地方比如輸入定義說必填但異常處理里又說可以為空。有沒有無法驗證的標(biāo)準(zhǔn)比如“界面美觀”這種沒法測的。有沒有遺漏的邊界情況比如輸入為空、輸入超長、輸入格式錯誤。優(yōu)先級是否清晰P0 是不是真的必須P2 是不是可以砍。自檢通過后我會把文檔再給 AI 看一遍讓它指出可能的問題。AI 有時候能發(fā)現(xiàn)我自己沒注意到的邏輯漏洞比如某個功能依賴另一個功能但優(yōu)先級排反了。這一步花不了幾分鐘但能省掉后面大量返工。3.4 文檔的版本管理別小看這件事文檔驅(qū)動的一個前提是文檔會不斷修訂。如果沒有版本管理改著改著就亂了你不知道哪版是最新的也不知道某次改動是為了什么。我的做法很簡單用 Git 管理文檔每次修訂都寫清楚改了什么、為什么改。如果不用 Git至少也要在文檔里保留一個修訂記錄表。版本日期修改內(nèi)容原因v1.0某日初版需求澄清完成v1.1某日增加重名處理策略測試發(fā)現(xiàn)重名會覆蓋v1.2某日調(diào)整輸出格式實際使用中發(fā)現(xiàn)不便這個習(xí)慣看起來麻煩但在實測修訂階段會救你很多次。因為當(dāng)你發(fā)現(xiàn)某個問題反復(fù)出現(xiàn)時翻修訂記錄往往能找到根源——可能是某次改動引入的也可能是某個假設(shè)一直沒驗證。4. 實測修訂的完整流程從生成代碼到真正可用4.1 基于文檔生成代碼的正確姿勢文檔準(zhǔn)備好之后生成代碼這一步反而簡單了。但有幾個細(xì)節(jié)要注意不然生成出來的東西還是要大改。第一分段生成不要一次性生成整個應(yīng)用。我通常按功能模塊來先讓 AI 生成 P0 功能跑通后再加 P1。一次性生成太多出了問題很難定位是哪塊的。第二把文檔的相關(guān)部分直接貼給 AI而不是只給一句話描述。比如生成重命名功能時把輸入輸出契約和重命名規(guī)則那部分完整貼過去AI 生成的代碼會準(zhǔn)確得多。第三要求 AI 同時生成測試代碼。我通常會說“請為這個功能生成對應(yīng)的測試用例覆蓋正常情況和邊界情況”。這樣測試用例和功能代碼一起出來省得自己再寫。第四生成后先看代碼結(jié)構(gòu)再跑測試。AI 生成的代碼有時候結(jié)構(gòu)混亂比如把所有邏輯塞在一個函數(shù)里。這時候先讓它重構(gòu)比后面改 bug 更省事。4.2 測試用例怎么寫才能真正發(fā)現(xiàn)問題測試用例的質(zhì)量直接決定實測修訂的效果。我的經(jīng)驗是測試用例要覆蓋四類情況正常路徑最常見的輸入預(yù)期輸出是什么。邊界情況輸入為空、輸入超長、輸入剛好在臨界值。異常情況輸入格式錯誤、文件不存在、權(quán)限不足。組合情況多個參數(shù)同時變化比如重命名規(guī)則和重名策略的不同組合。寫測試用例時我習(xí)慣用表格來組織每條包含編號、輸入、預(yù)期輸出、實際輸出、是否通過。實際輸出那一列在跑測試時填對不上的標(biāo)紅然后逐條排查。編號輸入預(yù)期輸出實際輸出通過T01正常文件prefix 規(guī)則文件名加前綴待填待填T02空路徑報錯提示待填待填T03重名文件skip 策略跳過并提示待填待填T04重名文件overwrite 策略覆蓋原文件待填待填注意測試用例不要只寫“正常情況”邊界和異常才是 bug 的高發(fā)區(qū)。我踩過的坑里至少一半是邊界情況沒考慮到。4.3 實測修訂的循環(huán)改文檔還是改代碼跑完測試后對不上的地方要判斷是文檔問題還是代碼問題。我的判斷標(biāo)準(zhǔn)很簡單如果代碼行為符合文檔但結(jié)果不符合預(yù)期那是文檔寫錯了改文檔。如果代碼行為不符合文檔那是代碼寫錯了改代碼。如果文檔和代碼都符合但實際使用中還是有問題那是需求本身沒想清楚回到文檔重新澄清。這個判斷很重要因為很多人一發(fā)現(xiàn)不對就改代碼結(jié)果改來改去文檔和代碼越來越不一致最后文檔徹底失效。堅持“先判斷再改”能保證文檔始終是有效的事實來源。改完之后重新跑測試直到全部通過。然后進(jìn)入下一輪加新功能、加新測試用例、再跑、再改。每一輪都保持文檔和代碼同步這樣項目再大也不會失控。4.4 什么時候算“可以用了”這個問題沒有絕對標(biāo)準(zhǔn)但我的經(jīng)驗是當(dāng)滿足這三個條件時就可以算“可以用了”第一所有 P0 功能的測試用例全部通過包括邊界和異常情況。第二實際用真實數(shù)據(jù)跑過至少一遍沒有出現(xiàn)測試用例沒覆蓋到的問題。第三你自己愿意把它推薦給別人用而不是“勉強(qiáng)能用”。達(dá)到這三個條件后再考慮 P1、P2 功能。不要一開始就追求完美先把核心跑通再逐步完善。我見過太多項目死在“想一次做完”上其實分階段落地每一步都能用反而走得更遠(yuǎn)。5. 常見問題與排查技巧實錄5.1 文檔寫不下去怎么辦這是最常見的問題。寫著寫著發(fā)現(xiàn)需求本身就不清楚或者越寫越復(fù)雜。我的處理方式是先寫最小可用的文檔只覆蓋 P0 功能其他先不寫。把 P0 跑通后再回來補(bǔ) P1、P2。這樣不會一開始就被復(fù)雜度壓垮。另一個技巧是把文檔當(dāng)成“給 AI 的指令”來寫而不是“給人看的說明”。給 AI 的指令要具體、可執(zhí)行這反過來會逼你把需求想清楚。5.2 AI 生成的代碼跑不起來先別急著改代碼先檢查三件事依賴裝了嗎、環(huán)境對嗎、輸入格式符合文檔嗎。我遇到的大部分“跑不起來”其實是環(huán)境問題或輸入問題不是代碼邏輯問題。如果這三項都沒問題再把錯誤信息完整貼給 AI讓它分析。注意要貼完整的錯誤堆棧不要只貼最后一行不然 AI 很難定位。5.3 測試通過了但實際用還是有問題這說明測試用例覆蓋不夠。我的做法是把實際使用中遇到的問題直接轉(zhuǎn)化成新的測試用例加進(jìn)文檔里。這樣下次再改代碼時這個問題就不會復(fù)現(xiàn)。實測修訂的核心就是不斷把真實問題轉(zhuǎn)化為測試用例讓測試集越來越貼近實際。5.4 改著改著文檔和代碼不一致了這是沒有堅持“先判斷再改”的后果。補(bǔ)救方法是以當(dāng)前代碼的實際行為為準(zhǔn)反向更新文檔然后重新跑一遍測試確認(rèn)文檔和代碼一致。之后嚴(yán)格按流程走每次改動都先判斷是改文檔還是改代碼。5.5 常見問題速查表問題可能原因排查方向代碼跑不起來依賴、環(huán)境、輸入格式先檢查這三項再看邏輯測試通過但實際有問題測試覆蓋不足把實際問題轉(zhuǎn)為測試用例文檔代碼不一致改動時沒同步以代碼為準(zhǔn)反向更新文檔需求越寫越復(fù)雜想一次做完先做 P0分階段落地AI 生成代碼結(jié)構(gòu)混亂一次性生成太多分段生成先重構(gòu)再改 bug5.6 幾個我踩過的坑第一個坑是文檔寫得太抽象。早期我寫“輸出要友好”結(jié)果 AI 生成的東西完全不是我想要的。后來改成“輸出格式為 JSON包含 status 和 message 兩個字段”問題就解決了。文檔越具體AI 越不會跑偏。第二個坑是測試用例只寫正常情況。有一次做文件處理工具正常情況全過結(jié)果用戶輸入了一個空文件直接崩潰。后來補(bǔ)了邊界測試才發(fā)現(xiàn)問題。邊界和異常永遠(yuǎn)是 bug 的重災(zāi)區(qū)。第三個坑是改代碼不改文檔。有次為了趕時間直接改了代碼沒更新文檔結(jié)果過兩天自己都忘了為什么這么改再想加功能時完全對不上。從那以后我堅持每次改動都同步文檔哪怕只改一行。第四個坑是一次性生成整個應(yīng)用。剛開始用 AI 時我總想一句話生成完整應(yīng)用結(jié)果生成出來的東西結(jié)構(gòu)混亂改都沒法改。后來改成按模塊生成每個模塊跑通再合并效率反而高得多。6. 這套路徑的延展與個人體會這套“文檔驅(qū)動 實測修訂”的路徑不只適用于小工具也可以用在更大的項目上。區(qū)別只在于文檔的詳細(xì)程度和測試用例的覆蓋范圍。項目越大文檔和測試的價值越高因為靠腦子記不住那么多細(xì)節(jié)。我后來把這套方法用在了團(tuán)隊協(xié)作上效果也很明顯。文檔成為團(tuán)隊共識的基礎(chǔ)測試用例成為驗收的標(biāo)準(zhǔn)AI 生成的代碼有了明確的約束。大家不用再反復(fù)口頭對齊看文檔就行不用再爭論“算不算做完”跑測試就行。如果你手里正好有個想法想把它變成應(yīng)用我的建議是先別急著打開 AI 對話窗口先花半小時把文檔寫出來。哪怕只有半頁紙只要包含目標(biāo)、輸入輸出、核心功能和驗收標(biāo)準(zhǔn)你后面的路就會順很多。寫文檔的時間永遠(yuǎn)比返工的時間短。最后分享一個小技巧每次實測修訂后把這次遇到的問題和解決方法記在文檔的修訂記錄里。積累下來這就是你自己的“避坑手冊”下次做類似項目時翻一翻能省掉大量重復(fù)踩坑的時間。這個習(xí)慣我堅持了兩年現(xiàn)在做新項目時很多問題在文檔階段就能提前規(guī)避。