给智能体写代码补上可维护性约束

Agent 写完一个功能、测试全部通过，代码就能放心合并吗？Sohit Kumar 提出的判断标准是：下一位工程师修改它时，要付出多少额外工作。功能能跑通，只回答了眼前的问题。

作者关注的是 AI 编程容易留下的一类成本：绕过已有模块、增加重复的集成路径，却没有留下设计理由。文章没有提供效率对照数据，而是借通知任务这个示例，讲清如何给 Agent 上下文、审查设计边界，以及交接决策依据。

功能通过了，为什么还会增加维护成本

作者早年曾把第三方调用散落在多个类里。评审时，资深同事把这些调用收拢到一个负责集成的类中。这段经历发生在编程 Agent 出现之前，涉及的是单一职责与内聚：相关行为由职责明确的模块管理，修改时更容易找到入口。

Agent 只是让这个老问题出现得更快。

文章给出一个示意任务：后台任务需要发送账单提醒，应用已经有 notification client，负责服务商凭证、错误处理和投递日志。Agent 却在新任务中直接调用邮件服务商，测试也确认提醒发送成功。

问题出在下一次修改。如果服务商调整请求格式，维护者要同时更新两条路径；投递失败时，新任务也可能采用另一套处理方式。

测试通过，不能证明下一次修改容易。

评审时应该先追问：为什么没有使用已有客户端？Agent 没找到它，模块用途不清楚，还是新需求超出了它的能力？

答案不同，处理也不同。职责合适就复用，设计允许就扩展；确实需要独立路径，就把理由留下。不能只看到重复调用，就机械地要求合并。

给 Agent 指路，比要求「代码整洁」更有效

「保持代码整洁」很难转化成明确行动。对账单提醒任务，更有用的上下文是：现有通知从哪里发送，哪个模块负责服务商集成，以及哪些业务规则约束它。然后要求 Agent 先检查已有路径，再提出方案。

作者把相关行为分散、难以定位带来的查找成本，称为 retrieval debt，可以理解为「检索债务」。人或 Agent 接手时，都得先花精力重新拼出系统如何运作。

这也解释了为什么只补一条提示词未必够用。如果模块命名模糊、职责混杂，Agent 即便搜索到了文件，也未必知道应该复用它。

不过，复用需要业务判断。账单通知与营销活动看起来都在发消息，但用户同意、发送时机、失败处理要求可能不同。强行塞进同一个抽象，会让两边的规则互相牵制。

目标应当是让职责和交互容易理解，而不是让相似代码全部走同一条路。

评审要看修改落在哪里，交接要留下为什么

作者建议把设计问题带进评审：服务商相关行为由哪里负责？新任务是否使用了这个边界？错误和日志是否方便所属团队支持？投递行为变化时，下一位工程师应该改哪里？

这些问题关注的是改动如何接入系统。评审 Agent 可以帮助找疑点，但是否接受这个设计，仍需要负责的工程师判断。

测试也能提供线索。如果验证一条提醒就要构造半个应用，应该检查模块间是否依赖过多。不过作者保留了另一种解释：测试基础设施本身也可能造成困难，不能仅凭测试难写就认定设计有问题。

交接则要补上代码未必表达得清楚的部分：集成为何放在这里、遵循什么规则、由谁负责。理由应留在代码附近或相关决策记录里，方便后来者找到。

如果评审反复发现同类问题，就应改善后续执行条件：让已有模块更容易检索，澄清职责，或更新相关 skill。最终可以拿一次后续修改来检验：工程师能否不翻原来的 Agent 对话，就找到位置、理解决定并完成变更？

我的判断

我认同作者把「下一次修改」放进验收标准。对已有系统，新增功能的成本不仅是本次代码量，还包括后来需要同步维护多少处行为。这个视角能补上功能测试没有覆盖的部分。

但文章的证据有限。作者提供了一段早年经历和一个示意任务，没有展示 Agent 在真实项目中的对照实验，也没有量化提供上下文后能减少多少返工。因此，这是一套有解释力的工程经验，不能当作已经验证的效率结论。

它还有一个前提：现有边界值得复用。旧 notification client 如果职责混杂，继续堆进去未必更好。与一律复用相比，作者提出的「复用、扩展或独立，并解释原因」更合理；实际取舍仍需要结合业务规则和模块现状。

能拿来做什么

• 给 Node 后台任务安排通知类需求时，先提供现有客户端位置、集成归属和业务限制，要求 Agent 检查已有实现后再提交方案。
• 审查 AI 生成的第三方调用时，同时检查凭证、错误处理和日志放在哪里，并明确服务商行为变化后应该修改哪个入口。
• 对确实需要新增集成路径的改动，在代码附近或决策记录中写清原因和维护归属，让后续工程师无需重读聊天记录。
• 遇到重复出现的评审问题时，修正模块说明或相关 skill，并用下一次真实修改观察交接是否更顺畅。