同一个项目,为什么换个 Agent 又得从头解释?

0 阅读3分钟

假设要给订单服务清理一批废弃代码。Agent 搜了整个仓库,发现新版 App 已经改用 /v2/orders,准备把 /v1/orders 一起删除。问题出在仓库之外。仍在支持期内的旧版 App 还装在用户手机上,请求会继续打到这条路由。

你叫停这次删除,Agent 恢复代码,任务顺利结束。下一个会话继续扫废弃代码时,它还会看到同一组搜索结果。只要兼容约束停在上一次聊天里,团队就得从头解释一遍。

我想解决的是这类重复。一次排查已经确认了事实,代价也付过了。后面的人和 Agent 应该能从仓库里查到这个决定,知道它管哪些改动,还能判断它什么时候失效。

让关键约束出现在动手之前

得物在 Akashic 实践里,把工程知识放进 Git,按全局入口、模块文档和操作 Skill、代码注释三层维护。同一个任务走到哪一步,就读哪一处。

落到旧订单接口上,仓库根目录的 AGENTS.md(编程 Agent 的项目说明)只需要留一个入口,告诉 Agent 改订单 API 前先读移动端兼容说明。模块文档记录支持范围、保留原因和下线条件。路由旁的注释告诉维护者,这段代码还有旧版客户端依赖,并指回对应说明。

从仓库入口、模块文档到代码注释的查找路径

这几处的分工会影响维护成本。客户端支持范围变化时,改模块文档里的版本和下线条件就够了,入口仍指向同一份说明。有人只想修改库存任务,也无须在会话开始时读完一大段订单兼容史。

找到可能需要更新的文档,再看约束有没有变

「保留 /v1/orders」写久了,会出现另一种返工。旧 App 已经退出支持范围,Agent 照着一条没有日期和结束条件的注释,后续每次清理都跳过它。

一条好维护的约束,应该能说清什么时候撤销。以旧接口为例,可以把支持范围、调用量观察窗口和确认人写在模块文档里。条件满足以后,把路由、旧客户端的兼容测试和过时说明作为同一次变更审查,后续维护者能在 Git 里查到各处为什么一起调整。

Akashic 的提交检查给了一个实用做法。脚本依据变更文件与文档的映射,给出可能受影响的文档和 diff(代码差异)。Agent 再核对模块职责、配置规则或兼容边界有没有变。格式调整很少需要碰文档。支持范围缩小,说明就应当跟着这次改动更新。

对话里的结论,审核通过再写进仓库

代码变更检查还有个盲区。假设排查发现旧版 App 的请求经过另一层网关,服务日志看不到全量,现阶段只确认了这个事实。没有提交,也就不会触发文档同步。下次再判断接口能否下线,Agent 仍可能拿不完整的日志下结论。

得物还从归档会话里找值得保留的结论。一个 Agent 提取候选和依据,另一个使用同一份会话快照和固定版本的代码复核,最后由负责人审核合并请求。放在这个例子里,提取的是「判断旧客户端流量时去哪里查」。当时对接口是否能下线的猜测,等证据齐了再定。

我会先挑一件团队刚解释过两三次的事来试。留下一条索引、一份能查证的说明,再开空白会话做一次代码审查。如果 Agent 能指出「要看网关调用量和客户端支持范围」,团队就少了一次从头交代,仓库也多了一条以后能独立复核的决定。