为什么 AI 写代码看起来快,真正跑起来却问题很多
本文来自一个面向个人成长与人际沟通场景的多租户 AI 应用的实践。当编码被 AI 抹平之后,浮现出一个 AI 时代特有的新问题:你不再是"写代码的人",而是"管 AI 写代码的人"。这篇文章讲的就是,怎么用一套机制管住 AI,让它写出来的方案、需求、代码不跑偏。
这是 AI 应用工程化系列的第三篇,讨论如何用机制管住替你写代码的 AI。
你不再是"写代码的人",而是"管 AI 写代码的人"
编码被 AI 抹平之后,浮现出一个新壁垒:你不再是"写代码的人",而是"管 AI 写代码的人"。这道壁垒,恰恰是最容易被忽略的——因为大多数人的注意力还停在"AI 能不能把代码写出来",而真正的难点其实是"AI 写出来的代码,到底对不对"。
这个问题以前不存在,因为以前写代码的人就是判断代码的人,写错了自己知道。但现在代码是 AI 写的,你和代码之间隔了一层:AI 的"自信"不等于"正确",AI 的"能跑"不等于"做对了"。你失去了"亲手写"带来的那种判断的确定性,就得另找一套机制把它补回来。
AI 写代码,有几个值得警惕的共性:太自信、太会"看起来对"。项目协作文档里,把这些坑一条条记了下来:
- 会给"看起来对"的答案:AI 倾向于给出「技术更复杂、看起来更高级、更像业内标准」的方案,却未必真正回应问题。例如在只需看清几个结论时堆复杂图表,在单 Agent 足够时引入多 Agent,在需求尚未稳定时先叠几层抽象。问题不在于这些技术本身,而在于技术选择是否降低了理解与操作成本;如果它主要用来展示专业感,反而把成本转嫁给了用户。
- 把"编译通过"当"做对了":单测绿了、
npm run build过了,AI 就宣布完成。但它验证不了"整条链路真的把数据用上了"——那个"记忆算出来了却没进最终回答"的坑,单测全绿。 - 凭印象下结论:脱离项目实际套检查表,不碰实际代码,张嘴就是"应该没问题"。
- 不会主动问:需求边界不清时,它倾向于"猜",而不是停下来问人。
这四条凑到一起,就是"AI 写的代码,表面上能跑,实际上可能跑偏"的根源。更要命的是,这些坑单看都很隐蔽:单测能过、编译能过、甚至代码评审也看不出毛病,但一上线就是事故。所以光靠"让 AI 写、人最后看一眼"是远远不够的,得有一套机制,在写代码之前和之后都兜住。
所以"人定方向、AI 落成"这句话,落到工程上就变成一个更具体的问题:怎么降低 AI 写出来的方案、需求、代码跑偏的概率。我的答案,是两道由人负责的关键闸门——评审闸门和验证闸门。
第一道闸门:spec-review「动态推演」
需求方案定了,凭什么信它没问题、照着做就不会跑偏?项目采用的是 spec-review「动态推演」。
关键在那个"动态"二字。它的对立面是"静态推演"——脱离项目实际、套通用检查表、不碰实际代码、凭印象下结论。而动态推演要求:把待评审的 Spec 钉死在项目代码上,每条主张都落到具体代码行(file:line 取证);对不上,就说明 Spec 与代码之间存在不一致。
这五层,每一层回答一个问题:
- L0 项目实况耦合:先把 Spec 钉死在项目代码上——读项目 profile 的命门文件清单(项目里不可违背的约束)、读涉及文件的实际代码,建立证据。没有这一步,后面的推演就是空谈。
- L1 一致性推演:Spec 的目标、范围、依赖闭合吗?业务 ↔ 流程 ↔ 数据 ↔ 接口 ↔ 权限 ↔ 验收标准,这几条线对得上吗?
- L2 场景推演:沿实际路径模拟六个基础场景——正常、异常、边界、并发、越权、降级,每个场景走一遍"输入 → 路径 → 状态 → 输出 → 失败恢复"。
- L3 业内对照:关键决策和主流做法比一比,判断是"对齐"还是"有意偏离"——偏离要有理由。
- L4 真实验证计划:把静态推演确认不了的事,转成可执行的验证项。
为什么强调"动态"?因为通用检查表很难审出"这个 Spec 的某角色越权了"。需要落到隔离事实源(比如项目中的 permission/tenancy.py 的 resolve_scope),才更容易发现"这个接口把 OPERATOR 归到了 C 端域、会看到不该看的数据"。这也是为什么命门级误判代价高——权限、隔离、资金、安全,一次误判就可能带来数据泄露或资金损失,因此应尽量锚定代码取证,避免"凭印象说没问题"。
推演产出四段式发现(症状 → 来源 → 后果 → 补救),并给出门禁:pass(无阻塞且没有影响决策的未验证假设)/ pass_with_conditions(有条件通过)/ block(有未关闭的 P0)/ insufficient_evidence(证据不足)。缺少项目约束证据时,涉及权限/隔离/资金/合规的评审不能给出 pass;若无法进一步确认风险,应判定为 insufficient_evidence。
这个门禁为什么重要?因为它要回答的不是"这个 Spec 好不好",而是"现在能不能往下走"。block 是"有硬伤,先别写代码";pass_with_conditions 是"可以走,但要完成这些验证";insufficient_evidence 是"证据不够,我下不了判断"。三种状态,把"人的犹豫"变成了"可执行的决策",而不是"我觉得还行"。
还有一条关键边界:推演 ≠ 验证。设计推演通过,不能证明运行时正确。所以推演的最后一步通常是"真实验证计划"——把无法静态确认的事,转成可执行的验证项,而不是假装已经验过。验证计划需要写清环境与数据、操作步骤、通过/失败标准及回归范围;涉及权限、隐私、资金或安全时,还要包含负向、越权、失败和回滚路径。
spec-review 还有一个重要的边界:只读。它默认不修改被评审的文档、代码、配置——它的产出是"发现 + 门禁 + 验证计划",而不是直接改。评审改了自己评审的东西,就失去了独立性的意义。这也是它和 code-review 最大的区别:code-review 是事后挑毛病,spec-review 是事前挡风险。
为什么不能只靠"人自己看"?因为这个项目做到后面,已经 41 张表、5 个智能体、七角色权限——一个人很难把每条隔离规则、每个字段语义都记在脑子里,也很难只靠"感觉"去 review AI 写出的每一行代码。项目越复杂,纯靠人的记忆和状态做判断就越不现实,漏掉一个就可能造成越权或数据事故。
项目曾出现过权限隔离缺陷:平台运营角色(OPERATOR)一度能看到超出职责范围的会话数据。根因是把 OPERATOR 归到了错误的数据域——隔离逻辑散落在两处手写实现里,口径不一致,于是漏了。修复办法不是继续打补丁,而是收敛到统一事实源,让隔离判断尽量走同一套函数。如果当时有一套 spec-review,在写代码之前就把"OPERATOR 的数据域"这条主张落到实际代码上推演一遍,这个越权更可能在编码前被识别出来,而不是上线后才发现。
spec-review 的价值,正是把"人的判断"沉淀成一套可重复、可审计的机制:读项目 profile 的命门文件清单(把项目里不可违背的约束列出来)→ 把 Spec 每条主张落到具体代码行取证 → 六个基础场景逐一推演(正常 / 异常 / 边界 / 并发 / 越权 / 降级)→ 给出门禁 → 把"静态推演确认不了的事"转成真实验证计划。这样,约束 AI 的不再只是某个人的记性和状态,而是一套流程——换个人、换个模型再跑一遍,结论通常仍可复现。
值得一提的是,spec-review 这套机制也可以由 AI 执行。通常由人确定"命门文件清单"和"推演规则",AI 沿着实际代码路径逐条取证、逐场景推演。所以它不只是"人肉 review 的升级版",更像是"把人的判断编码成 AI 可执行的流程"——人负责定标准,AI 负责按标准执行。这也回答了一个常被问的问题:AI 越强,人是不是越没事干?恰恰相反,人要做的事从"写代码"更多转向"定标准、做判断",反而更考验功力。
它主要覆盖四类设计风险:架构(方案和现有分层是否冲突)、方案(备选方案和权衡有没有写清)、需求(验收标准是否可验证、边界是否写全)、功能与流程(角色、状态、异常和交接是否闭合)。代码和配置只用于核对当前实际行为,不能替代代码评审或运行时验证。这些风险应尽量在"写代码之前"识别,而不是等实现完成、测试跑完再处理。
这四类里,最容易跑偏的是需求和功能/流程边界。需求跑偏,是因为 AI 倾向于"猜"边界——你不写清楚,它就按自己的理解补一个,补错了后面全错。代码层面的"顺手优化"则要交给范围白名单、代码评审和实际运行验证兜底。
一次实际走查:人工会话派单接口
举个实际走查的例子。当时要加一个人工会话派单接口——平台把待处理会话分配给某个人工支持人员。Spec 初稿写完后,spec-review 走了一遍:
- L0 读命门文件:
permission/tenancy.py中resolve_scope("COUNSELOR")返回NONE,说明该角色不按租户域过滤;继续核对人工会话接口,发现会话归属由_get_owned_session按assigned_to校验,待接单池则由角色校验后的列表接口提供给在线支持人员。 - L1 一致性推演:这里实际有三类访问视图——待接单池、分配给我的会话、无权访问的会话。Spec 必须分别写清:待接单池仅 COUNSELOR 可读;接单后会话与消息仅
assigned_to=自己可读;其他会话拒绝访问。若直接按resolve_scope=NONE放开查询,就会漏掉第三层的归属校验。 - L2 场景推演:模拟支持人员 A、B 同时看到待接单池并尝试接同一会话。A 接单成功后,
assigned_to应变为 A;B 的会话列表和消息访问都不得命中该单,接单动作也应返回“已被接单”,而不是形成双重归属。 - L3 业内对照:按最小权限原则(OWASP ASVS 访问控制基线),“看到待处理池”不等于“能访问具体会话”;领取后再按执行者身份限制访问,与当前设计方向一致。并发领取使用 CAS 或行锁,也是常见的实现方式。
- L4 真实验证计划:在真实数据库准备两个支持人员账号和一个待接单会话;并发调用接单接口,断言仅一个成功,数据库中
assigned_to只指向成功者;随后验证失败方访问会话和消息被拒绝,成功方可正常访问。补充非 COUNSELOR 用户访问待接单池应返回 403。 - 门禁:Spec 初稿没有写清“共享池可见、认领后独占、越权访问拒绝”三层边界,给
block,整改后再进入实现。
人工按评审整改清单修改 Spec 并回写后,才进入实现。这就是"在写代码之前拦下来"——同样的越权,等代码写完再发现,代价翻倍。
而且这个评审的产出,不是一段对话,而是三份落盘的文档:
- 诊断报告——发现的问题、证据(
file:line取证)、门禁结论(pass / block / 证据不足); - 改进清单——每个发现对应一条整改:改哪个文件、改成什么、怎么验收;
- 方案定稿——把修正后的完整设计收敛成一份可读成稿。
三份文档强制落盘、可追溯,经人工确认后,改进清单里的每条"改成"要回写进原 Spec。这样,评审不是"我看过了、没问题"的一句话,而是一套有据可查的产物。
这三份文档,正好对应评审的三个角色:诊断报告回答"哪里有问题",改进清单回答"该怎么改",方案定稿回答"改完长什么样"。它们落在仓库里,可追溯、可审计——下次再遇到类似需求,可以直接翻上次的评审记录,而不是重新从零推演。
第二道闸门:真实验证,而不是"编译通过"
spec-review 管"设计对不对",但设计推演通过 ≠ 运行时正确。所以还有第二道闸门:真实验证。
真正难验证的,通常不是"页面能不能打开",而是跨层契约、状态一致性、系统副作用是否都对。
第一类问题:跨层契约错位。 评测单测里一直用 document 字段模拟检索结果,实际 done 事件返回的却是 content。每个模块各自测试都通过,但黑盒评测拿到的是空文档,最终 recall 长期为 0。问题不是某段代码算错,而是测试和实际链路对同一个字段的理解不一致。
这带来的判断是:验证不能只测模块自己,而要用实际事件的 payload 做契约断言。 否则单元测试越绿,越可能掩盖链路层的错位。
第二类问题:有状态链路的一致性。 聊天使用 SSE 流式生成,正常发一条消息并把回答显示出来,只能证明主路径可用。客户端断连、刷新页面后,还要验证 client_msg_id 是否幂等、seq 是否连续,以及同一条消息是否被多次写入数据库;同时确认 assistant 记录最终变为 done,而不是因流式生成中断长期停留在 generating 状态。这些状态错误不会出现在一张正常的页面截图中,需要主动制造断连,再检查浏览器、事件流和数据库三边是否一致。
所以,真实验证至少要覆盖三类证据:契约对齐、状态一致、副作用可控。如果功能包含前端交互,浏览器仍然是集成验证的必要入口;但浏览器只负责证明交互路径,不能替代对事件字段、数据库状态和幂等边界的断言。
同样重要的是三条业务路径:正常路径验证完整体验,安全路径验证红线短路,越界路径验证置信度熔断。它们与契约、状态、副作用三类证据交叉,才能说明"做对了",而不只是"能跑"。
把两道闸门串成一条闭环
把评审和验证串起来,就是一条闭环:
这条链上还有两道"防 AI 跑偏"的护栏:
- 改动范围纪律:任务 Spec 必须写清「涉及文件 + 禁止改动」;AI 只允许修改白名单文件,避免顺手重构、重命名或格式化无关代码;确需改动范围外内容时,必须停下来询问。否则 AI 可能在代码库里"顺手优化"出一堆你并不需要的改动——它会觉得"这里改一下更好",但那些"更好"往往是你没要的,还可能埋下新的风险。
改动范围纪律为什么这么重要?我举个实际例子:有一次让 AI 加一个功能,它顺手把旁边一个"看着不顺眼"的工具函数也重构了——函数签名变了,结果三四个调用点编译报错,我 debug 了半天才发现是 AI 的"顺手重构"导致的。从那以后,每个 Spec 都强制写「涉及文件 + 禁止改动」,AI 超出范围就停下来问人。
- Spec 作为实现依据 + 回写机制:评审产出的「整改清单」经人工确认后,应回写进原 Spec 的对应章节(涉及文件/字段/隔离口径/验收标准),再进入实现。这样能减少"文档一套、代码一套"的漂移,也降低下一位接手者的理解成本。
这套机制,为什么能跨项目复用
最后说一点:这套 spec-review + 真实验证的机制,并不只适用于一个具体项目。它的核心是"把人的判断沉淀成可重复的流程",而判断的对象——架构、方案、需求和功能/流程——在多数 AI 协作项目中都存在;代码和配置则作为核对实际行为的证据。换个项目、换个语言,命门文件清单换一批、Spec 换一份,但"动态推演 + 门禁 + 真实验证"这套流程本身仍可迁移。这也是为什么我把它做成了通用技能,而不是写死在某个项目的协作文档里。
结尾:管住 AI,靠的是判断力
这套机制,表面是"流程",内核还是判断力——只不过判断的对象,从"产品怎么做"变成了"AI 做得对不对"。
当编码不再是壁垒,一个团队更稀缺的,会从"会写代码的人"转向"能判断 AI 写没写对的人"。而这份判断力,AI 暂难替代——它主要依赖你把 Spec 写清楚、把评审落到项目代码、把验证做到真实运行环境。
说到底,AI 协同开发的效率与可控,并不矛盾——关键是别把"可控"寄托在某个人的记性和状态上,而是沉淀成一套可重复、可审计的机制。机制一旦立起来,AI 越快,反而越稳。
很多人有个误区,以为"用 AI 写代码"就是"写个好 prompt,然后看 AI 输出"。但 prompt 更多影响"AI 怎么想",很难单独保证"AI 写得对不对"——prompt 再好,AI 仍可能幻觉、越界,或把"编译通过"当"做对了"。真正让 AI 更可控的,通常不是 prompt 本身,而是这套"评审 + 验证"的机制:先挡在设计前,再验在实际运行中。
回顾全文,其实就三句话:评审管住"设计对不对",验证管住"做没做对",护栏管住"AI 别跑偏"。 三件事都不复杂,难的是把它们变成习惯、变成机制,而不是靠每次的"临时想起来"。
本文基于项目工程实践整理与思考,供参考。