我见过太多人用 AI 写代码上来就一句“帮我写个登录功能”模型也确实给了能跑的代码但一接真实项目就崩。不是缺参数校验就是字段名对不上再不然连业务状态都理解偏了。问题不在 AI在于你喂给它的需求本身就是模糊的。做需求的人脑子里有全景图可落到提示词里只剩一句话AI 只能靠猜。这一篇不聊花活就讲一条我从“一句话需求”走到“字段级 Spec”的完整实践路径。核心是把零散的业务诉求拆解成可直接执行的代码上下文让 AI 从“猜需求”变成“照着图纸施工”。适合正在用 AI 提效的开发、测试、产品经理也适合想把自己手头项目 AI 化的个人开发者。1. 需求拆解为什么一句话需求让 AI 必翻车1.1 AI 的真实工作方式与“上下文缺口”先说个底层认知大模型生成代码本质是“基于你提供的上下文做概率续写”。你给的上下文越具体续写落在正确路径上的概率就越高上下文越模糊它就只能调用训练数据里的“通用套路”来填补空白。一句“帮我写一个订单结算功能”对 AI 来说意味着无数种解释——结算口径是什么含不含运费优惠券分摊规则退款场景怎么处理这些在人类沟通里可以靠默契和追问解决但在提示词里不存在默契。AI 会把最常见的假设填进去而这个假设往往跟你的业务对不上。我把这个现象叫“上下文缺口”。缺得越多AI 就越是按照“大众化的技术想象”来生成而大众化想象恰恰是离真实业务最远的。所以你会发现一个悖论越简单的提示词AI 写出来的代码越“像样”但也越没法用。想解决这个问题就需要把需求从“一句话”逐步放大到“代码可执行单元”的粒度最终得到一份字段级的 Spec。字段级就是每个字段的名称、类型、含义、取值范围、校验规则、默认值全部变成确定信息。代码的每一个接口、每一个数据模型都能在 Spec 里找到对应来源。1.2 常见的三层需求模糊地带结合我自己的项目复盘模糊地带通常集中在三层目标层的模糊只说了“要做 X”没说清楚“X 要实现什么业务结果”。比如“做积分系统”但积分是营销工具还是权益体系是消费后累积还是行为激励方向不同表结构完全不同。路径层的模糊目标明确了但实现路径没定。比如“用户登录”是用手机号还是邮箱验证码还是密码接不接第三方 OAuth每个路径都是不同的代码分支提示词里不说AI 就随机挑一个。约束层的模糊更隐蔽但致命。性能要求、安全规范、兼容范围、未来扩展性这些如果不在 Spec 里显式写出AI 默认只追求“实现功能”完全不考虑表字段是否有索引、接口是否有鉴权、数据量大了是否会爆炸。一句话需求之所以让 AI 翻车本质上是这三层模糊同时存在而 AI 被迫在模糊中做了一连串“默认选择”。等代码生成完你以为得到的是答案其实是无数个未知假设的混合体。字段级 Spec 要做的就是把这些假设全部消除掉。2. 从“模糊意图”到“可执行需求”的四步拆解法2.1 第一步目标澄清——用一句“可验收的话”锁定方向我在实践里总结出一个硬规则写任何提示词之前先逼自己用一句话回答——做成之后用什么指标或现象证明它做成了比如最初一句话需求是“给我做一个订单备注功能”这没法直接写代码。我先问自己一句这个功能要解决什么答案是“销售在订单详情页能补充客户的特殊要求方便仓库拣货时看到”。这句“方便仓库拣货时看到”就是整个设计的北极星。接着把它转成可验收的话“销售在订单详情页添加备注后备注在订单列表、详情页、拣货单三个位置可见且可编辑”。有了这句话后面所有字段设计都有了判断依据。这一步很容易被跳过但它决定了后面所有内容的走向。目标没定清楚往下走的每一步都是在沙滩上盖楼Spec 写得越详细返工的代价越大。而且这一步要写进提示词作为 AI 生成代码时的“最高指导原则”——后续如果模型生成的方案出现偏差就用这句话来校准它。2.2 第二步路径设计——把黑盒需求变成一组“看得见的动作”目标明确后第二步是拆路径。路径拆解遵循一个朴素原则如果你是用户你会从这个功能里索取什么、提交什么还是用订单备注来说。用户侧的动作拆出来就是打开订单详情页看到已有备注点击编辑或新增填写文本内容保存并生效这些动作共同指向一个数据集合备注内容本身。但仅拆出动作还不够还要给动作配信息。用户在哪一屏看到备注格式限制多少字可不可传图片这些每个都对应到后续的一个字段或一项校验逻辑。这一步的产出是“行为-信息”对照表。我一般用表格记录下来一列写用户动作一列写动作涉及的信息项一列写信息项的格式预期。这张表就是下一步字段级拆解的原材料。它把黑盒需求变成了一组看得见的动作回路AI 得到它之后生成代码就相当于有人给它画好了“用户的完整行走路径”它只需要沿着路径铺设接口。2.3 第三步约束收敛——明确边界、规则与例外路径有了接下来做约束收敛。约束包括四类缺一不可字段规则约束每个字段的类型、长度、可选性、默认值。业务规则约束比如“备注在订单发货后不可修改”这种条件必须在 Spec 里固化否则模型不会自动替你想。技术大坝约束最大文本长度、接口超时、是否需要记录操作人和时间这些都属于技术坝不写就等于没有。边界例外约束空值怎么处理、超长文本怎么截断、并发编辑怎么处理。约束收敛不是一次头脑风暴还是一轮“追问式对话”。我的做法是把自己当成采访者反复问“如果……怎么办”。如果用户什么都不填直接保存会怎样如果备注内容超过 500 字怎样如果订单已经发货了还能不能改每一个“如果”都会逼出一个规则规则落到纸面上就是字段级 Spec 的一部分。我踩过的大坑是只写了“正常路径”的约束忘了“异常路径”。比如订单备注正常路径是“填写-保存-可见”但异常路径“发货后还能不能改”没写AI 生成代码时就完全不做状态判断导致线上出现已发货订单被随意改备注的 bug。这种问题代码层面查不出错全是需求层面的漏洞。2.4 第四步验收描述——用“示例输入预期输出”封死歧义最后一步是我个人最推荐的杀手锏给 AI 提供“示例输入 预期输出”的成对数据。它的作用相当于给需求文档配上了可执行的测试用例。举个例子为了让模型准确实现备注字段的“文本截断”我在 Spec 里写了这么一条输入用户粘贴一段 600 字文本到备注框预期输出系统存储且只存储前 500 字界面提示“备注超出 500 字限制多余内容已截断”这样一个具体的“输入-输出”对比任何文字都要有约束力。因为大模型本质上是“模式处理器”你给它一个小票级的输入输出对应关系它生成代码的时候就会不自觉地沿用这种模式而不是自己发明一种新的截断策略。验收描述这条我建议做两张表一张是“正常业务输入输出表”覆盖主流程一张是“异常场景输入输出表”覆盖边界条件。两张表全部写进提示词里代码生成后可以直接拿去做测试用例的蓝本。我实测下来AI 生成的代码通过验收测试的比例至少提升一倍。3. 字段级 Spec 的实操拆解以“订单结算功能”为例3.1 从实体梳理到字段清单这一节我用一个真实做过的案例来演示从零开始把“帮我写一个订单结算功能”拆到字段级 Spec。整个过程中不涉及任何代码但你拿着这份 Spec 去问任何 AI 工具生成的代码会比直接问“写个订单结算功能”靠谱一个数量级。我先梳理实体。订单结算功能涉及的实体有四张表订单主表、订单商品明细、结算单、结算明细。对于每一张表这时候还不急着写字段而是先明确这个实体解决什么问题。订单主表解决“这一单是谁的、总额多少、状态如何”结算单解决“这一批订单什么时候结算、结了多少钱”两套数据是分开管理的不能混在一张表里。实体明确后开始逐字段拆解。以订单主表为例字段拆解分五个维度业务字段、状态字段、金额字段、时间字段、审计字段。业务字段至少要包含订单号、用户 ID、订单来源、收货信息。订单号不用多说天然主键用户 ID 要注明是 long 还是 string订单来源如果是多端共用必须明确取值范围比如“APP/小程序/后台录入”收货信息是拆开存还是合并存要在这时候就定否则后续接口的入参出参全是模糊的。状态字段是重灾区。很多人只写一个“订单状态”但真实业务里订单状态是一个状态机至少有待支付、已支付、待发货、已发货、已完成、已取消。每个状态之间还可能有流转条件这些都应该在 Spec 里用一张状态表说明而不是丢给 AI 自己猜。金额字段则有一个极其常见的坑——“金额用什么类型”。我强调三遍金额绝不用 float。凡是涉及金额、积分、折扣这类精确计算的字段一律用 decimal精度明确到小数点后 2 位。这个细节如果不在字段级 Spec 里写明AI 生成的代码十有八九会用通用数字类型表面上跑得通一旦对账就出偏差而且是那种极难排查的隐蔽偏差。3.2 字段级说明书的六要素模板单个字段的说明书我给每个字段统一配置六个要素。这六要素不是我想出来的而是在多次返工中总结出来的最小完备集合字段名代码中实际使用的命名预先确定避免 AI 自由发挥出奇怪命名。字段类型与长度存储层面的精确类型和最大长度。业务含义这个字段在业务里到底代表什么杜绝歧义。默认值不传值时给什么。校验规则允许的取值边界、正则、范围。示例值一个真实的样例数据让模型有“感性认识”。举一个具体字段作例子——优惠券分摊金额字段名coupon_discount_amount类型decimal(10,2)精确到分业务含义本订单通过优惠券抵扣的总金额按商品金额比例分摊至各明细行默认值0.00校验规则非负且不超过订单商品总额多明细行分摊金额之和必须等于订单级优惠总金额示例值12.50有了这套结构任何一个字段丢给 AI它都不会产生二义性。整张表的所有字段都按这个格式写完后数据结构就是“死图纸”AI 的任务不再是设计而是翻译。不要小看“默认值”这一要素——很多 AI 生成代码跑不通就是因为某个字段没有默认值或者默认值给错了方向一旦统一在 Spec 里给定这类问题直接清零。3.3 状态机、计算口径与全局规则如何写入 Spec字段清单完成后还需要加入三类全局规则字段清单只解决“有什么数据”下面这三类规则解决“数据如何变化和计算”。状态机订单状态不是一个字段那么简单还包含状态与状态之间的流转条件。比如“已支付”到“待发货”前提条件是支付回调成功且订单金额已对账“待发货”到“已发货”前提条件是仓库已打单并出库。这些流转条件要逐一写进 Spec甚至可以给 AI 提供一个状态流转表格左列是当前状态中列是触发动作右列是目标状态。计算口径所有的聚合类字段——订单总额、应结金额、退款总额等必须写明计算口径。比如订单总额是否包含运费如果包含是哪些情况下包含运费参与优惠券分摊吗这些口径问题如果在代码阶段才去“问 AI”AI 只能给你一个可能正确、也可能不正确的答案。在 Spec 阶段你要用一句话锁死它订单总额 商品总额 用户实付运费 – 优惠券降额。全局规则适合放在 Spec 开头作为“最高原则”。例如所有金额字段禁止使用浮点类型所有时间字段统一按 UTC 存储、展示时按用户时区转换所有接口必须对入参做空值校验和长度校验所有涉及金额变动的操作必须记录操作日志。这些全局规则会在模型生成每一个接口时持续发挥约束作用相当于给它装上了一条不可逾越的红线。我在实践里会把这份完整 Spec 命名成“编码上下文”在做完前面所有拆解后直接复制粘贴给 AI。效果最直观的一点是AI 生成的模型层代码几乎不需要改表字段和 Spec 能一一对上。Controller 层和 Service 层的代码也只需要为数不多的修饰性调整。4. 提示词模板把“字段级 Spec”变成可执行编码上下文4.1 一套实战验证过的提示词主体结构Spec 做得再完美如果喂给模型的方式不对输出质量照样打折。我这边经过大量项目的打磨整理出一套提示词模板直接贴在最后你复制改一改就能用。整套提示词分四层第一层是角色与目标。明确告诉 AI 它是一名资深后端工程师任务是根据用户给出的字段级 Spec 完成代码工程。角色设定不是可有可无的措辞它会激活模型在大量高质量代码数据上训练出来的模式。第二层是数据 Schema也就是前面做好的字段清单。这里要特别注意Schema 需要用代码块包裹不要让提示词里出现混乱的排版和解构方式模型对代码块的解析更准确字段名和类型不容易丢失。第三层是业务规则包括状态机、计算口径和全局规则。这些都写在普通正文位置作为约束条件。第四层是交付物要求。明确要求生成的代码包含哪些部分——实体类、Mapper 接口、Service 接口、ServiceImpl 实现、Controller 接口以及配套的 DTO。整个提示词的主体我按下面这种方式组织你是一名经验丰富的后端工程师。请严格根据以下字段级 Spec 和业务规则生成订单结算功能的完整后端代码。 要求 - 代码风格统一命名遵循驼峰规范 - 所有金额字段使用 decimal禁止使用 float - 所有接口需包含入参校验和异常处理 - 状态变更必须遵循给定的状态机流转规则 【数据 Schema】 表名order_main 字段列表 - id: bigint主键自增 - order_no: varchar(32)订单号唯一索引示例值 SO20250101120001 - user_id: bigint用户 ID示例值 1000234 - order_status: tinyint订单状态取值范围见状态机默认值 1 - total_amount: decimal(10,2)订单总额(含运费、含优惠后金额)默认值 0.00 - freight_amount: decimal(10,2)运费默认值 0.00 - coupon_discount_amount: decimal(10,2)优惠券抵扣额默认值 0.00 - created_at: datetime创建时间默认值 CURRENT_TIMESTAMP - updated_at: datetime更新时间默认值 CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP 【业务规则】 - 状态机1 待支付 - 2 已支付 - 3 待发货 - 4 已发货 - 5 已完成任意状态下可流转到 0 已取消 - 计算口径订单总额 商品总额 运费 - 优惠券抵扣额订单总额不得为负数 - 全局规则所有金额字段禁止使用浮点数时间字段统一存储 UTC记录任何状态变更的操作日志 【交付物】 生成以下文件 1. OrderMain 实体类 2. OrderMainMapper 接口及 XML 3. OrderService 接口及 OrderServiceImpl 实现 4. OrderController 控制器 5. 状态变更时对应的操作日志记录逻辑这套结构我反复用了大半年稳定性很高。如果你用的是不同 AI 工具只需要把分隔符换一下整体结构不用动。4.2 提示词的核心不是“说清楚”而是聚焦“不给幻觉空间”我在用这套方法时还有个更深的体会提示词的核心功能不是“描述你想要什么”而是“封死你不想要的”。大模型训练数据几乎什么代码都见过但它不知道什么是你最忌讳的。你的字段级 Spec 做得越细模型的自由发挥空间越小输出质量越稳。举个例子如果你不在提示词里写明“金额用 decimal”模型很可能按通用习惯生成 double 类型字段。短期看不出问题但等到对账或报表环节浮点精度误差就会变成事故。而只要你在“全局规则”里用一行字锁死这类幻觉就被彻底清除。类似的“幻觉高发区”还有主键生成策略自增还是雪花、时间字段类型datetime 还是 timestamp、软删标记有没有 deleted 字段、逻辑删除的字段命名deleted 还是 is_deleted。这些看起来都是小事但代码生成后如果每个模型都按自己喜好发挥你的代码库就会风格混乱。最好全部在提示词里定死。4.3 针对不同模型的参数与上下文长度适配不同 AI 模型对超长 Spec 的接受度不一样我也做了适配方案。如果你用上下文窗口较小的模型塞一整份字段级 Spec 可能超出限制这时候可以分块喂分两步走第一步只喂表结构和状态机让模型生成实体类与数据库脚本这一步上下文占用低模型能准确消化结构化内容。第二步再喂接口定义与业务规则让它生成 Service 层和 Controller 层因为这一步的输入输出已经依赖上一轮生成的实体类模型处理起来更连贯。如果你用的是上下文窗口超过 100K 的模型可以直接把整份 Spec 一次喂入甚至在后面追加上需求阶段产生的“行为-信息对照表”和“验收输入输出表”效果更好。我还建议生成代码后不要急着结束对话让模型再生成一份“API 接口文档”和“数据库建表 SQL”等于一份输入换来多份高价值产出连写文档的时间都省了。5. 从 Spec 到代码把图纸交给 AI 的过程与调优5.1 我的常用生成流程一次生成逐文件审查Spec 准备完毕提示词也写好后接下来就是实际生成环节。我习惯按下面的流程走先准备数据库建表 SQL这一步可以请 AI 单独生成也可以让它根据 Spec 里的 Schema 直接输出。拿到 SQL 后我先人工审一遍表结构重点看字段类型是否正确、索引是否缺失、默认值是否与 Spec 一致。表结构没有问题时再进入实体类和 Mapper 生成这一步基本上能一次通过的比例很高因为实体类和 SQL 的对应关系在 Spec 里已经被钉死了。Service 层和 Controller 层是工作量最大的环节我会重点检查三件事状态机是否在每个接口里被设置、金额计算是否遵循口径、异常处理是否覆盖了非法入参。AI 生成的代码往往在“主流程正确”上表现很好但异常分支经常遗漏比如用户传一个不存在的订单号时应该如何处理。这种分支逻辑我在代码审查时按“参数校验、业务校验、异常捕获”三层逐一过。全套代码生成后我还会用 AI 反向生成一份单元测试。测试用例直接参考我在需求拆解阶段做的“示例输入 预期输出”表。这个闭环非常实用相当于需求阶段的验收标准在代码阶段自动转化成了可执行的测试脚本。5.2 迭代提示词时重点优化的三个层次一次生成的代码很少十全十美。迭代调优提示词有三个层次按顺序推进每一步都会显著提升最终质量。第一层是“补上下文”。生成代码后发现某个方法实现错误原因多半是 Spec 里缺少对应的细节描述。比如生成订单列表接口时没有指定排序规则AI 默认按主键倒序。如果你需要按创建时间倒序就去 Spec 相应位置补一句然后重新生成。这层优化是最基础的也是频率最高的。第二层是“给示例”。纯文字说明有时不如一个例子直接。比如“订单状态变化的操作日志”要如何组织理论描述无论如何都不如一个示例日志条目录直观。每次给模型提供 1 到 2 个详细的输入输出示例出错的概率会下降很多。第三层是“定风格”。如果你在公司里维护长期项目代码风格统一很重要。可以在提示词里加一句“参照项目现有代码风格”让模型对齐格式。这个方法对前端项目特别管用除了逻辑层面的正确连组件命名和 CSS 命名风格都能一次性统一。5.3 AI 生成代码的审查清单与快速验收最后我把代码审查清单放在这里方便你直接对照执行数据字段审查每个字段是否与 Spec 中定义的类型、长度、默认值一致。状态机审查是否存在未按状态流转规则赋值的地方尤其在退款、取消场景是重灾区。金额精度审查全局搜索所有 float/double 类型字段重点确认金额、单价、折扣、余额等字段是否为 decimal。时间时区审查时间字段是否按统一约定存储接口返回时是否做了格式化处理。接口安全审查所有写操作接口是否有鉴权校验查询接口是否涉及越权访问。异常分支审查入参空值、超长、非法枚举时代码是否有明确的拒绝策略。这个清单我每次都会跑一遍熟练之后整套检查不超过二十分钟但它能挡住绝大多数线上事故。久而久之你会形成一种直觉看到 AI 生成的代码脑子里会自动浮现出一份待确认字段、待确认状态分支的清单而字段级 Spec 就是这份清单的源头。6. 搭一条可持续迭代的“需求-Spec-代码”流水线6.1 需求入库把零散诉求变成结构化需求卡片如果你只是偶尔用 AI 写一两个脚本前面的方法已经够用。但如果你想在日常开发中稳定使用这套能力我建议把整个流程升级成一条流水线每次只消耗少量精力却能持续产出高质量代码。流水线的第一站是“需求入库”。维护一张需求卡片每个卡片包含需求名称、业务目标、验收标准、涉及角色、关键路径。每当业务方或者你自己冒出一个新想法不要急着去敲提示词先把这些信息填进卡片。这一步的作用类似于“缓存”——你不必立刻做完整拆解但上游信息已经沉淀下来后面随时可以拿出来复用。我在实际项目中用表格工具沉淀需求卡片效果很好。每个卡片都有独立编号后续对所有字段级 Spec 的修改都有迹可寻。一旦这个环节形成习惯你会发现自己越来越不需要从头梳理因为大多数需求之间是有共性的字段级 Spec 的复用率会变高。6.2 半自动拆解复用一个需求域沉淀一套字段资产有了需求卡片之后第二站是把卡片转成 Spec。这一步在初始阶段需要人工参与但迭代后有一个非常实用的技巧按业务域沉淀一套“字段资产库”。例如在订单域里你会发现“金额类字段”“时间类字段”“状态类字段”的约束几乎完全一致。这些字段的定义整理好后后续同域的项目只需要复制过来微调即可。我手上有一套订单域的基础字段库包含金额类 8 个字段、状态类 6 个字段、时间类 4 个字段、基础审计字段 5 个任何订单相关的新需求进来这套字段库能一次性覆盖 70% 以上的字段设计需求剩下的 30% 才是这个项目独有的业务字段。这种做法最大的好处是维持了代码库的一致性。无论是哪个订单项目接手代码的人看到的字段命名、类型规范都是同一套风格维护成本直线下降。我自己维护这套资产库一年后新项目从需求到 Spec 的时间从半天压缩到了半小时。6.3 结合自动化和多 Agent 协作的长远玩法流水线再往后走还可以接入自动化环节。目前内部我把需求卡片到 Spec 的转化做了半自动化用规则模板AI 生成初稿人工只负责确认和修改。模板里固化了实体梳理字段表的格式AI 只需要按格式填充这比每次写一段全新提示词的稳定性要高得多。多 Agent 协作是把流水线再往前推一步。具体玩法是拆成三个角色需求分析 Agent 负责把一句话需求扩展成需求卡片Spec 生成 Agent 负责把需求卡片转成字段级 Spec编码 Agent 负责根据 Spec 生成代码。三个 Agent 之间通过文本交接每一个环节的输出即为下一个环节的输入。虽然这个方案还不能完全脱离人工质检但已经在把人的精力从“写代码-改代码”转移到“审 Spec-审代码”。这条路走到最后你真正售卖的核心价值不再是“会写代码”而是“会把业务拆成可执行的规格”。AI 负责翻译你负责画图纸。图纸画得多细AI 的施工就有多准。7. 避坑实录字段级 Spec 实践中的高频事故7.1 过度设计 Spec 导致 AI 生成代码“严重超重”我最初用字段级 Spec 时犯过一个相反方向的错误把能想到的所有字段、所有规则全部塞进去结果 AI 生成的代码异常庞大大量无用的校验、冗余的逻辑片段比需求本身还复杂读起来非常吃力。后来我反思这个问题的本质Spec 的粒度要服务于“消除歧义”而不是“穷尽一切可能”。如果一个字段含义明确、模式通用就只写它最基本的约束如果一个字段真的多分支、易误解才需要逐条展开。字段级 Spec 的重心是“让 AI 恰好知道它该知道的一切”多一分则冗余少一分则猜疑。找到这个平衡点需要一点刻意练习但回报极高。7.2 只写字段清单不写计算口径金额逻辑照样出错第二次大坑是字段清单写得很完整但计算口径没有写清楚。比如我定义了“total_amount”“freight_amount”却没定义“总额到底含不含运费、优惠券怎么分摊”。AI 生成的代码看起来字段齐全但对账时总发现数据对不上追踪很久才发现是计算口径不一致。现在我把“计算口径”单独列为一场专门的拆解步骤任何涉及聚合计算的字段都必须有一段“公式化描述”。这个描述不一定是复杂的数学表达式可以是简单的一句话但必须无歧义。这一条比字段清单本身还关键。7.3 不小心让模型自由发挥命名和枚举值第三次教训来自命名和枚举值。我在一份 Spec 里写了“订单状态”但没有写明具体枚举值结果模型自由发挥了一套状态枚举——有的状态含义相同但值不同有的值是跳跃的、不连续的导致前后端对接时鸡同鸭讲。还有一次我少写了字段命名规范模型生成了 order_no、orderno、orderNum 三种风格混搭的命名难以维护。从那以后“命名预先定死、枚举逐个列出”成了不可动摇的底线。字段级 Spec 意味着连字典表值都要逐个列出来不给模型自由发挥的空间它才能真正成为“图纸”。7.4 字段级 Spec 速查表与避坑清单我把实践里沉淀下来的检查要点整理成速查表你可以直接抄走检查项自查要点常见失败现象目标可验收性是否有一句可证明做成的话代码写完没人能确认对错路径覆盖度用户动作是否逐一拆齐漏操作导致缺接口字段类型统一金额/时间/状态类型是否规范类型混乱导致返工默认值完整每个字段是否都有默认值空指针、数据残缺枚举值完备每个状态/来源取值范围是否列全前后端取值不一致计算口径清晰聚合字段是否有公式说明对账不一致问题隐蔽状态流转条件每个状态变更的前置条件是否写明状态跳变产生脏数据异常场景描述非法输入时如何处理是否写明只覆盖主流程异常漏处理时间与时区规则UTC 存储与展示转换是否说明时间八小时偏差这张表我每次开工前都会过一遍实测能让返工率降低一半以上。你也可以把它内化成自己的检查习惯时间长了拆解速度会越来越快对模糊的容忍度会越来越低。我个人在这条路上踩过不少坑才走到现在的流程。早期总觉得“Spec 这么细还不如自己写代码”但真经过几个中型项目的验证后观点完全转变一份字段级 Spec 的价值不在于让 AI 写出的代码多惊艳而在于它逼着我把需求想清楚把边界摸透彻把最容易翻车的细节前置暴露。AI 只是放大器——输入模糊它就放大模糊输入精确它就放大精确。把需求做到字段级可能是当前这个阶段投入产出比最高的一项工程能力。 
长河君 · 2026/10/6 6:24:51 · 阅读 1.2k AI写代码总翻车？用字段级Spec让AI从猜需求变成照着图纸施工
我见过太多人用 AI 写代码上来就一句“帮我写个登录功能”模型也确实给了能跑的代码但一接真实项目就崩。不是缺参数校验就是字段名对不上再不然连业务状态都理解偏了。问题不在 AI在于你喂给它的需求本身就是模糊的。做需求的人脑子里有全景图可落到提示词里只剩一句话AI 只能靠猜。这一篇不聊花活就讲一条我从“一句话需求”走到“字段级 Spec”的完整实践路径。核心是把零散的业务诉求拆解成可直接执行的代码上下文让 AI 从“猜需求”变成“照着图纸施工”。适合正在用 AI 提效的开发、测试、产品经理也适合想把自己手头项目 AI 化的个人开发者。1. 需求拆解为什么一句话需求让 AI 必翻车1.1 AI 的真实工作方式与“上下文缺口”先说个底层认知大模型生成代码本质是“基于你提供的上下文做概率续写”。你给的上下文越具体续写落在正确路径上的概率就越高上下文越模糊它就只能调用训练数据里的“通用套路”来填补空白。一句“帮我写一个订单结算功能”对 AI 来说意味着无数种解释——结算口径是什么含不含运费优惠券分摊规则退款场景怎么处理这些在人类沟通里可以靠默契和追问解决但在提示词里不存在默契。AI 会把最常见的假设填进去而这个假设往往跟你的业务对不上。我把这个现象叫“上下文缺口”。缺得越多AI 就越是按照“大众化的技术想象”来生成而大众化想象恰恰是离真实业务最远的。所以你会发现一个悖论越简单的提示词AI 写出来的代码越“像样”但也越没法用。想解决这个问题就需要把需求从“一句话”逐步放大到“代码可执行单元”的粒度最终得到一份字段级的 Spec。字段级就是每个字段的名称、类型、含义、取值范围、校验规则、默认值全部变成确定信息。代码的每一个接口、每一个数据模型都能在 Spec 里找到对应来源。1.2 常见的三层需求模糊地带结合我自己的项目复盘模糊地带通常集中在三层目标层的模糊只说了“要做 X”没说清楚“X 要实现什么业务结果”。比如“做积分系统”但积分是营销工具还是权益体系是消费后累积还是行为激励方向不同表结构完全不同。路径层的模糊目标明确了但实现路径没定。比如“用户登录”是用手机号还是邮箱验证码还是密码接不接第三方 OAuth每个路径都是不同的代码分支提示词里不说AI 就随机挑一个。约束层的模糊更隐蔽但致命。性能要求、安全规范、兼容范围、未来扩展性这些如果不在 Spec 里显式写出AI 默认只追求“实现功能”完全不考虑表字段是否有索引、接口是否有鉴权、数据量大了是否会爆炸。一句话需求之所以让 AI 翻车本质上是这三层模糊同时存在而 AI 被迫在模糊中做了一连串“默认选择”。等代码生成完你以为得到的是答案其实是无数个未知假设的混合体。字段级 Spec 要做的就是把这些假设全部消除掉。2. 从“模糊意图”到“可执行需求”的四步拆解法2.1 第一步目标澄清——用一句“可验收的话”锁定方向我在实践里总结出一个硬规则写任何提示词之前先逼自己用一句话回答——做成之后用什么指标或现象证明它做成了比如最初一句话需求是“给我做一个订单备注功能”这没法直接写代码。我先问自己一句这个功能要解决什么答案是“销售在订单详情页能补充客户的特殊要求方便仓库拣货时看到”。这句“方便仓库拣货时看到”就是整个设计的北极星。接着把它转成可验收的话“销售在订单详情页添加备注后备注在订单列表、详情页、拣货单三个位置可见且可编辑”。有了这句话后面所有字段设计都有了判断依据。这一步很容易被跳过但它决定了后面所有内容的走向。目标没定清楚往下走的每一步都是在沙滩上盖楼Spec 写得越详细返工的代价越大。而且这一步要写进提示词作为 AI 生成代码时的“最高指导原则”——后续如果模型生成的方案出现偏差就用这句话来校准它。2.2 第二步路径设计——把黑盒需求变成一组“看得见的动作”目标明确后第二步是拆路径。路径拆解遵循一个朴素原则如果你是用户你会从这个功能里索取什么、提交什么还是用订单备注来说。用户侧的动作拆出来就是打开订单详情页看到已有备注点击编辑或新增填写文本内容保存并生效这些动作共同指向一个数据集合备注内容本身。但仅拆出动作还不够还要给动作配信息。用户在哪一屏看到备注格式限制多少字可不可传图片这些每个都对应到后续的一个字段或一项校验逻辑。这一步的产出是“行为-信息”对照表。我一般用表格记录下来一列写用户动作一列写动作涉及的信息项一列写信息项的格式预期。这张表就是下一步字段级拆解的原材料。它把黑盒需求变成了一组看得见的动作回路AI 得到它之后生成代码就相当于有人给它画好了“用户的完整行走路径”它只需要沿着路径铺设接口。2.3 第三步约束收敛——明确边界、规则与例外路径有了接下来做约束收敛。约束包括四类缺一不可字段规则约束每个字段的类型、长度、可选性、默认值。业务规则约束比如“备注在订单发货后不可修改”这种条件必须在 Spec 里固化否则模型不会自动替你想。技术大坝约束最大文本长度、接口超时、是否需要记录操作人和时间这些都属于技术坝不写就等于没有。边界例外约束空值怎么处理、超长文本怎么截断、并发编辑怎么处理。约束收敛不是一次头脑风暴还是一轮“追问式对话”。我的做法是把自己当成采访者反复问“如果……怎么办”。如果用户什么都不填直接保存会怎样如果备注内容超过 500 字怎样如果订单已经发货了还能不能改每一个“如果”都会逼出一个规则规则落到纸面上就是字段级 Spec 的一部分。我踩过的大坑是只写了“正常路径”的约束忘了“异常路径”。比如订单备注正常路径是“填写-保存-可见”但异常路径“发货后还能不能改”没写AI 生成代码时就完全不做状态判断导致线上出现已发货订单被随意改备注的 bug。这种问题代码层面查不出错全是需求层面的漏洞。2.4 第四步验收描述——用“示例输入预期输出”封死歧义最后一步是我个人最推荐的杀手锏给 AI 提供“示例输入 预期输出”的成对数据。它的作用相当于给需求文档配上了可执行的测试用例。举个例子为了让模型准确实现备注字段的“文本截断”我在 Spec 里写了这么一条输入用户粘贴一段 600 字文本到备注框预期输出系统存储且只存储前 500 字界面提示“备注超出 500 字限制多余内容已截断”这样一个具体的“输入-输出”对比任何文字都要有约束力。因为大模型本质上是“模式处理器”你给它一个小票级的输入输出对应关系它生成代码的时候就会不自觉地沿用这种模式而不是自己发明一种新的截断策略。验收描述这条我建议做两张表一张是“正常业务输入输出表”覆盖主流程一张是“异常场景输入输出表”覆盖边界条件。两张表全部写进提示词里代码生成后可以直接拿去做测试用例的蓝本。我实测下来AI 生成的代码通过验收测试的比例至少提升一倍。3. 字段级 Spec 的实操拆解以“订单结算功能”为例3.1 从实体梳理到字段清单这一节我用一个真实做过的案例来演示从零开始把“帮我写一个订单结算功能”拆到字段级 Spec。整个过程中不涉及任何代码但你拿着这份 Spec 去问任何 AI 工具生成的代码会比直接问“写个订单结算功能”靠谱一个数量级。我先梳理实体。订单结算功能涉及的实体有四张表订单主表、订单商品明细、结算单、结算明细。对于每一张表这时候还不急着写字段而是先明确这个实体解决什么问题。订单主表解决“这一单是谁的、总额多少、状态如何”结算单解决“这一批订单什么时候结算、结了多少钱”两套数据是分开管理的不能混在一张表里。实体明确后开始逐字段拆解。以订单主表为例字段拆解分五个维度业务字段、状态字段、金额字段、时间字段、审计字段。业务字段至少要包含订单号、用户 ID、订单来源、收货信息。订单号不用多说天然主键用户 ID 要注明是 long 还是 string订单来源如果是多端共用必须明确取值范围比如“APP/小程序/后台录入”收货信息是拆开存还是合并存要在这时候就定否则后续接口的入参出参全是模糊的。状态字段是重灾区。很多人只写一个“订单状态”但真实业务里订单状态是一个状态机至少有待支付、已支付、待发货、已发货、已完成、已取消。每个状态之间还可能有流转条件这些都应该在 Spec 里用一张状态表说明而不是丢给 AI 自己猜。金额字段则有一个极其常见的坑——“金额用什么类型”。我强调三遍金额绝不用 float。凡是涉及金额、积分、折扣这类精确计算的字段一律用 decimal精度明确到小数点后 2 位。这个细节如果不在字段级 Spec 里写明AI 生成的代码十有八九会用通用数字类型表面上跑得通一旦对账就出偏差而且是那种极难排查的隐蔽偏差。3.2 字段级说明书的六要素模板单个字段的说明书我给每个字段统一配置六个要素。这六要素不是我想出来的而是在多次返工中总结出来的最小完备集合字段名代码中实际使用的命名预先确定避免 AI 自由发挥出奇怪命名。字段类型与长度存储层面的精确类型和最大长度。业务含义这个字段在业务里到底代表什么杜绝歧义。默认值不传值时给什么。校验规则允许的取值边界、正则、范围。示例值一个真实的样例数据让模型有“感性认识”。举一个具体字段作例子——优惠券分摊金额字段名coupon_discount_amount类型decimal(10,2)精确到分业务含义本订单通过优惠券抵扣的总金额按商品金额比例分摊至各明细行默认值0.00校验规则非负且不超过订单商品总额多明细行分摊金额之和必须等于订单级优惠总金额示例值12.50有了这套结构任何一个字段丢给 AI它都不会产生二义性。整张表的所有字段都按这个格式写完后数据结构就是“死图纸”AI 的任务不再是设计而是翻译。不要小看“默认值”这一要素——很多 AI 生成代码跑不通就是因为某个字段没有默认值或者默认值给错了方向一旦统一在 Spec 里给定这类问题直接清零。3.3 状态机、计算口径与全局规则如何写入 Spec字段清单完成后还需要加入三类全局规则字段清单只解决“有什么数据”下面这三类规则解决“数据如何变化和计算”。状态机订单状态不是一个字段那么简单还包含状态与状态之间的流转条件。比如“已支付”到“待发货”前提条件是支付回调成功且订单金额已对账“待发货”到“已发货”前提条件是仓库已打单并出库。这些流转条件要逐一写进 Spec甚至可以给 AI 提供一个状态流转表格左列是当前状态中列是触发动作右列是目标状态。计算口径所有的聚合类字段——订单总额、应结金额、退款总额等必须写明计算口径。比如订单总额是否包含运费如果包含是哪些情况下包含运费参与优惠券分摊吗这些口径问题如果在代码阶段才去“问 AI”AI 只能给你一个可能正确、也可能不正确的答案。在 Spec 阶段你要用一句话锁死它订单总额 商品总额 用户实付运费 – 优惠券降额。全局规则适合放在 Spec 开头作为“最高原则”。例如所有金额字段禁止使用浮点类型所有时间字段统一按 UTC 存储、展示时按用户时区转换所有接口必须对入参做空值校验和长度校验所有涉及金额变动的操作必须记录操作日志。这些全局规则会在模型生成每一个接口时持续发挥约束作用相当于给它装上了一条不可逾越的红线。我在实践里会把这份完整 Spec 命名成“编码上下文”在做完前面所有拆解后直接复制粘贴给 AI。效果最直观的一点是AI 生成的模型层代码几乎不需要改表字段和 Spec 能一一对上。Controller 层和 Service 层的代码也只需要为数不多的修饰性调整。4. 提示词模板把“字段级 Spec”变成可执行编码上下文4.1 一套实战验证过的提示词主体结构Spec 做得再完美如果喂给模型的方式不对输出质量照样打折。我这边经过大量项目的打磨整理出一套提示词模板直接贴在最后你复制改一改就能用。整套提示词分四层第一层是角色与目标。明确告诉 AI 它是一名资深后端工程师任务是根据用户给出的字段级 Spec 完成代码工程。角色设定不是可有可无的措辞它会激活模型在大量高质量代码数据上训练出来的模式。第二层是数据 Schema也就是前面做好的字段清单。这里要特别注意Schema 需要用代码块包裹不要让提示词里出现混乱的排版和解构方式模型对代码块的解析更准确字段名和类型不容易丢失。第三层是业务规则包括状态机、计算口径和全局规则。这些都写在普通正文位置作为约束条件。第四层是交付物要求。明确要求生成的代码包含哪些部分——实体类、Mapper 接口、Service 接口、ServiceImpl 实现、Controller 接口以及配套的 DTO。整个提示词的主体我按下面这种方式组织你是一名经验丰富的后端工程师。请严格根据以下字段级 Spec 和业务规则生成订单结算功能的完整后端代码。 要求 - 代码风格统一命名遵循驼峰规范 - 所有金额字段使用 decimal禁止使用 float - 所有接口需包含入参校验和异常处理 - 状态变更必须遵循给定的状态机流转规则 【数据 Schema】 表名order_main 字段列表 - id: bigint主键自增 - order_no: varchar(32)订单号唯一索引示例值 SO20250101120001 - user_id: bigint用户 ID示例值 1000234 - order_status: tinyint订单状态取值范围见状态机默认值 1 - total_amount: decimal(10,2)订单总额(含运费、含优惠后金额)默认值 0.00 - freight_amount: decimal(10,2)运费默认值 0.00 - coupon_discount_amount: decimal(10,2)优惠券抵扣额默认值 0.00 - created_at: datetime创建时间默认值 CURRENT_TIMESTAMP - updated_at: datetime更新时间默认值 CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP 【业务规则】 - 状态机1 待支付 - 2 已支付 - 3 待发货 - 4 已发货 - 5 已完成任意状态下可流转到 0 已取消 - 计算口径订单总额 商品总额 运费 - 优惠券抵扣额订单总额不得为负数 - 全局规则所有金额字段禁止使用浮点数时间字段统一存储 UTC记录任何状态变更的操作日志 【交付物】 生成以下文件 1. OrderMain 实体类 2. OrderMainMapper 接口及 XML 3. OrderService 接口及 OrderServiceImpl 实现 4. OrderController 控制器 5. 状态变更时对应的操作日志记录逻辑这套结构我反复用了大半年稳定性很高。如果你用的是不同 AI 工具只需要把分隔符换一下整体结构不用动。4.2 提示词的核心不是“说清楚”而是聚焦“不给幻觉空间”我在用这套方法时还有个更深的体会提示词的核心功能不是“描述你想要什么”而是“封死你不想要的”。大模型训练数据几乎什么代码都见过但它不知道什么是你最忌讳的。你的字段级 Spec 做得越细模型的自由发挥空间越小输出质量越稳。举个例子如果你不在提示词里写明“金额用 decimal”模型很可能按通用习惯生成 double 类型字段。短期看不出问题但等到对账或报表环节浮点精度误差就会变成事故。而只要你在“全局规则”里用一行字锁死这类幻觉就被彻底清除。类似的“幻觉高发区”还有主键生成策略自增还是雪花、时间字段类型datetime 还是 timestamp、软删标记有没有 deleted 字段、逻辑删除的字段命名deleted 还是 is_deleted。这些看起来都是小事但代码生成后如果每个模型都按自己喜好发挥你的代码库就会风格混乱。最好全部在提示词里定死。4.3 针对不同模型的参数与上下文长度适配不同 AI 模型对超长 Spec 的接受度不一样我也做了适配方案。如果你用上下文窗口较小的模型塞一整份字段级 Spec 可能超出限制这时候可以分块喂分两步走第一步只喂表结构和状态机让模型生成实体类与数据库脚本这一步上下文占用低模型能准确消化结构化内容。第二步再喂接口定义与业务规则让它生成 Service 层和 Controller 层因为这一步的输入输出已经依赖上一轮生成的实体类模型处理起来更连贯。如果你用的是上下文窗口超过 100K 的模型可以直接把整份 Spec 一次喂入甚至在后面追加上需求阶段产生的“行为-信息对照表”和“验收输入输出表”效果更好。我还建议生成代码后不要急着结束对话让模型再生成一份“API 接口文档”和“数据库建表 SQL”等于一份输入换来多份高价值产出连写文档的时间都省了。5. 从 Spec 到代码把图纸交给 AI 的过程与调优5.1 我的常用生成流程一次生成逐文件审查Spec 准备完毕提示词也写好后接下来就是实际生成环节。我习惯按下面的流程走先准备数据库建表 SQL这一步可以请 AI 单独生成也可以让它根据 Spec 里的 Schema 直接输出。拿到 SQL 后我先人工审一遍表结构重点看字段类型是否正确、索引是否缺失、默认值是否与 Spec 一致。表结构没有问题时再进入实体类和 Mapper 生成这一步基本上能一次通过的比例很高因为实体类和 SQL 的对应关系在 Spec 里已经被钉死了。Service 层和 Controller 层是工作量最大的环节我会重点检查三件事状态机是否在每个接口里被设置、金额计算是否遵循口径、异常处理是否覆盖了非法入参。AI 生成的代码往往在“主流程正确”上表现很好但异常分支经常遗漏比如用户传一个不存在的订单号时应该如何处理。这种分支逻辑我在代码审查时按“参数校验、业务校验、异常捕获”三层逐一过。全套代码生成后我还会用 AI 反向生成一份单元测试。测试用例直接参考我在需求拆解阶段做的“示例输入 预期输出”表。这个闭环非常实用相当于需求阶段的验收标准在代码阶段自动转化成了可执行的测试脚本。5.2 迭代提示词时重点优化的三个层次一次生成的代码很少十全十美。迭代调优提示词有三个层次按顺序推进每一步都会显著提升最终质量。第一层是“补上下文”。生成代码后发现某个方法实现错误原因多半是 Spec 里缺少对应的细节描述。比如生成订单列表接口时没有指定排序规则AI 默认按主键倒序。如果你需要按创建时间倒序就去 Spec 相应位置补一句然后重新生成。这层优化是最基础的也是频率最高的。第二层是“给示例”。纯文字说明有时不如一个例子直接。比如“订单状态变化的操作日志”要如何组织理论描述无论如何都不如一个示例日志条目录直观。每次给模型提供 1 到 2 个详细的输入输出示例出错的概率会下降很多。第三层是“定风格”。如果你在公司里维护长期项目代码风格统一很重要。可以在提示词里加一句“参照项目现有代码风格”让模型对齐格式。这个方法对前端项目特别管用除了逻辑层面的正确连组件命名和 CSS 命名风格都能一次性统一。5.3 AI 生成代码的审查清单与快速验收最后我把代码审查清单放在这里方便你直接对照执行数据字段审查每个字段是否与 Spec 中定义的类型、长度、默认值一致。状态机审查是否存在未按状态流转规则赋值的地方尤其在退款、取消场景是重灾区。金额精度审查全局搜索所有 float/double 类型字段重点确认金额、单价、折扣、余额等字段是否为 decimal。时间时区审查时间字段是否按统一约定存储接口返回时是否做了格式化处理。接口安全审查所有写操作接口是否有鉴权校验查询接口是否涉及越权访问。异常分支审查入参空值、超长、非法枚举时代码是否有明确的拒绝策略。这个清单我每次都会跑一遍熟练之后整套检查不超过二十分钟但它能挡住绝大多数线上事故。久而久之你会形成一种直觉看到 AI 生成的代码脑子里会自动浮现出一份待确认字段、待确认状态分支的清单而字段级 Spec 就是这份清单的源头。6. 搭一条可持续迭代的“需求-Spec-代码”流水线6.1 需求入库把零散诉求变成结构化需求卡片如果你只是偶尔用 AI 写一两个脚本前面的方法已经够用。但如果你想在日常开发中稳定使用这套能力我建议把整个流程升级成一条流水线每次只消耗少量精力却能持续产出高质量代码。流水线的第一站是“需求入库”。维护一张需求卡片每个卡片包含需求名称、业务目标、验收标准、涉及角色、关键路径。每当业务方或者你自己冒出一个新想法不要急着去敲提示词先把这些信息填进卡片。这一步的作用类似于“缓存”——你不必立刻做完整拆解但上游信息已经沉淀下来后面随时可以拿出来复用。我在实际项目中用表格工具沉淀需求卡片效果很好。每个卡片都有独立编号后续对所有字段级 Spec 的修改都有迹可寻。一旦这个环节形成习惯你会发现自己越来越不需要从头梳理因为大多数需求之间是有共性的字段级 Spec 的复用率会变高。6.2 半自动拆解复用一个需求域沉淀一套字段资产有了需求卡片之后第二站是把卡片转成 Spec。这一步在初始阶段需要人工参与但迭代后有一个非常实用的技巧按业务域沉淀一套“字段资产库”。例如在订单域里你会发现“金额类字段”“时间类字段”“状态类字段”的约束几乎完全一致。这些字段的定义整理好后后续同域的项目只需要复制过来微调即可。我手上有一套订单域的基础字段库包含金额类 8 个字段、状态类 6 个字段、时间类 4 个字段、基础审计字段 5 个任何订单相关的新需求进来这套字段库能一次性覆盖 70% 以上的字段设计需求剩下的 30% 才是这个项目独有的业务字段。这种做法最大的好处是维持了代码库的一致性。无论是哪个订单项目接手代码的人看到的字段命名、类型规范都是同一套风格维护成本直线下降。我自己维护这套资产库一年后新项目从需求到 Spec 的时间从半天压缩到了半小时。6.3 结合自动化和多 Agent 协作的长远玩法流水线再往后走还可以接入自动化环节。目前内部我把需求卡片到 Spec 的转化做了半自动化用规则模板AI 生成初稿人工只负责确认和修改。模板里固化了实体梳理字段表的格式AI 只需要按格式填充这比每次写一段全新提示词的稳定性要高得多。多 Agent 协作是把流水线再往前推一步。具体玩法是拆成三个角色需求分析 Agent 负责把一句话需求扩展成需求卡片Spec 生成 Agent 负责把需求卡片转成字段级 Spec编码 Agent 负责根据 Spec 生成代码。三个 Agent 之间通过文本交接每一个环节的输出即为下一个环节的输入。虽然这个方案还不能完全脱离人工质检但已经在把人的精力从“写代码-改代码”转移到“审 Spec-审代码”。这条路走到最后你真正售卖的核心价值不再是“会写代码”而是“会把业务拆成可执行的规格”。AI 负责翻译你负责画图纸。图纸画得多细AI 的施工就有多准。7. 避坑实录字段级 Spec 实践中的高频事故7.1 过度设计 Spec 导致 AI 生成代码“严重超重”我最初用字段级 Spec 时犯过一个相反方向的错误把能想到的所有字段、所有规则全部塞进去结果 AI 生成的代码异常庞大大量无用的校验、冗余的逻辑片段比需求本身还复杂读起来非常吃力。后来我反思这个问题的本质Spec 的粒度要服务于“消除歧义”而不是“穷尽一切可能”。如果一个字段含义明确、模式通用就只写它最基本的约束如果一个字段真的多分支、易误解才需要逐条展开。字段级 Spec 的重心是“让 AI 恰好知道它该知道的一切”多一分则冗余少一分则猜疑。找到这个平衡点需要一点刻意练习但回报极高。7.2 只写字段清单不写计算口径金额逻辑照样出错第二次大坑是字段清单写得很完整但计算口径没有写清楚。比如我定义了“total_amount”“freight_amount”却没定义“总额到底含不含运费、优惠券怎么分摊”。AI 生成的代码看起来字段齐全但对账时总发现数据对不上追踪很久才发现是计算口径不一致。现在我把“计算口径”单独列为一场专门的拆解步骤任何涉及聚合计算的字段都必须有一段“公式化描述”。这个描述不一定是复杂的数学表达式可以是简单的一句话但必须无歧义。这一条比字段清单本身还关键。7.3 不小心让模型自由发挥命名和枚举值第三次教训来自命名和枚举值。我在一份 Spec 里写了“订单状态”但没有写明具体枚举值结果模型自由发挥了一套状态枚举——有的状态含义相同但值不同有的值是跳跃的、不连续的导致前后端对接时鸡同鸭讲。还有一次我少写了字段命名规范模型生成了 order_no、orderno、orderNum 三种风格混搭的命名难以维护。从那以后“命名预先定死、枚举逐个列出”成了不可动摇的底线。字段级 Spec 意味着连字典表值都要逐个列出来不给模型自由发挥的空间它才能真正成为“图纸”。7.4 字段级 Spec 速查表与避坑清单我把实践里沉淀下来的检查要点整理成速查表你可以直接抄走检查项自查要点常见失败现象目标可验收性是否有一句可证明做成的话代码写完没人能确认对错路径覆盖度用户动作是否逐一拆齐漏操作导致缺接口字段类型统一金额/时间/状态类型是否规范类型混乱导致返工默认值完整每个字段是否都有默认值空指针、数据残缺枚举值完备每个状态/来源取值范围是否列全前后端取值不一致计算口径清晰聚合字段是否有公式说明对账不一致问题隐蔽状态流转条件每个状态变更的前置条件是否写明状态跳变产生脏数据异常场景描述非法输入时如何处理是否写明只覆盖主流程异常漏处理时间与时区规则UTC 存储与展示转换是否说明时间八小时偏差这张表我每次开工前都会过一遍实测能让返工率降低一半以上。你也可以把它内化成自己的检查习惯时间长了拆解速度会越来越快对模糊的容忍度会越来越低。我个人在这条路上踩过不少坑才走到现在的流程。早期总觉得“Spec 这么细还不如自己写代码”但真经过几个中型项目的验证后观点完全转变一份字段级 Spec 的价值不在于让 AI 写出的代码多惊艳而在于它逼着我把需求想清楚把边界摸透彻把最容易翻车的细节前置暴露。AI 只是放大器——输入模糊它就放大模糊输入精确它就放大精确。把需求做到字段级可能是当前这个阶段投入产出比最高的一项工程能力。