如何写好AI编程的spec？让AI生成更准确的代码

刚接触 AI 编程或者用过一段时间 AI 编程工具的人，大概率都经历过这个场景：你花了大半天，把需求文档写得密密麻麻，背景、目标、接口、边界条件恨不得全塞进去，结果 AI 生成的代码一跑，核心逻辑全是错的，甚至方向都跟你想的完全不一样。那一刻真的会很怀疑人生：到底是 spec 写得不够好，还是 AI 太笨？

其实都不是。问题出在大多数人对“spec 写得完整”这件事的理解，和 AI 实际需要的东西之间，存在一条巨大的认知鸿沟。spec 这个词，在 AI 编程、spec coding、AI agent 工作流里几乎每天都要打交道，它确实是指导 AI 的第一资料，但它的定位不是“产品需求文档”，而更像是“给一个聪明但失忆的程序员的操作手册”。这篇内容，我把自己的踩坑经历和反复验证过的经验整理出来，掰开揉碎讲给你听，希望能帮你少走点弯路。

内容适合三类人看：正在用 Cursor、Copilot、通义灵码这类工具的开发者，做 AI Agent / AI 工程实践相关工作的工程师，以及产品、测试、研发任何需要跟 AI 协作的人。下面直接进入正题。

1. 先搞清楚：你以为的“完整” vs AI 眼里的“完整”

1.1 需求完整不等于指令可执行

很多人的 spec 确实很“完整”，功能、流程、界面元素、接口参数全都有，但 AI 还是做错。这里的第一层原因，往往出在“完整的方向错位”上。你觉得完整是把业务讲清楚，AI 需要的完整，是把每一步该干什么、在什么条件下干什么、输出长什么样，用可执行的语言确定下来。

打个比方，你请了一位家教帮孩子辅导作文，你把背景资料、主题、字数要求都给得很足，但你没有告诉他“每段第一句必须是论点句”、“不能用感叹号”、“动词一律用主动语态”。家教最终可能写出了一篇好文章，但它不符合你的评分标准。AI 写代码也是这个道理。业务描述再丰富，如果编码层面的可执行约束缺失，它就只会生成“看起来差不多”的代码。

我自己实测过一组对比：给 AI 一份写满业务细节、但缺少明确验收条件的 spec，和一份只写了核心功能、但明确给出“输入是什么、输出是什么、异常时返回什么、错误码是什么”的 spec，后者的完成精准度反而高很多。原因后面会展开说。简单讲，模型是根据 token 概率生成内容的，它更容易抓住有“可检验性”的句子，而不是描述性的背景信息。

1.2 spec 完整的三个维度

如果要把“完整”给一个可操作的定义，我建议拆成三个维度，缺任何一个都会有“AI 做不对”的现象出现。

• 需求完整性：功能目标是全的，角色和权限是清楚的，数据来源是明确的。
• 指令可执行性：每一步的输入、处理、输出、异常路径，都有足够具体、无歧义的描述。
• 验收可检验性：你给出了判断“做对”的客观标准，通常体现为验收条件、测试用例、边界值、性能阈值。

这三个维度不是并列关系，而是从“想清楚”到“写得清”再到“可验证”的递进关系。很多 spec 其实输在第二层和第三层，而需求层的“完整”反而经常是信息过量，把模型的注意力带偏了。

2. 为什么 AI 会把“明确的 spec”做歪：根因拆解

2.1 上下文窗口不是无限内存

AI 的上下文窗口虽然越来越大，但“能放进窗口”不等于“能被有效利用”。模型对长文本的处理有一个注意力分配的问题：它会在每个 token 上计算权重，长文本很容易出现“中部信息被稀释”、“开头和结尾的记忆更强”的现象，业内管这个叫 “lost in the middle”。你的 spec 如果长达一两千行，真正影响核心逻辑的约束可能藏在中间，等模型读到后面，重心已经偏移了。

实操中，我习惯把核心约束分成两类。一类是“最高优先级指令”，必须放在 spec 开头 10% 的位置，甚至直接在系统提示词或第一条 user 消息里重复一遍；另一类是“背景资料”，放到最后，让模型在需要时查阅。把背景资料和硬性约束混在一起写，是 AI 做错的最常见原因之一，没有例外。

2.2 模型的“理解”是概率性解释，不是逻辑推演

无论模型多强，它的底层机制还是“根据前文预测下一个词”。它不是像编译器那样按语义严格执行，而是在生成时寻找“最像正确答案”的路径。所以 spec 里如果存在两个互不冲突、但也没有强制关联的信息，模型可能只取其中一个；如果存在一个可做可不做的描述，模型倾向于选择比较常见的做法，而不是你的做法。

这就是为什么 spec 里写着“校验失败时返回错误提示”，AI 可能返回 HTTP 400，也可能返回 200 + 业务错误码，甚至可能只打日志不返回。人类看到“返回错误提示”，能理解需要看后面上下文确定具体格式，但模型只能在概率分布里做选择，它觉得哪种写法“更像正确答案”就写哪种。

2.3 隐式假设：你没写，AI 也不会替你补

每个人心里都有很多“不用写也知道的东西”。你写“用户上传头像，限制大小”，你觉得“大小”是指文件体积，AI 可能理解成“尺寸”，结果生成了 2MB 的限制而不是 512×512 像素。你写“列表按时间倒序”，你默认是新创建的排在前面，AI 可能按更新时间排序，因为“时间”这个字段本身就有歧义。

隐式假设是 spec 的隐形杀手。越是熟悉业务的人越容易漏，因为有些东西对你来说太显然了，而 AI 唯一的输入就是文字。你没写，它就只能猜，猜完可能还猜得很自信。处理隐式假设的诀窍是：把自己当业务小白，把 spec 当交接文档，把所有用到的名词做一次“名词-定义表”。“大小”是什么大小？是文件字节数、像素尺寸、还是列表长度？“时间”是什么时间？是创建时间、更新时间还是业务发生时间？“已完成”是什么状态？是用户操作完成，还是后台任务执行完成？写进 spec 里哪怕只有一句话，效果也立竿见影。

2.4 输出格式：你觉得没问题，但解析就是失败

还有一类“AI 做不对”，不是逻辑问题，而是输出格式问题。你需要 AI 输出 JSON，它偶尔会在 JSON 前后加解释文字；你需要它输出数组，它给你套了个对象。这在 spec coding 里是高频问题，尤其当 spec 只描述业务、不描述输出结构时。

解决方式很简单也很土：在 spec 里直接用代码块给出“输出模板”，告诉模型必须严格按照该结构输出，并加上“除该结构外不要输出任何其他内容”这种强约束。实测下来，这种显式模板比任何自然语言的描述都管用，几乎能把这个错误率降到零。

3. 从 spec 到代码：AI 真正“读懂”你需要的几个条件

3.1 把“目标”翻译成“指令”

我经常跟团队做 AI 工程实践培训，里面最核心的一句话是：不要把 spec 写成产品需求文档，要写成给一个聪明但失忆的程序员的操作手册。

产品需求文档描述的是“系统应该是什么样”，操作手册描述的是“你现在按顺序做什么”。AI 每一次对话都是重新阅读整个 spec，它没有长期记忆，也没有“我上次读过了”的缓存，所以你要假设它什么都不知道。举例说明：

• 需求写法：“系统需要对上传文件进行病毒扫描。”
• 指令写法：“文件上传完成后，调用扫描服务，若扫描状态为 fail 则删除文件并返回错误码 A102；若超时 3 秒返回 A103；其他情况返回 A100。”

后者不仅告诉它做什么，还告诉了决策树和每种结果对应的可执行动作。AI 做对的比例会显著上升，因为不存在概率性的“该返回什么”的选项了，判断标准和动作都是确定的。

3.2 顺序就是优先级

Spec 的排列顺序会被模型当作隐式优先级。越靠前的内容在生成时权重越高，越靠后的内容越容易被忽略。很多人的 spec 开头写“背景介绍”、“产品目标”，把真正的技术约束放在中后段，结果 AI 在生成代码时优先满足它理解的“产品目标”，技术约束就被忽略了。

我的经验是，spec 的结构严格按下面的顺序组织，硬性约束永远在最前：

1. 硬性约束：禁止事项、强制技术栈、必须使用的函数或模式、必须返回的格式。
2. 功能入口与触发条件。
3. 完成标准与验收用例，至少 3 个，包含边界值和异常场景。
4. 正常流程描述。
5. 异常流程与兜底逻辑。
6. 背景资料、业务知识、参考代码，可选放最末。

这样调整之后，模型的输出会明显更稳。我对同一个任务做过两次对比：一次按产品需求风格写，一次按“指令优先”的风格写，同样是做一个批量文件重命名的小工具，后者第一次跑通的概率高很多，而且重新生成时的一致性也更好。

3.3 伪代码也算代码：在 spec 里预置关键逻辑片段

很多人舍不得在 spec 里写伪代码，觉得“我把伪代码写完了，还要 AI 干什么？”我的观点是，AI 的价值不是替你思考算法，而是替你实现工程化代码。在 spec 里插入关键逻辑的伪代码，能让 AI 百分之百对齐你的思路，尤其是排序规则、状态机、边界判断这类逻辑。

比如你要实现一个“任务重试”，与其写“重试失败的请求”，不如写：

对于每个任务，最多重试3次； 每次重试间隔为 [1,2,4] 秒（指数退避）； 重试前必须更新任务状态为 retrying，并写入日志； 若第三次仍失败，标记任务为 failed，同时发送告警通知。

AI 拿到这样的伪代码后，生成的重试逻辑基本不需要改，因为它不再需要“猜测”你的重试策略，你给出的规则就是它唯一的生成依据。这个方法有个前提：你自己得对关键逻辑有清晰的预期。如果你自己都是模糊的，那确实应该先让 AI 帮你列出方案，而不是直接写代码。把“方案设计”和“编码”分两步走，很多问题能在编码前先暴露出来。

4. 实测案例：一份 spec 的三次整改记录

4.1 场景背景

拿我以前做过的一个小项目当案例：用 AI 生成一个通用的“Excel 导入”功能。需求包括文件上传、格式校验、按批次写入数据库，前端异步显示导入进度。这个项目规模不大，但非常适合展示 spec 质量对 AI 输出的影响，因为里面有大量边界条件。

第一版 spec 我写成了：

用户可以通过页面上传 Excel 文件，系统需要校验文件格式，将数据导入数据库中，导入过程中显示进度，导入完成后通知用户。

4.2 第一版 AI 输出：业务大体对，细节全是雷

AI 第一版输出看起来挺完整：有上传接口、有读取 Excel 的方法、有批量插入、有进度字段。但几个关键细节全军覆没：

• 校验只做了扩展名判断，没读文件内容，导致伪装的 .xlsx（实际是文本文件）直接报错。
• 日期格式检测写死了 yyyy-MM-dd，但用户大量使用 yyyy/M/d，导入结果全是空字符串。
• 批次写入没有做事务，5000 条数据中间有一条错了，前面 4999 条全部入库，而且进度卡在 97% 不更新。
• 失败记录没有返回给用户，只打了日志，用户完全不知道哪几条失败。

站在 AI 的角度分析，它有没有读懂 spec？读懂了大部分。它没有自动补齐这些边界条件，原因是 spec 里根本没提“伪装的扩展名怎么办”、“日期格式有哪些”、“单条失败要不要影响整批”、“失败明细要不要给用户看”。这些对我是常识，对它是盲区。

4.3 第二版 spec：补了边界，但补法不对

第二版我补充了很多细节，写法是“注意：文件格式要校验，日期格式要兼容，导入失败要提示用户”。结果好了一些，但依然不理想。原因是这些描述仍然是“目标性”的，没有“可执行性”。比如“校验文件格式”，AI 可能只判断扩展名；“兼容日期格式”，AI 可能只加一个 yyyy/MM/dd，少了 yyyy-M-d 和 yyyyMMdd；“提示用户”，AI 可能写个 alert 就完了。

这个阶段我意识到，AI 需要的不是我提示它注意什么，而是我告诉它判断标准和动作。后来我把这三条改成了：

• 文件格式校验：解析文件头，判断是否为合法 Excel 格式；若文件头不属于指定魔数段开头，返回错误码 E001，不得入库。
• 日期解析：入参支持 yyyy-MM-dd、yyyy/M/d、yyyyMMdd 三种格式，解析失败返回错误码 E002，记录到失败明细。
• 失败明细：导入完成后，返回属性包含 successCount、failCount、failDetails（数组，每条含行号和失败原因）。

这一版 AI 的输出质量提升非常明显，因为每条都有“判断标准 + 动作 + 输出形式”。我拿这个经验回头检查自己写的所有 spec，补了一遍之后才真正稳定下来。

4.4 第三版：把验收用例直接写进 spec

第三版更进一步，我在 spec 末尾加了一段“验收用例”：

加验收用例的效果比我预想中还好。AI 会以这些用例为目标，反向修正自己的实现。比如它为了满足 TC03，会主动把失败明细的数据结构设计充分；为了满足 TC04，会实现分批和进度更新，而不是一次性插入。

这里多说一句，验收用例放在 spec 里不是“仅供参考”，而是“强制条件”。最好在用例后面加一句“实现必须通过这些验收用例，若有场景无法满足，需要先说明原因再编码”。这样 AI 就不会在部分实现无法覆盖时不说明原因地跳过。

5. 常见问题与排查技巧实录

5.1 典型问题速查表

这几类问题是我实际使用中反复遇到的，整理成一张速查表，遇到“AI 做不对”可以先对号入座。

这张表对我的排查流程帮助很大。遇到不对的代码，我第一反应不是怪 AI，而是先回看 spec：是不是漏了规则？是不是有歧义？是不是约束放得太靠后？

5.2 两个高性价比的“防错动作”

动作一：先让 AI 复述需求，再编码。

这是我在 spec coding 中收益最大的一个小技巧。在正式让 AI 写代码前，先让它“用你的理解复述一遍需求，并列出你将要使用的技术方案、接口设计和完成标准”。这一步能暴露绝大部分理解偏差。AI 复述得有多准，后面做错的概率就有多低。而且它的复述文本会成为后续对话的锚点，等于把 spec 里最重要的信息又强化了一遍。

动作二：要求 AI 做“自测并解释”。

让 AI 写完代码后，要求它“按 spec 里的验收用例逐条自测，并输出测试过程与结果”。如果它自己都没信心说“这条用例覆盖不了”，那大概率是 spec 有盲区或实现有缺陷。这个过程类似让 AI 做 code review，虽然它不能真正执行代码，但能通过静态推演发现很多不一致的地方。

5.3 长文本项目的拆分策略

如果你的项目很大，一定要避免把全部需求放在一个超长 spec 里。我推荐“总 spec + 子任务”的方式：总 spec 只写全局架构、目录结构、模块划分、约束规范；每个子任务单独写一个局部 spec，里面包含该模块的详细要求和验收用例。

这样做有两个好处。第一，模型每次看到的信息量小了，注意力更集中；第二，你可以在子任务的 spec 里引用总 spec 的架构约束，让模型“带着全局观写局部代码”。很多 AI agent 工具本身就有任务拆解能力，但你自己拆分后注入，可控性要高得多。

6. 把 spec 和测试绑定：让 AI 自己给自己验收

6.1 在 spec 里内置“测试计划”

刚刚说验收用例要写进 spec，这里还有一个更进阶的玩法：把测试计划也做成可执行的、能让 AI 生成测试代码的东西。操作上，每个验收用例不仅要写输入和预期，还要附上“如果实现语言是 Python，用 pytest 写；如果是 TypeScript，用 vitest 写”。这样 AI 在生成业务代码时，会顺手生成对应的测试代码，甚至在写实现时就已经在想怎么满足测试。

我实测过一个账号系统的接口改造任务。spec 里的验收用例比较多，我加了一句话“请为以下每个验收用例生成 pytest 测试，测试文件命名 test_*.py，全部放在 tests 目录”。结果 AI 生成的测试和实现代码几乎是配套完整的。虽然部分测试因为环境原因需要微调，但整体覆盖度和逻辑一致性，比我人工补测试快了很多。

6.2 测试先行 vs 后置说明

传统的 TDD 是“先写测试，再写实现”。对 AI 编程来说，因为需要一次性生成很多东西，比较现实的做法是“同一轮对话里测试和实现一起生成，但测试代码在逻辑顺序上要先于实现代码被思考”。这样说有些抽象，换个说法：在 prompt 中明确要求“先定义接口契约和测试用例，再写实现代码”。AI 依然在同一轮中完成，但输出顺序会影响它自己的逻辑一致性，因为先想清楚验收再写实现，隐含的推理链是顺的。

如果工具支持多轮执行，更推荐的做法是：

1. 第一轮：让 AI 根据 spec 输出测试用例清单。
2. 第二轮：确认或修正测试用例。
3. 第三轮：让 AI 根据“spec + 已确认测试用例”生成实现。
4. 第四轮：让 AI 根据实现跑一遍“自测步骤”，无法真实运行的话，至少做静态走查并输出结论。

这套流程在 AI agent 工具里基本都能实现，手动在对话里分轮问也行，就是辛苦一点。但你可以明显看到，经过“先用例后实现”流程生成的代码，比一刀切直接生成的要稳很多。

6.3 找不到问题的最后手段：可复现的最小样例

如果 spec 已经很完整、验收用例也写了，AI 还是做错，而且错得很莫名其妙，大概率需要给 AI 一个“最小化样例”来对齐。常见做法是，在 spec 里给出一份小的输入文件（比如只有 3 行数据的 CSV），并写出期望输出；同时要求 AI 用这份样例做数据流走查，输出每一步中间变量的值。

这个过程很费 token，但定位问题的效率极高。它能把“AI 对 spec 的理解在哪里发生了偏移”非常显式地暴露出来。尤其是在处理复杂状态机、嵌套数据结构这类问题时，最小样例简直是指路明灯。我之前处理过一个订单状态流转的错误，整整查了两轮对话都没定位到问题，后来给了一个只有 3 条状态迁移的最小样例，AI 一下就意识到自己把“已取消”状态从状态机里漏掉了。

7. 一点更深的思考：spec 与工具链的协同

7.1 spec 不只是给模型看，也是给 AI Agent 的“任务书”

现在很多人的工作流已经从“单次对话生成代码”升级到了“AI Agent 自主完成一个模块”，这就对 spec 提出了更高的要求。在 Agent 场景下，spec 不仅仅是“给模型看的描述”，还是 Agent 规划任务、拆分步骤、调用工具、自我检查时的依据。如果你的 spec 只写了“做什么”没写“怎么拆”，Agent 可能自己拆出一个你完全没预料到的执行路径。

我见过一个典型翻车场景：用户给了 Agent 一个任务“把图片上传接口加上压缩功能”，spec 里写了压缩质量 85%、格式转 WebP，但没有写“压缩后要删除原图”。Agent 执行完以后，原图和新图都留存了，而且上传逻辑变成了“先传原图再传压缩图”，完全偏离了“客户端压缩后再上传”的初衷。这个问题的根源不是 Agent 笨，而是 spec 没有表达“在哪个环节做压缩”。把这个写清楚之后，Agent 的执行路径就正常了。

所以，如果你在使用 AI Agent，建议在 spec 里增加一小节“执行顺序与依赖关系”，明确列出任务的先后步骤、步骤之间的输入输出、哪些环节可以并行、哪些环节必须串行。这对 Agent 的规划能力是一个很好的补强。

7.2 spec 的版本管理：把 spec 当作代码一样维护

还有一点很多人忽略：spec 是有生命周期的，它不是写一遍就完事了。AI 生成的代码改了，spec 如果不跟着更新，下一次让 AI 修改功能时，它会把旧 spec 和新需求混在一起，生成的结果大概率是矛盾的。

我的经验是，把 spec 放进仓库里，和代码一起做版本管理。每次需求变更，先改 spec，再让 AI 改代码。这样模型（以及未来的你）始终能看到一份“和代码同步演进”的需求文档。如果不这样做，你会陷入一个死循环：代码改了三轮，spec 还是最早那一版，AI 每次修改都在拿旧地图找新路，错误率当然降不下来。

7.3 警惕 spec 与数据样例的不一致

最后提醒一个很容易被忽略的细节：如果你的 spec 里引用了字段名、枚举值、示例数据，一定要保证和代码里实际的数据结构一致。比如 spec 里写“status 字段可选值为 pending、processing、done”，结果示例 JSON 里出现了一个 “completed”，AI 就会非常困惑，它可能会把 “completed” 当作合法值，也可能直接报错。

这种问题在长 spec 里特别常见，因为手写的时候很难做到全文一致。建议在写完 spec 后，自己先做一次“字段命名一致性扫描”，或者直接把关键字段列表放在一个显眼的地方，然后用一句话约束 AI：“以上字段定义为本需求的唯一可信来源，若在需求描述中发现不一致，以该字段定义为准。”

结尾

我自己用了很长一段时间的 AI 编程工具，最大的一个感受是：AI 不是不聪明，而是它“不知道自己不知道什么”。它不会像同事一样反问“你这里的校验是指文件头还是扩展名？”、“时间倒序是按哪个字段？”，它只会按自己的理解一路走下去。所以 spec 写作的核心不是把内容写得更长，而是把所有可能产生歧义的边界，用文字钉死。

我的建议是：每次 AI 做错，先别急着怪它，把错误整理成一个清单，然后逐条反向补充到 spec 里。补了两三次之后，你会发现自己的 spec 越来越薄而不是越来越厚，因为你已经知道哪些话 AI 需要听、哪些话它对理解帮助不大。这是一种双向磨合，磨合好了，后面新项目的 AI 产出质量会直接上一个台阶。

最后分享一个小技巧：写完 spec 后，先让 AI 用 100 字以内概括它理解到的需求。如果这个概括和你心里的预期一致性超过八成，再让它开工，否则先把 spec 说清楚。这一步真的能省下后面大量的返工时间。