1. 先别急着让AI写代码：一句话需求为什么会跑偏

你有没有过这种经历：跟AI说了一句“帮我做个用户登录”，它两秒钟给你吐出一大坨代码，看起来功能齐全，跑起来全是问题——没有校验、没有异常处理、连密码是明文存的都敢给你写出来。你要是再追问“你为什么会这么做”，它反而一脸无辜，因为你没说。

这不是AI蠢，也不是它不努力。问题出在“一句话需求”本身就是一个信息压缩率极高的表达。人类之间做沟通，靠的是共同认知背景去补完大量没说出口的信息；但AI没有这种背景，它的默认行为是“用最热门的特殊案例去盖一座最安全的房子”。你开头说的那句“做个用户登录”，在AI的统计世界里，对应的可能是某个开源博客项目里最小可用的登录模块，根本不是你业务里那个要和手机号验证码、第三方授权、多端token联动登录体系。

我在实际试过把同一句话需求丢给不同AI产品之后，有个很深的体会：它们的差异不在“听懂话的能力”，而在“补全的偏好”。有的偏好保守，只给你最基本的骨架；有的偏好完整，会自行脑补一堆字段和接口。但这种“补全”恰恰是最危险的地方——AI补出来的字段，十有八九不是你产品经理表格里那个字段。

所以，这篇文章的核心就是一条实操路线：把一句话需求，加工成字段级Spec，再让AI基于Spec写代码。这个前缀链路你做得越扎实，后面AI写出来的东西越接近可交付，而不是一堆“看起来能跑”的代码。

1.1 AI最擅长“补全”，而不是“追问”

大模型生成代码的机制，本质上是在做下一个token的预测。它写出来的每一行代码，都是“在你给的信息+它训练见过的大量代码分布下，概率最高的那一个”。这不是独立思考，也不是真正理解你的业务，而是一种比搜索引擎高级得多的模式匹配。

这带来一个直接后果：你不把约束给全，它就按自己见过的最大公约数来写。比如你对AI说“写一个订单列表接口”，它的默认假设里可能出现：没有分页、没有筛选条件、返回了整个订单表的所有字段、也没有考虑数据权限。这些恰恰是生产环境代码最贵的部分。

我做过的对比测试挺能说明问题。同一个“订单列表接口”需求，一组直接丢给AI写，另一组先花15分钟整理一份含字段级说明的Spec再丢进去。结果是：直接丢的那组代码实现时间只花了两分钟，但评审后改了三轮；先写Spec的那组，实现时间花了二十分钟，但改动极少，字段对齐率接近百分之百。

这就是为什么我一再强调要“先Spec后Coding”。你没花掉的时间，都会在后面十倍百倍地补回来。

1.2 需求拆解的第一步：把名词圈出来

很多人一上来就列功能清单，但字段级Spec的正确起点不是功能，而是名词。名词是被业务反复提到的实体；一个名词通常就是一个数据表或者一个对象；名词后面的定语，往往就是字段约束的雏形。

拿最经典的“做一个用户注册功能”举例。这句需求里的名词是“用户”，那我要追问的选项就出现了：用户名是手机号还是邮箱还是自定义？密码有没有复杂度要求？要不要昵称、头像、性别？有没有邀请码？注册成功后需不需要默认创建什么关联数据？

如果你拿记号笔把这句需求里所有名词圈出来，会发现可引申的信息量远超想象。“用户注册”四个字背后，实体至少有“用户账户”“登录凭证”“用户资料”，可能还有“邀请关系”“设备绑定”“操作日志”等。

一个我在团队里带得很顺的习惯是“名词分色法”：用黄色标实体类名词，用绿色标动作类名词，用蓝色标状态类名词。黄的是表和字段，绿的是接口和流程，蓝的是枚举和状态机。三次拆解下来，一张草稿纸就能把整个需求的骨架撑起来。

1.3 “不做的事”清单：比功能清单更值钱

字段级Spec里面，最容易被省掉也最容易被AI搞坏的部分，是反例边界。你告诉AI“要做什么”总是很容易，但告诉它“不要做什么”却经常被遗漏。

举一个我踩过挺多次的坑：给AI描述“写一个评论接口，用户可以给文章评论”，它通常会默认允许任何登录用户评论任何文章，包括自己评论自己的文章、评论已关闭的文章、同一条评论重复提交。这些在业务上是明令禁止的行为，你没写进Spec就等于放开。更麻烦的是，AI写出来的校验逻辑和你业务侧的预期完全分离——你以为它校验了，其实它压根没往那个方向想。

所以我在每个Spec里强制保留一块“禁止行为”区，列入至少三条以上的反例约束。比如：

• 不允许未登录状态下调用本接口
• 不允许对已关闭评论的文章新增评论
• 不允许同一用户对同一文章在10秒内重复提交评论

这看起来是小事，但AI一旦读到这些约束，生成的代码里会主动出现对应的守卫条件，而不是指望某个中间件统一拦。

结论很直接：正面功能清单决定AI“做什么”，反例约束决定AI“不做什么”，后者往往才是生产事故的源头。

2. 字段级Spec长什么样：模板、结构和底层逻辑

Spec全称是Specification，也就是“规格说明”。这个词虽然在工业领域用得多，但在软件工程里同样是指一段精确、无歧义、可用于验收的描述。

为什么必须强调“字段级”？因为AI写代码时，真正能让它跑偏或跑对的地方，往往不是一个接口的主流程，而是每一个字段的类型、约束、默认值、来源和去向。主流程只有一条，AI基本不会写错；但字段上百个，任何一个约束漏了，AI就会用它的“默认世界观”帮你补一个——补出来的往往和真实业务相差很大。

下面直接给一份我用了很久的Spec模板，不用下载什么工具，就是一个Markdown文档，加上编号，大约三到五页。关键在于它覆盖了AI从代码生成到测试验收所需的几乎全部结构信息。

2.1 一份字段级Spec必备的五个模块

我的模板不算花哨，核心就五块：模块定位、数据模型、接口细则、业务规则、验收标准。

模块定位是写给AI和评审人双方看的“需求摘要”，用五句话以内讲清楚这个模块是干什么的、上游是谁、下游是谁。数据模型是整份Spec的心脏，里面是每一个字段级定义。接口细则列出所有要暴露的API路径、请求方法、请求头、请求体、返回体。业务规则再把链路里的非原子性逻辑讲清楚，比如状态流转、幂等性、并发控制。验收标准则给出一组可以执行检查的清单，AI后期也可以借助它自查。

很多初学者会问：“我只想让AI写个FastAPI接口，为什么要写这么多？”我的回答是：你花10分钟写的Spec，AI可以用更少的轮次和更少的试错把代码写对；一次跑偏的代价通常不止10分钟。更重要的是，字段级Spec本身就可以沉淀进项目文档库，给后续维护、新人接手、甚至第二个AI项目复用，做到一次整理、长期受益。

2.2 字段明细表的写法：每个格子都有意义

字段明细表是整个Spec里技术含量最高、也最容易被写废的部分。一个合格的字段定义包含这么几列：字段名，类型，是否必填，默认值，来源，业务规则，示例值。

• 字段名不用多说，就是程序里真实使用的名字，建议统一用小驼峰。
• 类型要具体到语言级别，比如String、Integer、LocalDateTime，而不是模糊的“日期”“数字”。
• 是否必填写清楚，这里要区分“请求时必填”和“存储时非空”，很多AI生成的代码会把两者混为一谈。
• 来源指的是这个字段值由谁产生——前端传参、服务端计算、数据库自增，还是第三方回调。这点特别关键，AI一旦不知道字段来源，就会默认自作主张地放在请求参数里，坑到后面接口对接。
• 业务规则则是这一字段的限制逻辑，例如“字符串长度在1到50之间”“数值必须大于0”“枚举值只能取’pending’、’paid’、’failed’”。
• 示例值是给AI喂样例用的，喂一个真实形态的数据，AI生成的序列化逻辑会更准确。

比如一个“订单金额”字段，如果只写“订单金额 Decimal 必填”，AI大概率会写成一个只接受正数、没有任何精度约束的参数；但你如果写明“类型为Decimal(10,2)，必须大于0且小于1000000，精度四舍五入保留两位小数”，它写出来的校验逻辑就差不了多少。

2.3 验收标准怎么写才不算“废话”

验收标准最大的坑，是写成“功能正常”“运行流畅”“没有Bug”这种无法验证的废话。我在Spec里只保留两类验收项：一种是可执行的，另一种是可由测试用例覆盖的。

可执行的验收项指的是“调用某个接口时传入一组特定参数，断言返回体里某个字段等于期望值”。这类标准是给AI或者测试脚本用的，越具体越好。比如“POST /api/v1/users时，传入手机号为13800001111、验证码为123456，HTTP状态码必须为200，响应体里userId字段必须是32位非空UUID”。

可由测试用例覆盖的验收项稍微抽象一点，比如“非法验证码必须返回4042错误码而非500”。这类要求是为了防止AI偷懒，把所有异常都统一包装成一个500。对生产系统来说，错误码和信息能精确区分，是排查问题的基础。

每次写Spec时，我都提醒自己一件事：如果验收标准可以不加思考地执行，它就有价值；如果还需要解释或讨论，它本身就有问题。

3. 实操路径：从一句话到冻结版Spec的四步流程

理论说完了，下面进入最容易上手用的部分。这一套四步流程是我在真实项目里磨出来的，不需要任何昂贵的工具，一支笔、一张纸、一个智能助手，甚至直接在文档里就能完成。

3.1 第一步：粗拆分，把“一句话”切成“三句话”

任何需求不管看起来多大，都可以按“主流程、异常流、关联流”三种形态拆成三句话。主流程是业务的核心通路；异常流是关键分支，比如用户输入非法、依赖服务返回失败、并发冲突；关联流则是这个功能被触发之后，它要去改动或通知的相邻模块。

拿“做一个支付回调”这句话举例。主流程可以拆成“接收支付平台回调，验签成功，修改订单状态，通知业务方”。异常流是“验签失败，丢弃数据并记录日志”。关联流是“订单状态变更之后，需要扣减库存、生成流水、触发消息推送”。

完成粗拆分之后，你会得到一张非常朴素但方向正确的全景图。不用追求完美，关键是让那些原本藏在“一句话”里的隐性流程浮到纸面上。AI后面写代码时，这些分支会成为它的天然指令。

3.2 第二步：澄清型提问清单，逼AI和需求方暴露假设

这一步最有实战价值。写Spec最怕“产品以为技术懂、技术以为产品懂”，最后的共识全靠猜。为了让假设尽快现原形，我列了一张固定提问清单，每次在动笔写字段之前，先把问题抛出去：

• 唯一标识是什么？是数据库自增、业务流水号、UUID，还是雪花ID？
• 数据量预估多大？单表还是分表？需不需要缓存？
• 并发读写冲突怎么处理？乐观锁还是悲观锁？
• 删除是物理删除还是逻辑删除？
• 金额精度？币种？是否需要小数点后四位？
• 哪些字段允许为空？哪些空值有业务含义？
• 状态字段的枚举值有哪些？初始值是什么？终态是什么？
• 所有字段的合法值范围？长度上限？
• 哪些操作记录日志？日志需不需要结构化？存多久？
• 外部依赖超时和重试策略？失败是补偿还是人工介入？

这组问题看起来像是技术评审，但在字段级Spec的语境下，它其实是在给每个字段标定“业务边界”。AI不需要参与回答这些问题，你更需要的，是把拿到答案后的字段约束写进Spec，让AI直接消费。

3.3 第三步：边界与异常，让画外音变成代码逻辑

绝大多数线上Bug的真正来源，不是主流程坏了，而是异常分支没定义清楚。边界写清楚了，AI生成的防御性代码才会自然出现。

异常分支里最值得花时间的是这几类：入参非法、依赖服务超时、并发冲突、外部返回了预期之外的数据。每一类异常，Spec里都要给出对应的行为描述，是全套报错、是重试、还是兜底存储。

比如“用户下单”这个场景，并发重复下单就是一个典型边界。Spec里如果只写“用户提交订单”，AI生成的代码很可能没有防重逻辑；但你又加上一条“同一用户同一商品未支付成功的单子存在时，新增请求返回429错误码”，AI就会主动去查询未支付订单并做校验。

我习惯在Spec里把“预期内异常”列成一张表，字段包含场景、触发条件、预期行为、错误码、日志级别。它看起来像是测试用例的前身，但实际作用是给AI指路。

3.4 第四步：冻结与编号，让Spec成为唯一事实来源

写Spec最大的敌人是反复改动。你每改一次，AI那边就多一份“记忆污染”。特别是当AI上下文里有多个版本的Spec片段时，它就分不清到底该按哪个版本来实现。

所以第四步的核心动作是冻结。不是不能改，而是每次改动都必须走版本变更。我的操作方式是给Spec加版本号和变更记录，比如v1.0、v1.1，每次变更均增加一行说明，并且代码生成时只允许注入当前最新版本。

在这个环节，还可以顺手做一件事：把Spec的编号和代码模块编号做映射。比如模块名USER_REGISTER，下面的接口命名为USER_REGISTER_01、USER_REGISTER_02，清单一目了然。AI生成代码时，你让它把编号留在注释里，后续追踪需求和代码的对应成本会低非常多。

4. 实战演示：两个案例从零走到字段级Spec

光讲方法论，容易觉得虚。下面用两个非常常见的例子，把完整链路走一遍。这两个例子一大一小，覆盖了从简单接口到带业务状态流转的模块。

4.1 案例一：用户注册接口

一句话需求是：“写一个用户注册接口”。

粗拆分之后，我得到：主流程是校验手机号和验证码并创建用户；异常流是验证码错误、手机号已注册、参数非法；关联流是开通信誉积分账户及发送欢迎短信。

然后进入澄清阶段。用户唯一标识选UUID，避免自增ID暴露口径；手机号做唯一索引；验证码有效期5分钟，同一次验证码最多匹配3次；注册时带上来源渠道字段用于数据分析；密码由前端加密后传入，后端不感知明文。

这些答案填进字段明细表之后，Spec变成这样：

用户在“USER_REGISTER”表中看到字段userId、phone、passwordHash、nickname、channel、registerTime、status；每个字段对应类型、是否必填、校验逻辑和示例值。验收标准配合一组真实手机号和验证码，描述出完整请求、成功响应、各类错误码对应场景。

就这么一个看似“人人都会”的接口，写完Spec再交给AI实现时，它的代码几乎能一次通过测试，校准点只剩一些风格细节。这在没有Spec的时候非常少见。

4.2 案例二：给订单模块加“批量导出Excel”

这个例子比注册接口再复杂一些，因为它涉及异步任务、状态流转、报表权限，还有兜底失败场景。

初始需求一句话：“订单列表加一个导出Excel的按钮。”

如果直接丢给AI写，它很可能会做一个同步接口，传参之后直接吐出一个文件流。这在数据量小的时候没什么问题，可一旦订单量上万，请求会超时，前端也体验不好。

经过流程拆解，我把需求展开成了这样：主流程是筛选条件下达导出任务，创建一条导出记录，返回任务ID；后台任务是异步执行，将查询结果写入Excel文件，再上传到对象存储，并回调更新任务状态；异常流是导出中无数据、导出数量超过单文件上限、任务执行失败；关联流是权限校验和操作日志记录。

字段级Spec需要覆盖的地方多了一块：导出任务实体。字段包括taskId、userId、queryConditions、status、fileUrl、errorMsg、createTime、finishTime。状态枚举为pending、processing、success、failed。

验收标准里，有一项非常关键：“任务创建接口在已有一个processing状态的未完成任务时，重复创建返回409及提示信息”。AI读到这种边界约束后，就会主动去查未完成任务，而不是只管往里插记录。

4.3 两个案例的共同点

这两个案例虽小，但链路一致。都是先拆分成主流程和异常流，再澄清关键细节，最后落成字段级表格。重复这套动作三到五次之后，你会发现写Spec的速度会越来越快，而且你判断需求质量的敏感度也会显著提高——很多需求方自己都没想明白的问题，会在写Spec的过程中提前暴露，这比到开发阶段再返工要划算得多。

5. 把Spec喂给AI的那些细节与踩坑记录

Spec这关过了之后，和AI协作这件事才真正过半。同一份Spec，用不同的喂法、不同的上下文组织，产出的代码质量可能天差地别。下面这部分都是我实战中试出来的经验和教训。

5.1 Spec怎么喂：一次性灌入 vs. 任务卡片拆分

不少人陷入的误区，是希望让AI在一个窗口里处理所有事情，所以一条对话里塞了十几个接口的需求。事实证明这效果不佳。倒不是AI模型能力不够，而是上下文一长，AI经常会捡芝麻丢西瓜：前面接口的字段互相覆盖、跨接口的命名风格漂移、有些规则被遗忘。

我的做法是分两类投喂：主干信息一次性灌入，分任务卡片逐步实现。

主干信息包括：项目背景、整体模块清单、数据模型总表、通用规则（如统一返回格式、统一错误码规范、审计字段）。这部分让AI建立全局认知。分任务卡片时，一次只给一个接口的详细Spec，这个接口全部字段和边界都放在一张卡片里。等AI完成这个接口，再进入下一个。

这种方式的额外好处是，后续找AI修改代码时，上下文相对干净，你只需提及任务ID和特定字段名，AI就能快速定位到对应实现，而不会因为上下文太长而胡改其他地方。

5.2 五个高频坑：术语不统一、脑补字段、上下文截断……

第一，术语不统一。Spec里用的字段名是orderAmount，你对话里却写“订单金额”，AI生成代码时可能顺手把变量命名成money。为避免这个问题，我对话时全部写字段原名，并且提示AI“所有代码中的命名以Spec为准”。

第二，脑补字段。AI实现时为了“更完善”，可能会自行添加一些Spec里没有的字段或接口，例如加一个remark、加一个查询接口。如果这类设计不影响主流程，你可以接受；但涉及数据库结构或对外接口时，额外新增内容务必警惕。我会在每条消息末尾固定一句：“未在Spec中定义的字段和接口，一律不要新增。”

第三，上下文截断。AI有输入窗口上限，Spec太长时会被中间截断，导致后面部分的数据模型缺失。我的应对办法是把Spec拆成多份子文档，按模块分开，喂之前确认当前对话有足够空间，或者在消息开头写明“请先读取并记住文档A，文档B待我下一步给出”。

第四，需求变更流向失控。Spec冻结之后，需求方还是可能改。改了之后如果你只是口头告诉AI，而不去更新Spec文档，代码和Spec就会逐渐脱节。我的习惯是先更新Spec、升版本号，再让AI基于新版本重跑相关部分，确保“唯一事实来源”始终成立。

第五，验收标准形同虚设。Spec里的验收标准写完，AI代码生成完，没有人真去对照执行。后来我发现，把验收标准直接转成AI的自我检查项，让它生成代码后逐条自查，效果出奇好。它有相当概率能发现自己漏了某个条件的判断。

5.3 用Spec做代码评审：一个被我低估的用法

最后一段，说说我最近才开始用顺手的一个玩法：用Spec做代码评审参照物。

传统上，代码评审靠人肉阅读，非常依赖和经验。但在AI写码的场景里，真正有害的问题往往不是逻辑错，而是“和Spec不一致”。所以我把流程调整为：AI写完代码后，我会再次把对应的Spec片段发给它，要求它“逐字段核对实现代码，指出不一致项”，这份核对结果再交给人工做快速审阅。

实测下来，这种方式能抓出很多肉眼容易忽略的问题，比如某个字段的校验类型不一致、某个默认值写错、状态流转少了一步。更妙的是，AI找出来的不一致项通常还附带建议修法，你直接把这份对照结果丢给另一个AI去改代码，又形成了一条自动化闭环。

我后来还把这个思路扩展到了接口测试和文档生成上：Spec同时驱动Mock服务、测试用例和接口文档的生成。只要Spec本身质量稳定，所有下游产物都跟着稳定。这一整套像是一条从需求到代码再到验收的流水线，中间几乎不需要人力重复劳动。

如果你现在手里正堆着一批没写Spec就要交给AI实现的开发任务，不妨先停一停。抽出十几分钟，把其中一两条核心需求按上面的模板落到字段级，再让AI干活，对比一下评测结果和我说的相差多少。用不了几次，你就会习惯先Spec后写代码这个流程——它不只是提升AI输出质量的手段，也在逼着你想清楚每一个字段到底从哪来、到哪里去，这本身就是高密度经验积累的过程。