AGENT · AI 工程

让 AI 代理真正理解你的代码库

从索引、上下文到工具调用,建立稳定的代码理解流程。

本文目录

“把整个仓库发给模型”不是代码理解方案。仓库越大,真正相关的信息占比越低;上下文越长,模型越容易忽略局部约束。一个可靠的代码代理必须先知道自己不知道什么,再用工具逐步缩小问题范围。

代码理解更像调查,而不是一次问答。代理需要建立假设、寻找证据、修正路径,并在修改前确认调用关系和测试边界。

从任务而不是仓库开始

同一个代码库面对不同任务时,相关上下文完全不同。修复登录重定向需要路由、中间件、会话与测试;优化列表渲染需要组件树、数据获取和性能记录。预先把仓库摘要做得再完整,也不能替代任务驱动的探索。

第一步应该把请求转成可验证的问题:

  • 用户观察到的现象是什么?
  • 哪个入口最可能触发它?
  • 预期行为由测试、类型还是文档定义?
  • 哪些结果能够证明修改有效?

这些问题决定后续工具调用。没有明确任务边界时,代理往往会读取大量文件,却没有形成能够被证伪的判断。

建立分层检索

稳定的检索流程通常分为三层。第一层是结构:列出文件、识别语言和框架、找到入口与配置。第二层是符号:搜索组件、函数、路由和错误文本。第三层才是语义:当命名不确定或概念分散时,用向量检索寻找可能相关的实现。

实践原则:能够用精确文本回答的问题,不要先交给模糊检索。

文本搜索速度快、结果可解释,特别适合错误消息、API 名称和类型符号。语义检索更适合“哪里实现了权限继承”这类没有统一命名的问题。二者不是竞争关系,而是从确定性到探索性的两种工具。

type Evidence = {
  path: string;
  line: number;
  claim: string;
  confidence: 'high' | 'medium' | 'low';
};

代理可以为关键判断保存一份轻量证据表。路径和行号让判断可追溯,置信度则提醒后续步骤哪些结论仍需验证。它不需要写成长篇报告,但能防止“读过某个文件”被错误地等同于“已经理解行为”。

控制上下文预算

上下文不是越多越好。把完整文件不断追加到对话里,会让旧信息和新证据混在一起。更有效的方式是先读取小范围,确认相关后再扩展:从符号定义到调用者,从调用者到状态来源,再到覆盖该路径的测试。

可以把上下文分成三类:

  1. 当前证据:下一步推理必需的代码与测试。
  2. 稳定事实:框架、目录职责、公开接口等已确认信息。
  3. 暂存线索:可能相关但尚未验证的文件。

当前证据保持原文,稳定事实压缩成短摘要,暂存线索只保存路径和理由。这样既降低令牌占用,也减少过期代码继续影响判断。

避免摘要漂移

摘要经过多次转述后会丢失条件。尤其是权限、缓存和并发逻辑,一个“通常如此”的概括可能隐藏关键例外。任何会直接决定代码修改的事实,都应该在动手前重新打开源文件确认,而不是依赖早先摘要。

让工具调用形成闭环

工具的价值不在调用次数,而在每一次结果是否改变下一步。一个良好循环包括:提出假设、选择最小工具、读取结果、更新假设、决定继续或停止。

例如,页面返回旧数据时,不应该直接修改缓存逻辑。先搜索响应头和缓存键,再找到写入与失效路径,最后运行覆盖该路径的测试。如果证据显示缓存根本没有命中,就应转向请求去重或客户端状态,而不是沿着最初猜测继续深入。

修改完成后,代理需要从相反方向验证:

  • 类型检查是否通过?
  • 原失败路径是否恢复?
  • 相邻场景是否出现回归?
  • 页面或接口的实际行为是否与测试一致?

仅看到测试绿色还不够。如果任务涉及界面,就要打开页面、执行交互并检查控制台;如果涉及 API,就要验证真实响应而不是只看 mock。

把理解过程留给下一次任务

最有价值的长期产物不是一次性的仓库总结,而是清晰的代码边界、可靠测试和自解释接口。代理如果在每次任务后补上缺失测试、修正误导命名或写清模块约束,下一次探索会自然更快。

不要建立一个需要持续人工维护的“全仓库百科”。它很快就会过时。更好的做法是让事实靠近源头:架构约束放在模块文档,接口行为放在类型和测试,运行方式放在独立 README。代理可以读取这些材料,但不应该成为它们保持正确的唯一机制。

真正的代码理解不是记住所有文件,而是在有限时间内找到足够证据,做出可以验证的修改。一个成熟代理的特征,也不是回答得快,而是知道何时继续搜索、何时承认不确定,以及用什么结果证明自己已经完成。