1. 从一句需求到能跑的应用中间到底隔着什么这两年我参与过不少内部工具和轻量级产品的从零搭建也帮朋友看过一些“AI 生成的应用原型”。一个特别普遍的现象是需求描述只有一句话比如“帮我做一个能自动整理会议纪要并生成待办的小工具”然后就直接让 AI 写代码。结果往往是——代码能跑但跑出来的东西跟真正想要的东西差了十万八千里。改了三五轮之后连最初的需求是什么都模糊了。问题出在哪不是 AI 不够强而是从需求到应用之间缺了一条可追溯、可验证的落地路径。我把它总结为“文档驱动 实测修订”先用文档把需求拆成可执行的规格再让 AI 按规格产出最后通过实测把偏差修回去。这条路径的核心不是某个工具而是一套让需求、实现、验证三者始终对齐的工作方式。这篇文章适合谁看如果你手头有一个模糊的想法想借助 AI 把它变成真正能用的应用或者你已经试过直接让 AI 写代码但被反复返工折磨过那接下来的内容应该能帮你省下不少时间。我会把整条路径拆成设计思路、文档写法、实测修订、问题排查几个部分每一段都尽量给出可以直接抄的做法和参数。2. 为什么“直接让 AI 写”几乎一定会翻车2.1 需求在脑子里和在文档里是两种东西很多人觉得自己“想清楚了”其实只是有一个模糊的意象。比如“自动整理会议纪要”你脑子里想的是识别说话人、提取结论、按项目分类、生成待办、同步到某个地方。但当你把这句话丢给 AI 时它接收到的信息只有“整理会议纪要”六个字。AI 会按它自己的理解去补全而它的理解和你的理解大概率不一致。我做过一个对比实验同一个需求一组直接口述给 AI 让它写代码另一组先花二十分钟写一份半页纸的规格文档再让 AI 写。结果第一组平均返工 4.2 次才勉强可用第二组平均返工 1.3 次。差距不在 AI在于输入的信息密度。文档的作用不是“走流程”而是把脑子里那些默认的、没说出口的约束显式化。2.2 AI 的“合理补全”往往是偏差的来源AI 有一个很强的能力叫“合理补全”——你给它一个不完整的输入它会自动填充它认为合理的部分。这个能力在写文案时是优点在写应用时是灾难。因为它补全的依据是“训练数据里最常见的做法”而不是“你实际的使用场景”。举个例子你说“生成待办”AI 默认会生成一个列表每条待办有标题、截止日期、优先级。但你的实际场景可能是待办要关联到具体的会议片段要能追溯到是谁说的还要能标记“已确认”和“待确认”。这些约束如果不在文档里写清楚AI 永远不会主动加。等应用跑起来你发现不对再让它改它可能会把整个数据结构推翻重来之前调好的部分也跟着崩。2.3 没有验收标准就没有“改完”的那一天直接让 AI 写代码的另一个问题是你不知道什么时候算“做完了”。功能能跑算完吗界面能看算完吗还是说必须满足某个具体的输入输出才算完没有验收标准就会陷入“再改改”的无限循环。文档驱动的一个关键作用就是在动手之前先把验收标准定下来——什么样的输入经过应用处理应该得到什么样的输出。有了这个每次修订才有明确的靶子。3. 文档驱动把一句话需求拆成 AI 能执行的规格3.1 规格文档的最小结构我不建议一上来就写几十页的 PRD那太重了个人项目根本扛不住。我常用的是一份半页到一页的轻量规格包含四个部分目标、输入输出、核心流程、边界条件。下面用一个虚构的“会议纪要整理工具”来演示。目标把一段会议录音转写文本整理成结构化的纪要并提取可执行的待办项。输入输出输入是一段纯文本转写结果输出是一个 JSON包含summary摘要、decisions结论列表、todos待办列表每条含content、owner、source_snippet。核心流程先分段再逐段提取结论和待办最后合并去重。边界条件说话人未识别时owner填“待确认”待办内容少于 5 个字时丢弃摘要不超过 200 字。这份规格不到 300 字但它把 AI 最容易跑偏的地方都框住了。尤其是输入输出的数据结构一旦定下来后面所有代码都围绕这个结构写不会出现“改着改着数据结构变了”的情况。3.2 用“示例驱动”代替“描述驱动”规格文档里最有价值的部分不是文字描述而是示例。人写描述容易有歧义但给一个具体的输入和对应的输出歧义就消失了。我通常会在规格里放两到三组示例覆盖正常情况和边界情况。比如上面那个工具我会放一组正常示例输入一段 500 字的会议转写输出里摘要 150 字、两条结论、三条待办。再放一组边界示例输入里有一段没人认领的发言输出里对应的owner应该是“待确认”。AI 看到这两组示例对“什么叫整理好”就有了具体的锚点而不是靠猜。提示示例不要只给“理想情况”一定要给至少一个“异常情况”。异常情况才是 AI 最容易处理错的地方提前给它看能省掉后面很多返工。3.3 把“不做什么”写清楚规格文档里还有一类内容经常被忽略就是明确排除的范围。比如“这个版本不做说话人分离”“不做实时处理”“不接外部日历”。写这些不是为了限制而是为了防止 AI 自作主张加功能。AI 很爱“顺手”加一些它觉得有用的东西但这些额外功能往往会引入新的依赖和复杂度把项目拖垮。我一般会在规格末尾加一行“本版本不包含”列出三到五条。实测下来这一行能减少大约三成的意外改动。4. 实测修订让偏差在早期暴露而不是在交付时爆炸4.1 先跑通最小闭环再谈优化文档写完之后不要一次性让 AI 把整个应用写完。我的做法是先让它实现最小闭环——输入进去经过最核心的一步处理输出出来。哪怕这一步很粗糙只要闭环通了后面的优化就有地方挂。还是那个会议纪要工具最小闭环就是读入一段文本调用一次模型输出一个 JSON。先不管分段、不管去重、不管边界。跑通之后你拿真实数据测一下看看输出结构对不对、字段有没有缺、格式是不是你要的。这一步通常十分钟就能完成但它能暴露最致命的问题——比如模型根本不按你给的 JSON 结构输出。4.2 用真实数据做“冒烟测试”最小闭环跑通后立刻用真实数据测不要用示例数据。示例数据是你自己编的太干净了。真实数据里会有错别字、会有中英混杂、会有超长段落、会有空输入。这些才是真正会触发 bug 的东西。我一般会准备一个test_cases目录里面放五到十条真实输入每条对应一个期望输出的关键特征不是完整输出而是“摘要不超过 200 字”“待办数量大于等于 2”这种可检查的点。每次改完代码跑一遍这个目录看有没有回归。这个习惯看起来笨但比“改完凭感觉觉得没问题”靠谱得多。4.3 修订时只改一个变量实测发现问题后修订有一个铁律一次只改一个地方。如果你同时改了提示词、改了数据结构、又改了后处理逻辑改完发现好了你也不知道是哪个改动起的作用改完发现更糟你也不知道该回退哪个。我踩过这个坑。有一次输出格式总是不对我一边调提示词一边加正则清洗折腾了一下午。后来冷静下来先把正则去掉只调提示词发现提示词里少了一句“只输出 JSON不要任何解释文字”。加上这一句问题就解决了。之前加的正则全是白费功夫。4.4 把每次修订记成一条“变更日志”修订过程中我会在规格文档下面维护一个简单的变更日志格式就是“日期 改了什么 为什么改 效果如何”。比如“把摘要长度限制从 200 字改成 150 字因为实测 200 字经常超模型对字数的感知偏大”。这条日志看起来不起眼但当你隔一周再回来看这个项目时它能帮你快速回忆起当时的决策逻辑不用重新推一遍。5. 核心环节的实操细节与参数选择5.1 提示词的分层写法在文档驱动路径里提示词不是随手写的而是按规格文档“翻译”出来的。我习惯把提示词分成三层角色层、任务层、约束层。角色层一句话任务层说清楚输入输出约束层把边界条件列出来。以会议纪要工具为例角色层是“你是一个会议纪要整理助手”任务层是“输入一段会议转写文本输出 JSON包含 summary、decisions、todos 三个字段”约束层是“摘要不超过 150 字待办少于 5 个字丢弃owner 未识别时填待确认”。三层分开写改的时候也分开改不会互相干扰。5.2 输出结构的校验与兜底AI 输出 JSON 时偶尔会多一个逗号、少一个引号或者在外面包一层解释文字。直接json.loads会报错。我的做法是加一个清洗加校验的步骤先用正则把 JSON 之外的内容剥掉再尝试解析解析失败就重试一次重试还失败就返回一个默认结构并记录日志。这个兜底逻辑看起来是小事但它决定了应用是“偶尔崩”还是“一直稳”。我见过太多原型因为没做这个演示的时候当场报错非常尴尬。5.3 分段策略的参数选择如果输入文本很长需要分段处理。分段有两个参数要定每段长度和段间重叠。我的经验值是每段 800 到 1200 字重叠 100 到 150 字。为什么要有重叠因为结论和待办经常跨段如果硬切跨段的信息就丢了。重叠能让边界处的信息被两段都覆盖到合并时再去重。这个参数不是拍脑袋定的是根据模型上下文窗口和实际文本特点调的。如果你的文本里句子普遍很长段长可以适当加大如果待办很密集重叠可以适当加大。调的时候用真实数据测看合并后的结果有没有丢信息。5.4 合并去重的简单有效做法分段处理会产生重复的结论和待办。去重不需要上复杂的算法我的做法是把每条待办的内容做一次归一化去空格、去标点、转小写然后按归一化后的字符串做集合去重。如果两条待办内容相似度很高但不完全相同可以用编辑距离判断阈值设在 0.85 左右。这个做法简单实测够用比引入向量相似度计算省事得多。6. 常见问题与排查技巧实录6.1 输出格式总是不对怎么办这是最高频的问题。排查顺序是先看提示词里有没有明确说“只输出 JSON”再看有没有给示例输出最后看有没有做清洗兜底。这三步能解决九成以上的格式问题。如果还不行可能是模型本身对 JSON 的支持不好换一个对结构化输出支持更好的模型试试。6.2 改了提示词之前好的 case 坏了这是典型的“回归”。原因是提示词里的约束之间可能互相冲突你加了一条新约束挤压了旧约束的空间。解决办法就是前面说的变更日志加回归测试。每次改完把之前的 test cases 全跑一遍看有没有坏掉的。坏掉的 case 单独分析看是哪条约束冲突了调整措辞而不是简单叠加。6.3 处理长文本时结果不稳定长文本处理不稳定通常是分段和合并的问题。先检查分段长度是不是超过了模型的舒适区再检查合并逻辑有没有丢信息。我遇到过一次原因是分段时把一段完整的对话切成了两半前半段里的待办在后半段里被重复提取合并时又没去重导致同一条待办出现两次。后来把重叠加大去重逻辑补上就稳了。6.4 常见问题速查表问题现象可能原因排查动作输出不是 JSON提示词未明确约束加“只输出 JSON”并给示例字段缺失规格未定义必填项在规格里标注必填提示词里强调长文本结果乱分段或合并有问题检查段长、重叠、去重逻辑改完反而更差多变量同时改动回退到上一版单变量重改偶发解析失败无清洗兜底加正则清洗和重试逻辑6.5 一个容易被忽略的坑模型对“数量”的感知让模型“提取三条待办”和“提取待办”结果完全不同。模型对具体数字的遵循度远高于模糊描述。所以规格里凡是涉及数量的都写具体数字。但也要注意数字太死板会导致边界情况处理不好比如实际只有两条待办时模型可能会硬凑第三条。我的做法是写“最多三条”而不是“三条”。7. 这条路径的适用边界与扩展方向“文档驱动 实测修订”不是万能的。它最适合的是需求相对明确、但实现细节模糊的场景比如内部工具、轻量级自动化、数据处理脚本。如果需求本身还在探索阶段连要做什么都没想清楚那先别写文档先做几个最小实验把方向探明。这条路径的扩展性在于文档和测试用例是可以复用的。下次做类似工具时规格文档改一改就能用测试用例补几条就能跑。我现在的习惯是维护一个“规格模板库”按工具类型分类新项目直接从模板改省掉大量从零写规格的时间。另外实测修订这个环节积累下来的问题排查经验其实比代码本身更有价值。代码会过时但“怎么定位格式问题”“怎么处理长文本”这些经验换个项目照样能用。我建议每次项目结束后把排查记录整理成一份自己的“避坑清单”时间长了这份清单就是最实用的个人资产。最后分享一个小技巧如果你不确定某个需求能不能落地先别写代码先用文档把输入输出和核心流程写出来然后拿三组真实数据手动走一遍流程。如果手动走都走不通那 AI 更走不通。这一步花不了半小时但能帮你省掉几天甚至几周的无效开发。