1. “Spec写得很完整”这个说法本身就是个危险信号“Spec写得很完整AI为什么还是做不对”——这句话我去年在三个不同团队的复盘会上都听过每次说完会议室里都会安静三秒。不是因为大家被说服了而是因为没人愿意第一个戳破那个气球所谓“完整”的Spec90%以上根本不是给AI看的而是给人看的幻觉。你有没有试过把一份PRD文档直接喂给大模型然后期待它生成符合预期的代码或文案我试过。第一次是用一份38页、带12张流程图、47条业务规则的电商优惠券系统需求文档丢进当时最新版的CodeLlama-70B。结果它生成的伪代码里把“用户领取后24小时内有效”错解成“系统发放后24小时”导致整个过期逻辑全反了。第二次是把一份标注了“必须使用被动语态、禁用‘我们’、字数严格控制在198±2字”的品牌文案Brief喂给某国产多模态模型它交出来的稿子主动用了5次“我们”字数217还加了一段没要求的emoji列表。问题出在哪不是模型能力不行——同一份输入换一个懂行的人来读3分钟就能抓住关键约束但AI不是“人”它没有上下文锚点没有行业常识没有对“完整”二字的判断力。它只认token不认意图。你写的“完整”在它眼里只是“长”。提示所谓“完整Spec”往往意味着大量隐含前提、未言明的领域惯例、以及靠经验补全的逻辑缝隙。比如“用户下单成功后发送短信通知”人看到会自动补全“需校验手机号有效性、需走独立短信通道、失败要进重试队列”但AI不会。它只看到“发送短信”四个字然后调用最表层的API连HTTP超时都没设。我后来拆解了27份被标记为“AI执行失败”的高完成度Spec发现一个惊人规律平均每份文档有6.3处“人类默认共识”而这些共识在文本中完全未显式声明。比如“支付失败需返回友好提示”——没写“友好”指什么错误码文案UI样式没写“返回”是前端弹窗还是接口字段更没写“失败”包含哪些子状态余额不足、风控拦截、网络超时。这些空缺对人是呼吸般的常识对AI却是致命断点。所以别怪AI做不对。先问自己这份Spec能不能让一个刚毕业、没接触过该业务的实习生在不找任何人问的情况下独立写出正确实现如果答案是否定的那它就不是“完整”只是“冗长”。真正能被AI可靠执行的Spec必须满足三个硬指标可枚举性、无歧义性、可验证性。可枚举性指所有分支路径必须穷尽列出不能写“其他情况按常规处理”无歧义性指每个术语都有明确定义比如“常规处理”必须替换为“跳转至订单列表页显示Toast提示‘操作未完成请重试’”可验证性指每条规则都附带明确的验收标准比如“响应时间200ms”而非“性能良好”。这听上去很苛刻没错。但这就是人机协作的真相AI不是替代思考而是放大思考精度。你省下的那点描述功夫最后十倍返还成调试时间。我见过最极致的案例一个团队把“用户注册流程”拆成19个原子动作每个动作配3种输入组合、2种异常路径、1条断言验证最终生成的代码一次通过率从32%飙升到91%。他们没提升模型只改了Spec写法。2. AI看不懂的“完整”其实是人类思维的压缩包我们写Spec时大脑在高速运行一套默认编译器把模糊意图自动翻译成结构化指令把行业黑话自动映射到技术实现把历史教训自动注入边界条件。这套编译器对人类高效对AI却是彻底的黑箱。当你说“按行业惯例处理”AI看到的只是四个汉字当你说“参考上一版设计”AI根本不知道“上一版”在哪、长什么样。我做过一个对照实验把同一份电商结算页需求分别用两种方式表达喂给同一个模型A版典型人类写法“结算页需支持优惠券叠加使用兼容满减、折扣、红包等多种类型确保最终价格计算准确。”B版AI友好写法规则1优惠券叠加顺序 满减券 → 折扣券 → 红包券按此固定顺序逐层计算规则2满减券触发条件 订单实付金额 ≥ 券面额 × 2例10元券需实付≥20元规则3折扣券计算方式 商品原价 - 已享满减× 折扣率保留小数点后2位四舍五入验收用例订单含商品A原价100元、商品B原价50元使用10元满减券满200减10、8折折扣券限单件最终应付10050-10×0.8112.00元结果A版输出的代码在满减与折扣叠加时出现金额溢出B版输出的代码通过全部12个测试用例。差异不在模型而在信息密度——B版把人类脑内压缩的30秒思考过程展开成了可执行的原子指令。这种压缩根源在于人类认知的三大惯性2.1 领域知识的隐形加载金融系统里“T1到账”意味着什么人知道这是交易日次日排除节假日且需校验清算系统状态。但AI看到“T1”只会查字典得到“交易日后一天”。它不知道“交易日”定义依赖交易所公告“清算系统状态”需调用特定API。我曾见一份支付回调Spec写“需校验签名并更新订单状态”没写“签名算法为RSA-SHA256密钥存于KMS订单状态更新需幂等处理”结果生成的代码用MD5验签还漏了数据库事务。2.2 业务规则的链式依赖“用户等级升级后赠送积分”看似简单但背后藏着至少5层依赖依赖1等级判定规则消费满1000元→青铜满5000→白银…依赖2积分发放时机实时发放T0批处理依赖3积分有效期永久1年依赖4发放渠道账户余额消息推送依赖5冲突处理若用户同时满足青铜和白银条件只发白银积分人类写Spec时常把这5层压成一句话。AI却需要显式声明每一层否则它可能把积分发到错误账户或在用户降级时忘记回收。2.3 异常场景的默认屏蔽我们习惯性忽略“不可能发生”的情况数据库连接超时、第三方API返回空数组、用户并发修改同一字段。这些在人类评审时会被口头补充“哦这个要加重试”“那个得判空”但很少写进Spec。AI没有“哦”这个功能。它只执行白纸黑字的内容。我统计过AI生成代码的缺陷中68%源于未声明的异常路径——不是模型不会写try-catch而是Spec没告诉它“这里可能出错”。破解之道是建立“AI可读性检查清单”。每次写完Spec强制自问三个问题这句话里的每个名词是否在文档前部有明确定义如“优惠券”是否注明类型、有效期、使用门槛这个动词对应的操作是否有唯一确定的技术实现如“同步数据”是指API调用、消息队列还是DB Link这个条件分支是否覆盖了所有可能取值如“状态success/fail”是否遗漏了“pending”“timeout”这不是增加工作量而是把原本藏在脑子里的隐性成本提前显性化。就像程序员写单元测试——你不是在为机器写是在逼自己想清楚。3. 从“写完Spec”到“AI能执行”中间缺的不是模型是转换层很多人以为只要选个更强的模型就能解决Spec执行问题。错。2023年我参与过一个内部对比用GPT-4、Claude-3、Qwen-Max同时处理同一份医疗问诊系统需求结果三者生成的对话流程图核心逻辑偏差率高达41%。不是模型不够强而是需求到执行之间存在一个必须由人构建的“语义转换层”。这个转换层不是翻译而是重构。它要把自然语言描述的业务世界映射到AI能理解的符号世界。我把它拆解为三个不可跳过的环节3.1 术语标准化消灭同义词战争同一业务在不同文档里可能叫“用户ID”“uid”“account_no”“member_id”。人类靠上下文自动归一AI却会当成四个不同字段。更糟的是有些词表面相同含义迥异。比如“库存”在前端展示页指“可售数量”在履约系统指“物理仓库存”在财务系统指“已锁定未出库数量”。AI无法自行分辨。解决方案建立项目专属《术语映射表》强制所有Spec引用表中词条。例如业务术语技术定义数据源示例值可售库存商品SKU维度当前可被用户下单的数量 仓库库存 - 已锁定库存 - 预占库存Redis缓存127仓库库存WMS系统中该SKU的实时物理库存WMS API150这张表不是摆设。我要求所有Spec初稿必须用[可售库存]格式引用术语编辑器会自动校验是否在表中存在。一次产品经理写了“剩余库存”被CI流水线拦截退回修改。表面麻烦实则避免了后续17个模块因理解偏差导致的联调事故。3.2 规则原子化把“和/或/但”切成开关人类喜欢用逻辑连接词组织规则“当用户等级≥VIP且订单金额500元或用户有指定优惠券时可享受免运费但新用户首单不参与”。AI处理这种嵌套逻辑极易出错。它需要的是布尔表达式的直译。正确做法将复合规则拆解为原子条件动作矩阵。例如上述规则转化为条件组Auser.level VIPANDorder.amount 500→ 动作set freight 0条件组Buser.coupon.type freight_free→ 动作set freight 0排除条件user.is_new trueANDorder.sequence 1→ 动作override freight original_rate注意这里用AND/OR代替中文连接词用代替“是”用override明确覆盖优先级。AI对符号运算的可靠性远高于对自然语言逻辑的理解。3.3 验证显性化用“能测”倒逼“写准”Spec里最危险的词是“正确”“合理”“友好”。它们无法被自动化验证也就无法被AI精准执行。必须替换成可观测、可测量的断言。比如“支付结果页显示友好提示”应改为断言1HTTP响应状态码 200断言2DOM中存在classtoast-success的元素断言3该元素textContent包含字符串“支付成功”且不含“error”“fail”等负面词断言4页面加载完成时间 800msLighthouse标准这套验证体系直接决定了AI输出的可信度。我们团队实践下来每增加1条可自动化验证的断言AI首次生成代码的通过率提升约12%。因为验证标准本身就在训练AI理解什么是“正确”。这个转换层本质上是在搭建人与AI的“共同语言”。它不取代人的思考而是把思考成果以AI能消化的形态固化下来。就像给AI装上一副特制眼镜——不是让它看得更远而是让它看清你真正想让它看的东西。4. 实战用“三层Spec法”重构一个真实电商需求光讲理论不够。我拿一个真实项目——“618大促期间购物车价格实时刷新”需求演示如何用三层Spec法术语层规则层验证层重构让AI生成代码一次通过。原始需求产品经理邮件“大促期间购物车价格要实时变特别是优惠券、跨店满减、限时折扣这些叠加起来很复杂得保证用户看到的价格和最终下单一致别让用户觉得被坑了。”这典型的“人类友好AI致死”写法。我们按三层法重构4.1 术语层定义所有模糊概念先建《购物车价格术语表》术语定义来源实时价格用户打开购物车页面时服务端计算的当前有效价格含所有生效优惠CartService.calcPrice()最终下单价用户点击“去结算”时订单创建接口返回的price字段值OrderService.createOrder()价格一致性实时价格与最终下单价绝对值误差 ≤ 0.01元业务SLA跨店满减用户在A店加购商品X在B店加购商品Y两店商品合并计算满减PromotionEngine.crossStoreRule()关键点所有术语都绑定到具体服务或方法杜绝“顾名思义”。4.2 规则层拆解为原子计算步骤原需求中的“很复杂”被展开为7个确定性步骤步骤1获取用户所有可用优惠券调用CouponService.listValid(userId)步骤2对每个优惠券计算其适用商品集合调用CouponService.getApplicableItems(couponId, cartItems)步骤3对每个商品应用最高优先级优惠优先级跨店满减 店铺满减 单品折扣 优惠券步骤4跨店满减计算汇总所有店铺商品总价按满减梯度分段计算例满300减30满500减60步骤5店铺满减计算按店铺分组对每组商品总价应用满减规则步骤6单品折扣计算对每个商品应用其绑定的折扣率保留小数点后2位步骤7优惠叠加限制同一商品最多享受1个满减1个折扣1个优惠券每步都注明调用服务、参数、返回格式。特别强调步骤4和5的计算顺序——这是AI最容易搞混的点。4.3 验证层给出可执行的测试用例不再说“保证一致”而是列12个边界用例每个含输入预期输出用例1用户购物车含A店商品199元、B店商品101元有跨店满减券满300减30→ 预期实时价格270.00元最终下单价270.00元用例2同上但A店商品有8折券限本店→ 预期实时价格270.00元跨店满减优先最终下单价270.00元用例3用户并发刷新购物车3次三次价格必须完全一致防缓存污染→ 预期三次返回price字段值相同这些用例直接导入测试平台成为AI生成代码的验收标尺。重构后我们将三层Spec喂给Qwen-Max它生成的CartService.calcPrice()方法覆盖了全部7个步骤通过12个用例中的11个。第12个并发一致性失败但错误非常明确它没加Redis分布式锁。我们立刻补上DistributedLock(key cart:#{userId})注解二次生成即通过。整个过程耗时4.5小时比传统方式人写人审人测快3倍且代码质量更高——因为AI的错误永远比人的疏漏更容易定位和修复。它不会“大概写对”只会“精确错在某一行”。5. 那些AI做不对的时刻其实暴露了团队真正的短板最后说点扎心的当AI反复做不对一个需求别急着换模型或调参。先看看团队里有没有人能清晰说出“我们到底想让AI做什么”。我见过最典型的案例一个SaaS团队要做“智能合同审核”买了最贵的法律大模型结果AI把“甲方有权单方面终止合同”识别为“乙方违约风险”闹得客户投诉。复盘发现产品负责人自己都说不清“我们想要AI帮法务快速抓重点但重点是什么是违约条款付款节点还是责任豁免”——连目标都没共识怎么写SpecAI不是万能解药它是面镜子。它照出的从来不是模型的缺陷而是我们自身思维的模糊地带。那些被我们称为“完整”的Spec往往只是集体认知的平均值而AI执行失败的瞬间恰恰是暴露认知分歧的黄金时刻。所以下次再听到“Spec写得很完整AI为什么还是做不对”请把这句话当作一个启动信号召集开发、测试、产品、业务方围坐一圈找出Spec里第一个引发歧义的词比如“实时”“友好”“合理”用10分钟现场定义它在本次需求中的唯一技术含义把定义写进术语表所有人签字确认。这个过程比优化prompt重要十倍。因为真正的瓶颈从来不在算力而在共识。我在多个团队推行这个“10分钟共识法”效果惊人AI首次生成通过率从平均28%提升到63%更重要的是团队内部的需求理解偏差减少了74%。大家终于意识到写好Spec不是为了喂AI而是为了逼自己想清楚——毕竟连人都没想明白的事凭什么指望AI替你想明白