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 速查表与避坑清单

我把实践里沉淀下来的检查要点整理成速查表，你可以直接抄走：

这张表我每次开工前都会过一遍，实测能让返工率降低一半以上。你也可以把它内化成自己的检查习惯，时间长了，拆解速度会越来越快，对模糊的容忍度会越来越低。

我个人在这条路上踩过不少坑才走到现在的流程。早期总觉得“Spec 这么细，还不如自己写代码”，但真经过几个中型项目的验证后，观点完全转变：一份字段级 Spec 的价值不在于让 AI 写出的代码多惊艳，而在于它逼着我把需求想清楚，把边界摸透彻，把最容易翻车的细节前置暴露。AI 只是放大器——输入模糊，它就放大模糊；输入精确，它就放大精确。把需求做到字段级，可能是当前这个阶段投入产出比最高的一项工程能力。