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分钟写的SpecAI可以用更少的轮次和更少的试错把代码写对一次跑偏的代价通常不止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、验证码为123456HTTP状态码必须为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输出质量的手段也在逼着你想清楚每一个字段到底从哪来、到哪里去这本身就是高密度经验积累的过程。