用 AI 写代码时，经常会遇到一种很典型的问题：
单独检查每个文件，好像都没有明显错误；但真正运行起来，整个功能就是不对。
例如：
-
后端接口能够正常返回；
-
前端页面也没有语法错误；
-
类型检查能够通过；
-
单个函数测试正常；
可一旦把它们连起来，就开始出现：
-
字段读取不到；
-
状态更新不同步；
-
异常处理逻辑不一致；
-
页面一直加载；
-
某个模块认为任务已经成功，另一个模块却认为失败。
这种问题说明，AI写项目级代码时，真正困难的不只是：
某一段代码写得对不对。
还包括：
不同模块之间是不是遵守同一套规则。
一、局部正确，不等于系统正确
假设后端返回：
{
"userName": "Tom"
}
前端代码读取：
user.name
后端本身没有错。
前端代码单独看也可能没有明显语法问题。
但两边放在一起，数据就是拿不到。
这种错误的核心不是某个函数内部逻辑错误，而是：
接口契约不一致。
真实项目中很多问题都属于这一类。
每一块代码单独看都合理，但大家理解的“规则”不是同一个版本。
二、接口契约是跨模块协作的第一道边界
一个接口真正包含的并不只是URL。
它通常还包括：
-
请求参数；
-
字段名称；
-
数据类型；
-
返回结构；
-
错误码；
-
空值处理。
比如后端认为：
status = 1
代表启用。
前端却按照：
status = true
处理。
两边都能写出合法代码。
组合以后却会产生错误。
所以涉及前后端、服务之间调用时，最好先确定：
输入和输出到底长什么样。
再分别让AI实现。
这比两个模块各自推断规则稳定得多。
三、状态流不一致，也容易出现“代码都对但功能不对”
例如一个保存流程：
点击保存
↓
显示loading
↓
发送请求
↓
保存成功
↓
关闭loading
如果AI只修改请求逻辑，却忽略了页面状态，可能出现：
接口已经成功；
但：
loading = true
一直没有恢复。
从API角度看任务完成了。
从用户角度看页面却像卡住了一样。
这就是为什么项目级修改不能只看：
数据有没有正确返回。
还要看：
状态是怎么沿着整个流程变化的。
四、异常处理规则不同，也会产生隐性问题
例如后端约定：
HTTP 200 + errorCode
表示部分业务异常。
但前端只判断：
HTTP状态码
于是后端明明已经告诉它：
操作失败。
前端却继续显示：
保存成功。
两个模块单独看都可能符合自己的实现逻辑。
真正的问题是：
异常契约没有统一。
所以AI修改跨模块功能时，除了正常流程，还应该确认：
-
成功怎么表示；
-
失败怎么表示；
-
空数据怎么处理；
-
超时怎么办。
这些“边缘规则”往往比主流程更容易被漏掉。
五、类型一致，也不代表语义一致
TypeScript等类型系统能够帮助发现很多问题。
但类型检查通过，也不能保证业务语义一定正确。
例如：
price: number
前端认为单位是：
元。
后端返回的却是：
分。
类型完全一致。
都是 number。
但：
1999
一个模块理解成19.99元；
另一个模块理解成1999元。
这种问题靠类型检查很难发现。
它属于：
语义一致性问题。
所以项目越复杂，仅仅保证“类型对得上”还不够。
还要保证：
大家对这个字段代表什么有相同理解。
六、AI为什么特别容易出现这种问题？
因为AI处理代码时，往往会围绕当前任务重点读取相关文件。
例如让它：
修改用户详情页面。
它会重点理解：
UserPage
UserService
User类型
但真正影响功能的可能还有：
缓存
权限
公共请求层
状态管理
后端DTO
如果这些关系没有进入当前分析范围，就容易出现：
局部实现非常合理，但整体规则没有同步。
所以项目越大，AI真正需要理解的就越不是“文件数量”。
而是：
文件之间的关系。
七、跨模块修改前，最好先画出一条完整链路
例如修改“用户头像上传”。
不要马上让AI开始改。
可以先确认：
页面
↓
上传组件
↓
API Client
↓
后端接口
↓
文件存储
↓
数据库
↓
重新返回头像地址
然后检查每一个连接点：
-
字段叫什么；
-
数据格式是什么；
-
谁负责转换；
-
出错以后怎么返回；
-
成功后谁更新状态。
这样比逐个打开文件修改更容易发现问题。
八、修改完成后，不要只做单文件验证
如果任务涉及多个模块，可以至少检查三层：
第一层：单模块
函数自身是否正确？
第二层：模块连接
调用双方的数据和状态是否一致？
第三层：完整流程
用户真正执行一次操作能不能从头走到尾？
很多“局部都对”的问题，就是前两层通过以后，没有继续验证第三层。
九、可以让AI专门做一次“一致性检查”
代码完成以后，可以要求：
不继续修改代码，检查本次涉及的所有模块，确认字段名称、数据类型、错误处理、状态变化和返回结构是否一致。
这类检查和普通Code Review不完全一样。
Code Review可能关注：
代码质量；
重复逻辑；
潜在Bug。
一致性检查更关注：
不同模块说的是不是同一种语言。
对于跨文件任务非常实用。
十、一个简单的跨模块检查清单
以后让AI修改跨模块功能，可以重点确认：
接口：
请求和返回结构是否一致？
字段：
命名、类型、单位是否一致？
状态：
loading、success、error是否闭环？
异常：
不同模块如何判断失败？
调用链：
是否还有其他消费者使用旧逻辑？
测试：
有没有完整流程验证？
把这几个问题确认清楚，很多“明明代码都没错，功能就是跑不起来”的问题都会明显减少。
最后
AI写代码出现：
“局部看起来都对，合起来却出问题”
真正暴露的是项目级开发和单文件生成之间的差别。
单文件更关注：
这一段代码有没有写对。
项目级开发更关注：
所有参与者是不是遵守同一套规则。
接口、状态、异常、类型、业务语义，只要其中一层出现不一致，就可能出现：
每个模块都觉得自己没错，但整个系统就是错的。
所以AI开始参与大型项目以后，真正重要的能力会越来越从：
生成正确代码
走向：
保持跨模块一致性。
这也是Coding Agent从“会写函数”真正走向“会理解系统”必须跨过的一步。
持续更新 Codex、Claude Code 与大模型开发实战内容，也会整理 AI 会员订阅与使用相关经验。更多深度内容欢迎搜索关注「孤狼GPT」。
