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