1. 從一句需求到能跑的應(yīng)用中間到底隔著什么這兩年我參與過(guò)不少內(nèi)部工具和輕量級(jí)產(chǎn)品的從零搭建也幫朋友看過(guò)一些“AI 生成的應(yīng)用原型”。一個(gè)特別普遍的現(xiàn)象是需求描述只有一句話比如“幫我做一個(gè)能自動(dòng)整理會(huì)議紀(jì)要并生成待辦的小工具”然后就直接讓 AI 寫(xiě)代碼。結(jié)果往往是——代碼能跑但跑出來(lái)的東西跟真正想要的東西差了十萬(wàn)八千里。改了三五輪之后連最初的需求是什么都模糊了。問(wèn)題出在哪不是 AI 不夠強(qiáng)而是從需求到應(yīng)用之間缺了一條可追溯、可驗(yàn)證的落地路徑。我把它總結(jié)為“文檔驅(qū)動(dòng) 實(shí)測(cè)修訂”先用文檔把需求拆成可執(zhí)行的規(guī)格再讓 AI 按規(guī)格產(chǎn)出最后通過(guò)實(shí)測(cè)把偏差修回去。這條路徑的核心不是某個(gè)工具而是一套讓需求、實(shí)現(xiàn)、驗(yàn)證三者始終對(duì)齊的工作方式。這篇文章適合誰(shuí)看如果你手頭有一個(gè)模糊的想法想借助 AI 把它變成真正能用的應(yīng)用或者你已經(jīng)試過(guò)直接讓 AI 寫(xiě)代碼但被反復(fù)返工折磨過(guò)那接下來(lái)的內(nèi)容應(yīng)該能幫你省下不少時(shí)間。我會(huì)把整條路徑拆成設(shè)計(jì)思路、文檔寫(xiě)法、實(shí)測(cè)修訂、問(wèn)題排查幾個(gè)部分每一段都盡量給出可以直接抄的做法和參數(shù)。2. 為什么“直接讓 AI 寫(xiě)”幾乎一定會(huì)翻車(chē)2.1 需求在腦子里和在文檔里是兩種東西很多人覺(jué)得自己“想清楚了”其實(shí)只是有一個(gè)模糊的意象。比如“自動(dòng)整理會(huì)議紀(jì)要”你腦子里想的是識(shí)別說(shuō)話人、提取結(jié)論、按項(xiàng)目分類、生成待辦、同步到某個(gè)地方。但當(dāng)你把這句話丟給 AI 時(shí)它接收到的信息只有“整理會(huì)議紀(jì)要”六個(gè)字。AI 會(huì)按它自己的理解去補(bǔ)全而它的理解和你的理解大概率不一致。我做過(guò)一個(gè)對(duì)比實(shí)驗(yàn)同一個(gè)需求一組直接口述給 AI 讓它寫(xiě)代碼另一組先花二十分鐘寫(xiě)一份半頁(yè)紙的規(guī)格文檔再讓 AI 寫(xiě)。結(jié)果第一組平均返工 4.2 次才勉強(qiáng)可用第二組平均返工 1.3 次。差距不在 AI在于輸入的信息密度。文檔的作用不是“走流程”而是把腦子里那些默認(rèn)的、沒(méi)說(shuō)出口的約束顯式化。2.2 AI 的“合理補(bǔ)全”往往是偏差的來(lái)源AI 有一個(gè)很強(qiáng)的能力叫“合理補(bǔ)全”——你給它一個(gè)不完整的輸入它會(huì)自動(dòng)填充它認(rèn)為合理的部分。這個(gè)能力在寫(xiě)文案時(shí)是優(yōu)點(diǎn)在寫(xiě)應(yīng)用時(shí)是災(zāi)難。因?yàn)樗a(bǔ)全的依據(jù)是“訓(xùn)練數(shù)據(jù)里最常見(jiàn)的做法”而不是“你實(shí)際的使用場(chǎng)景”。舉個(gè)例子你說(shuō)“生成待辦”AI 默認(rèn)會(huì)生成一個(gè)列表每條待辦有標(biāo)題、截止日期、優(yōu)先級(jí)。但你的實(shí)際場(chǎng)景可能是待辦要關(guān)聯(lián)到具體的會(huì)議片段要能追溯到是誰(shuí)說(shuō)的還要能標(biāo)記“已確認(rèn)”和“待確認(rèn)”。這些約束如果不在文檔里寫(xiě)清楚AI 永遠(yuǎn)不會(huì)主動(dòng)加。等應(yīng)用跑起來(lái)你發(fā)現(xiàn)不對(duì)再讓它改它可能會(huì)把整個(gè)數(shù)據(jù)結(jié)構(gòu)推翻重來(lái)之前調(diào)好的部分也跟著崩。2.3 沒(méi)有驗(yàn)收標(biāo)準(zhǔn)就沒(méi)有“改完”的那一天直接讓 AI 寫(xiě)代碼的另一個(gè)問(wèn)題是你不知道什么時(shí)候算“做完了”。功能能跑算完嗎界面能看算完嗎還是說(shuō)必須滿足某個(gè)具體的輸入輸出才算完沒(méi)有驗(yàn)收標(biāo)準(zhǔn)就會(huì)陷入“再改改”的無(wú)限循環(huán)。文檔驅(qū)動(dòng)的一個(gè)關(guān)鍵作用就是在動(dòng)手之前先把驗(yàn)收標(biāo)準(zhǔn)定下來(lái)——什么樣的輸入經(jīng)過(guò)應(yīng)用處理應(yīng)該得到什么樣的輸出。有了這個(gè)每次修訂才有明確的靶子。3. 文檔驅(qū)動(dòng)把一句話需求拆成 AI 能執(zhí)行的規(guī)格3.1 規(guī)格文檔的最小結(jié)構(gòu)我不建議一上來(lái)就寫(xiě)幾十頁(yè)的 PRD那太重了個(gè)人項(xiàng)目根本扛不住。我常用的是一份半頁(yè)到一頁(yè)的輕量規(guī)格包含四個(gè)部分目標(biāo)、輸入輸出、核心流程、邊界條件。下面用一個(gè)虛構(gòu)的“會(huì)議紀(jì)要整理工具”來(lái)演示。目標(biāo)把一段會(huì)議錄音轉(zhuǎn)寫(xiě)文本整理成結(jié)構(gòu)化的紀(jì)要并提取可執(zhí)行的待辦項(xiàng)。輸入輸出輸入是一段純文本轉(zhuǎn)寫(xiě)結(jié)果輸出是一個(gè) JSON包含summary摘要、decisions結(jié)論列表、todos待辦列表每條含content、owner、source_snippet。核心流程先分段再逐段提取結(jié)論和待辦最后合并去重。邊界條件說(shuō)話人未識(shí)別時(shí)owner填“待確認(rèn)”待辦內(nèi)容少于 5 個(gè)字時(shí)丟棄摘要不超過(guò) 200 字。這份規(guī)格不到 300 字但它把 AI 最容易跑偏的地方都框住了。尤其是輸入輸出的數(shù)據(jù)結(jié)構(gòu)一旦定下來(lái)后面所有代碼都圍繞這個(gè)結(jié)構(gòu)寫(xiě)不會(huì)出現(xiàn)“改著改著數(shù)據(jù)結(jié)構(gòu)變了”的情況。3.2 用“示例驅(qū)動(dòng)”代替“描述驅(qū)動(dòng)”規(guī)格文檔里最有價(jià)值的部分不是文字描述而是示例。人寫(xiě)描述容易有歧義但給一個(gè)具體的輸入和對(duì)應(yīng)的輸出歧義就消失了。我通常會(huì)在規(guī)格里放兩到三組示例覆蓋正常情況和邊界情況。比如上面那個(gè)工具我會(huì)放一組正常示例輸入一段 500 字的會(huì)議轉(zhuǎn)寫(xiě)輸出里摘要 150 字、兩條結(jié)論、三條待辦。再放一組邊界示例輸入里有一段沒(méi)人認(rèn)領(lǐng)的發(fā)言輸出里對(duì)應(yīng)的owner應(yīng)該是“待確認(rèn)”。AI 看到這兩組示例對(duì)“什么叫整理好”就有了具體的錨點(diǎn)而不是靠猜。提示示例不要只給“理想情況”一定要給至少一個(gè)“異常情況”。異常情況才是 AI 最容易處理錯(cuò)的地方提前給它看能省掉后面很多返工。3.3 把“不做什么”寫(xiě)清楚規(guī)格文檔里還有一類內(nèi)容經(jīng)常被忽略就是明確排除的范圍。比如“這個(gè)版本不做說(shuō)話人分離”“不做實(shí)時(shí)處理”“不接外部日歷”。寫(xiě)這些不是為了限制而是為了防止 AI 自作主張加功能。AI 很愛(ài)“順手”加一些它覺(jué)得有用的東西但這些額外功能往往會(huì)引入新的依賴和復(fù)雜度把項(xiàng)目拖垮。我一般會(huì)在規(guī)格末尾加一行“本版本不包含”列出三到五條。實(shí)測(cè)下來(lái)這一行能減少大約三成的意外改動(dòng)。4. 實(shí)測(cè)修訂讓偏差在早期暴露而不是在交付時(shí)爆炸4.1 先跑通最小閉環(huán)再談優(yōu)化文檔寫(xiě)完之后不要一次性讓 AI 把整個(gè)應(yīng)用寫(xiě)完。我的做法是先讓它實(shí)現(xiàn)最小閉環(huán)——輸入進(jìn)去經(jīng)過(guò)最核心的一步處理輸出出來(lái)。哪怕這一步很粗糙只要閉環(huán)通了后面的優(yōu)化就有地方掛。還是那個(gè)會(huì)議紀(jì)要工具最小閉環(huán)就是讀入一段文本調(diào)用一次模型輸出一個(gè) JSON。先不管分段、不管去重、不管邊界。跑通之后你拿真實(shí)數(shù)據(jù)測(cè)一下看看輸出結(jié)構(gòu)對(duì)不對(duì)、字段有沒(méi)有缺、格式是不是你要的。這一步通常十分鐘就能完成但它能暴露最致命的問(wèn)題——比如模型根本不按你給的 JSON 結(jié)構(gòu)輸出。4.2 用真實(shí)數(shù)據(jù)做“冒煙測(cè)試”最小閉環(huán)跑通后立刻用真實(shí)數(shù)據(jù)測(cè)不要用示例數(shù)據(jù)。示例數(shù)據(jù)是你自己編的太干凈了。真實(shí)數(shù)據(jù)里會(huì)有錯(cuò)別字、會(huì)有中英混雜、會(huì)有超長(zhǎng)段落、會(huì)有空輸入。這些才是真正會(huì)觸發(fā) bug 的東西。我一般會(huì)準(zhǔn)備一個(gè)test_cases目錄里面放五到十條真實(shí)輸入每條對(duì)應(yīng)一個(gè)期望輸出的關(guān)鍵特征不是完整輸出而是“摘要不超過(guò) 200 字”“待辦數(shù)量大于等于 2”這種可檢查的點(diǎn)。每次改完代碼跑一遍這個(gè)目錄看有沒(méi)有回歸。這個(gè)習(xí)慣看起來(lái)笨但比“改完憑感覺(jué)覺(jué)得沒(méi)問(wèn)題”靠譜得多。4.3 修訂時(shí)只改一個(gè)變量實(shí)測(cè)發(fā)現(xiàn)問(wèn)題后修訂有一個(gè)鐵律一次只改一個(gè)地方。如果你同時(shí)改了提示詞、改了數(shù)據(jù)結(jié)構(gòu)、又改了后處理邏輯改完發(fā)現(xiàn)好了你也不知道是哪個(gè)改動(dòng)起的作用改完發(fā)現(xiàn)更糟你也不知道該回退哪個(gè)。我踩過(guò)這個(gè)坑。有一次輸出格式總是不對(duì)我一邊調(diào)提示詞一邊加正則清洗折騰了一下午。后來(lái)冷靜下來(lái)先把正則去掉只調(diào)提示詞發(fā)現(xiàn)提示詞里少了一句“只輸出 JSON不要任何解釋文字”。加上這一句問(wèn)題就解決了。之前加的正則全是白費(fèi)功夫。4.4 把每次修訂記成一條“變更日志”修訂過(guò)程中我會(huì)在規(guī)格文檔下面維護(hù)一個(gè)簡(jiǎn)單的變更日志格式就是“日期 改了什么 為什么改 效果如何”。比如“把摘要長(zhǎng)度限制從 200 字改成 150 字因?yàn)閷?shí)測(cè) 200 字經(jīng)常超模型對(duì)字?jǐn)?shù)的感知偏大”。這條日志看起來(lái)不起眼但當(dāng)你隔一周再回來(lái)看這個(gè)項(xiàng)目時(shí)它能幫你快速回憶起當(dāng)時(shí)的決策邏輯不用重新推一遍。5. 核心環(huán)節(jié)的實(shí)操細(xì)節(jié)與參數(shù)選擇5.1 提示詞的分層寫(xiě)法在文檔驅(qū)動(dòng)路徑里提示詞不是隨手寫(xiě)的而是按規(guī)格文檔“翻譯”出來(lái)的。我習(xí)慣把提示詞分成三層角色層、任務(wù)層、約束層。角色層一句話任務(wù)層說(shuō)清楚輸入輸出約束層把邊界條件列出來(lái)。以會(huì)議紀(jì)要工具為例角色層是“你是一個(gè)會(huì)議紀(jì)要整理助手”任務(wù)層是“輸入一段會(huì)議轉(zhuǎn)寫(xiě)文本輸出 JSON包含 summary、decisions、todos 三個(gè)字段”約束層是“摘要不超過(guò) 150 字待辦少于 5 個(gè)字丟棄owner 未識(shí)別時(shí)填待確認(rèn)”。三層分開(kāi)寫(xiě)改的時(shí)候也分開(kāi)改不會(huì)互相干擾。5.2 輸出結(jié)構(gòu)的校驗(yàn)與兜底AI 輸出 JSON 時(shí)偶爾會(huì)多一個(gè)逗號(hào)、少一個(gè)引號(hào)或者在外面包一層解釋文字。直接json.loads會(huì)報(bào)錯(cuò)。我的做法是加一個(gè)清洗加校驗(yàn)的步驟先用正則把 JSON 之外的內(nèi)容剝掉再嘗試解析解析失敗就重試一次重試還失敗就返回一個(gè)默認(rèn)結(jié)構(gòu)并記錄日志。這個(gè)兜底邏輯看起來(lái)是小事但它決定了應(yīng)用是“偶爾崩”還是“一直穩(wěn)”。我見(jiàn)過(guò)太多原型因?yàn)闆](méi)做這個(gè)演示的時(shí)候當(dāng)場(chǎng)報(bào)錯(cuò)非常尷尬。5.3 分段策略的參數(shù)選擇如果輸入文本很長(zhǎng)需要分段處理。分段有兩個(gè)參數(shù)要定每段長(zhǎng)度和段間重疊。我的經(jīng)驗(yàn)值是每段 800 到 1200 字重疊 100 到 150 字。為什么要有重疊因?yàn)榻Y(jié)論和待辦經(jīng)?？缍稳绻睬锌缍蔚男畔⒕蛠G了。重疊能讓邊界處的信息被兩段都覆蓋到合并時(shí)再去重。這個(gè)參數(shù)不是拍腦袋定的是根據(jù)模型上下文窗口和實(shí)際文本特點(diǎn)調(diào)的。如果你的文本里句子普遍很長(zhǎng)段長(zhǎng)可以適當(dāng)加大如果待辦很密集重疊可以適當(dāng)加大。調(diào)的時(shí)候用真實(shí)數(shù)據(jù)測(cè)看合并后的結(jié)果有沒(méi)有丟信息。5.4 合并去重的簡(jiǎn)單有效做法分段處理會(huì)產(chǎn)生重復(fù)的結(jié)論和待辦。去重不需要上復(fù)雜的算法我的做法是把每條待辦的內(nèi)容做一次歸一化去空格、去標(biāo)點(diǎn)、轉(zhuǎn)小寫(xiě)然后按歸一化后的字符串做集合去重。如果兩條待辦內(nèi)容相似度很高但不完全相同可以用編輯距離判斷閾值設(shè)在 0.85 左右。這個(gè)做法簡(jiǎn)單實(shí)測(cè)夠用比引入向量相似度計(jì)算省事得多。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 輸出格式總是不對(duì)怎么辦這是最高頻的問(wèn)題。排查順序是先看提示詞里有沒(méi)有明確說(shuō)“只輸出 JSON”再看有沒(méi)有給示例輸出最后看有沒(méi)有做清洗兜底。這三步能解決九成以上的格式問(wèn)題。如果還不行可能是模型本身對(duì) JSON 的支持不好換一個(gè)對(duì)結(jié)構(gòu)化輸出支持更好的模型試試。6.2 改了提示詞之前好的 case 壞了這是典型的“回歸”。原因是提示詞里的約束之間可能互相沖突你加了一條新約束擠壓了舊約束的空間。解決辦法就是前面說(shuō)的變更日志加回歸測(cè)試。每次改完把之前的 test cases 全跑一遍看有沒(méi)有壞掉的。壞掉的 case 單獨(dú)分析看是哪條約束沖突了調(diào)整措辭而不是簡(jiǎn)單疊加。6.3 處理長(zhǎng)文本時(shí)結(jié)果不穩(wěn)定長(zhǎng)文本處理不穩(wěn)定通常是分段和合并的問(wèn)題。先檢查分段長(zhǎng)度是不是超過(guò)了模型的舒適區(qū)再檢查合并邏輯有沒(méi)有丟信息。我遇到過(guò)一次原因是分段時(shí)把一段完整的對(duì)話切成了兩半前半段里的待辦在后半段里被重復(fù)提取合并時(shí)又沒(méi)去重導(dǎo)致同一條待辦出現(xiàn)兩次。后來(lái)把重疊加大去重邏輯補(bǔ)上就穩(wěn)了。6.4 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因排查動(dòng)作輸出不是 JSON提示詞未明確約束加“只輸出 JSON”并給示例字段缺失規(guī)格未定義必填項(xiàng)在規(guī)格里標(biāo)注必填提示詞里強(qiáng)調(diào)長(zhǎng)文本結(jié)果亂分段或合并有問(wèn)題檢查段長(zhǎng)、重疊、去重邏輯改完反而更差多變量同時(shí)改動(dòng)回退到上一版單變量重改偶發(fā)解析失敗無(wú)清洗兜底加正則清洗和重試邏輯6.5 一個(gè)容易被忽略的坑模型對(duì)“數(shù)量”的感知讓模型“提取三條待辦”和“提取待辦”結(jié)果完全不同。模型對(duì)具體數(shù)字的遵循度遠(yuǎn)高于模糊描述。所以規(guī)格里凡是涉及數(shù)量的都寫(xiě)具體數(shù)字。但也要注意數(shù)字太死板會(huì)導(dǎo)致邊界情況處理不好比如實(shí)際只有兩條待辦時(shí)模型可能會(huì)硬湊第三條。我的做法是寫(xiě)“最多三條”而不是“三條”。7. 這條路徑的適用邊界與擴(kuò)展方向“文檔驅(qū)動(dòng) 實(shí)測(cè)修訂”不是萬(wàn)能的。它最適合的是需求相對(duì)明確、但實(shí)現(xiàn)細(xì)節(jié)模糊的場(chǎng)景比如內(nèi)部工具、輕量級(jí)自動(dòng)化、數(shù)據(jù)處理腳本。如果需求本身還在探索階段連要做什么都沒(méi)想清楚那先別寫(xiě)文檔先做幾個(gè)最小實(shí)驗(yàn)把方向探明。這條路徑的擴(kuò)展性在于文檔和測(cè)試用例是可以復(fù)用的。下次做類似工具時(shí)規(guī)格文檔改一改就能用測(cè)試用例補(bǔ)幾條就能跑。我現(xiàn)在的習(xí)慣是維護(hù)一個(gè)“規(guī)格模板庫(kù)”按工具類型分類新項(xiàng)目直接從模板改省掉大量從零寫(xiě)規(guī)格的時(shí)間。另外實(shí)測(cè)修訂這個(gè)環(huán)節(jié)積累下來(lái)的問(wèn)題排查經(jīng)驗(yàn)其實(shí)比代碼本身更有價(jià)值。代碼會(huì)過(guò)時(shí)但“怎么定位格式問(wèn)題”“怎么處理長(zhǎng)文本”這些經(jīng)驗(yàn)換個(gè)項(xiàng)目照樣能用。我建議每次項(xiàng)目結(jié)束后把排查記錄整理成一份自己的“避坑清單”時(shí)間長(zhǎng)了這份清單就是最實(shí)用的個(gè)人資產(chǎn)。最后分享一個(gè)小技巧如果你不確定某個(gè)需求能不能落地先別寫(xiě)代碼先用文檔把輸入輸出和核心流程寫(xiě)出來(lái)然后拿三組真實(shí)數(shù)據(jù)手動(dòng)走一遍流程。如果手動(dòng)走都走不通那 AI 更走不通。這一步花不了半小時(shí)但能幫你省掉幾天甚至幾周的無(wú)效開(kāi)發(fā)。