在分析遗留代码库中应用 AI 代理的现实方法

负责大规模遗留项目的工程师每天都要花 2 个小时翻阅代码堆。靠 grep 追踪字符串的方式如今已达到极限。即使想引入 AI 代理，现实中也往往对如何将其融入工作流感到迷茫。本文将探讨如何将代理从简单的聊天机器人转型为提高实务生产力的工具，并介绍具体的工程流程。

先清除噪音

如果把整个代码库丢给代理，会导致上下文被污染。学习不必要的数据只会产生离谱的回答，并浪费 Token 费用。仅仅缩小索引范围，就能让响应速度有明显的提升。

请立即应用以下 3 点：

1. 在项目根目录下创建 .cursorignore 文件。像 /dist、/build、/target、node_modules 这样巨大的构建产物必须排除在外。
2. 排除 Protobuf 桩文件或自动生成的 *.gen.ts 文件。这可以防止代理生成忽视向后兼容性的代码。
3. 使用基于默克尔树（Merkle Tree）的同步工具。不要每次都重新创建完整索引，只更新被修改文件的哈希值，从而将索引速度提高 3 倍以上。

通过语法树追踪依赖关系

基于文本的搜索永远无法找出复杂的继承关系。必须使用 ast-grep 之类的工具分析代码的语法树（AST）。将其融入 Prompt 中，可以实现比简单搜索精密得多的查询。

1. 定义要分析目标的语法模式。例如，用 ast-grep 语法编写缺失错误处理的异步函数模式。
2. 将 @codebase 工具与该模式一起提供给代理。此时，添加指令以缩小范围，让其忽略外部库，仅查找内部模块之间的继承关系。
3. 让其将结果输出为 Mermaid 图表。可视化复杂的调用流程可以将问题解决时间缩短约 40%。

通过测试验证修正方案

AI 提出的修正方案有一半是错误的。如果直接合并，只会堆积技术债务。请在 CI 流水线中植入测试影响分析（TIA）以自动化验证循环。

1. 编写脚本，仅执行与修改代码相关的测试，例如使用 Jest 的 --findRelatedTests。
2. 向代理下达指令。设置循环，如果测试失败，则分析错误日志并让代码自动修复。
3. 在 CI 阶段加入 CodeQL 等工具。它可以自动过滤掉人类难以察觉的安全漏洞。

构建此循环可以显著提高语法有效性检查的准确度。没必要抛弃现有的工具链。在简单搜索方面，ripgrep 仍然比代理快 10 倍以上。根据工具的特性分离角色，才是资深工程师真正要做的事。