很多人使用 Agent 编程时，会有一个期待：

AI 写代码更快，项目维护成本是不是也会更低？

不一定。

现在也常听到一些说法：某些项目的代码几乎全部由 AI 生成，甚至“100% 由 AI 写代码”。

但这里要区分两件事：

AI 生成代码文本，和 AI 完成软件工程，不是一回事。

AI 可以生成一行代码、一个函数、一个页面，甚至一组补丁。但真正的软件工程还包括需求澄清、架构设计、数据模型、模块边界、关系分析、测试验收、部署维护和技术债清理。

把“AI 生成代码”说成“AI 完成项目”，就像把“机器搬砖”说成“机器设计并建成了一栋楼”。

Agent 确实可以降低代码生成成本，但不会自动降低工程复杂度。

如果缺少架构约束、关系分析、验收机制和清理动作，Agent 也会制造技术债，而且可能制造得更快。

---

一、Agent 提高的是速度，不是工程判断

Agent 很擅长生成代码。

它可以快速：

• 增加接口；
• 修改页面；
• 补充函数；
• 生成测试；
• 批量处理文件。

但软件项目的难点，不只是“代码怎么写出来”。

更难的是：

• 数据模型是否合理；
• 模块边界是否清楚；
• 接口是否稳定；
• 修改会不会影响其他功能；
• 当前方案会不会限制未来维护。

这些问题属于工程判断。

Agent 可以参与分析，但不能自动替代判断。

---

二、关系债：AI 看到关键词，却看不见关系

项目变大以后，代码之间的关系不再只靠文件名和关键词决定。

一个函数可能被多个模块调用。

一个字段可能影响数据库、接口和前端展示。

一个 CSS 类可能同时作用于多个页面。

一个配置项可能改变测试、部署和权限。

但 Agent 常常会根据关键词定位文件。

它看到 login，就修改登录文件；看到 cart，就修改购物车文件；看到 button，就修改按钮样式。

问题在于，真实影响关系不一定写在关键词里。

很多关系藏在：

• 调用链里；
• 数据流里；
• 组件依赖里；
• 配置关系里；
• 历史兼容逻辑里。

于是就会出现：

当前问题修好了，相关功能却坏了。

这就是关系债。

它不是简单的代码错误，而是 Agent 对项目关系理解不足造成的长期成本。

---

三、残留债：AI 喜欢追加，不喜欢清理

Agent 还有一个常见倾向：

为了避免删错，先保留旧代码，再新增一套逻辑。

短期看，这样比较安全。

长期看，项目会越来越臃肿。

常见现象包括：

• 旧函数没有删除；
• 旧样式继续存在；
• 旧注释没有同步；
• 备份文件留在项目里；
• 临时代码变成永久代码；
• 重复逻辑同时存在；
• 新旧命名混在一起。

代码不是只要能跑就行。

代码还要能读、能删、能维护。

如果 Agent 只会追加，不会清理，项目就会一层一层沉积下去。

---

四、为什么这两类债特别危险？

关系债和残留债一开始都不明显。

关系债的表现是：

本轮任务通过了，但别的地方悄悄坏了。

残留债的表现是：

当前代码还能运行，但项目越来越难读。

它们不会立刻爆炸，而是慢慢积累。

等到下一轮修改时，人和 Agent 都会面对一个更混乱的项目：

• 不知道哪个函数还在用；
• 不知道哪个文件是旧版本；
• 不知道哪段注释还可信；
• 不知道哪个样式会影响哪个页面。

这时，AI 不但没有降低维护成本，反而增加了维护难度。

---

五、修改前：先做关系分析

避免关系债，不能只让 Agent 搜关键词。

在修改前，应该要求它先回答：

• 这个函数被谁调用？
• 这个组件在哪些页面使用？
• 这个字段从哪里来、到哪里去？
• 这个样式是不是全局样式？
• 修改后可能影响哪些测试？

可以把这一步写进 current_task.md：

修改前必须说明：

1. 本次涉及哪些函数、组件、接口或样式；
2. 它们被哪些地方调用或引用；
3. 可能影响哪些功能；
4. 用哪些测试或截图验证影响范围。

这一步不是形式主义。

它是在强迫 Agent 从关键词定位，转向关系分析。

---

六、修改后：必须清理残留

避免残留债，不能只验收“功能是否可用”。

还要检查：

• 是否留下旧函数；
• 是否留下重复逻辑；
• 是否有废弃注释；
• 是否有备份文件；
• 是否有临时代码；
• 是否有应该删除但没有删除的内容。

可以在验收标准里加入：

本轮修改不允许保留无用旧版本代码。

如果确实需要保留，必须在 revision_log.md 中说明原因和清理时间。

这样，Agent 就不能把“为了安全先保留”当成默认策略。

---

七、真正的 Agent 工程，也包括删除

很多人使用 AI 编程，只关注生成：

• 生成代码；
• 生成页面；
• 生成接口；
• 生成测试。

但长期项目里，删除同样重要。

要删除：

• 旧代码；
• 错误注释；
• 重复逻辑；
• 临时方案；
• 失效状态；
• 过期文档。

没有删除，项目只会越来越厚。

Agent 的任务不应该只是：

完成本轮功能。

还应该包括：

保持项目结构干净。

---