编程 Agent 的仓库地图：让上下文选择可验证而不是全量塞进提示词

把编程 Agent 放进一个真实仓库后，第一件事常常是“读取所有文件”。小项目里这似乎可行，大型 monorepo 中却会立刻变成上下文污染：过期配置、生成文件、vendor 代码和无关模块淹没了真正的约束。模型看到的文字更多，并不代表它理解得更好。

仓库地图的目的不是生成一份漂亮目录树，而是为每次任务提供可验证的选材依据。它应回答：入口在哪里、模块之间的依赖是什么、如何构建和测试、哪些路径是高风险区域、哪些文件由生成器管理、当前任务应读取哪些最小文件集合。地图本身也要有来源和更新时间，不能成为另一份长期失真的文档。

把仓库事实分成稳定层与动态层

稳定层适合从版本控制和配置文件提取：语言和包管理器、workspace 布局、主要应用入口、数据库迁移目录、公共库、CI 命令和代码所有者。动态层则来自最近变更和当前任务：最近修改的模块、失败测试、发布分支、活跃 feature flag、依赖漏洞和未提交文件。

不要让 Agent 自己从猜测中生成这些事实。一个轻量扫描器可以读取 package.json、go.mod、pyproject.toml、CI workflow、工作区配置和顶层说明，然后输出结构化清单。下面的对象比一段自然语言摘要更容易校验和更新：

{
  "root": "apps/web",
  "entrypoints": ["src/app/layout.tsx", "src/app/api"],
  "commands": {"lint": "pnpm lint", "test": "pnpm test", "build": "pnpm build"},
  "generatedPaths": ["src/generated"],
  "sensitivePaths": ["infra", "prisma/migrations", ".github/workflows"],
  "owners": {"infra": "platform-team"}
}

Agent 开始改动前应引用这份地图的版本号，并说明此次任务选用了哪些路径。若它修改 prisma/migrations 或 CI 配置，执行器可以自动提高审核等级；若它改的是生成目录，则要求回到生成源而不是直接编辑产物。

用依赖边界缩小读取范围

目录接近不等于依赖相关。更有效的是从目标文件出发寻找 import 图、路由入口、测试文件和配置引用。比如修复一个 Next.js 页面，不必读取所有 UI 组件；但必须了解该页面使用的服务端 action、数据 schema、权限包装器和对应测试。仓库地图可以保存粗粒度依赖索引，Agent 再按任务精确展开。

对每次上下文选择保留一份证据：任务 ID、地图版本、读取的文件列表、排除的高风险路径和理由。出现回归时，团队可以判断问题是模型推理错了，还是它根本没有被提供关键文件。相比“模型不知道”，这种证据能指导地图持续改进。

让地图随变更失效，而非靠人工记忆

当 lockfile、workspace 配置、路由目录、迁移目录或 CI 命令变化时，相关地图区块应自动失效。可以在提交钩子或 CI 中比较关键文件哈希，只有受影响的模块重建索引。不要每次全量扫描，也不要让旧地图无限期复用。

上线验证可选一个跨模块任务，例如给 API 增加字段并在前端显示。要求 Agent 先生成读取计划，再执行修改。审阅时检查它是否包含 schema、服务层、页面、测试和迁移约束；然后故意移动一个入口文件，确认地图失效机制能阻止 Agent 使用旧路径。能通过这两个场景，说明地图在减少风险而不是制造文档负担。

将地图输出接入评审而不是只给模型看

每次 Agent 创建分支或提交补丁时，可把仓库地图摘要附在 PR 描述中：目标模块、读取范围、敏感路径、未读取但可能受影响的依赖，以及实际运行的命令。reviewer 不需要相信模型“看过代码”的声明，而能快速发现它漏掉了哪条边界。若任务后来扩大范围，地图也应生成新的版本并标记差异。

团队可以定期抽样比较地图与真实依赖：选择近期事故或回归，检查关键文件是否在任务上下文中、是否被错误标为无关、失效是否及时触发。把这些反馈转成扫描规则或任务模板，比不断加长系统提示词更稳定。仓库地图最终是工程资产，应与代码和 CI 一起被验证、更新和审阅。

延伸阅读

• AI 代码库上手
• AI 代码审查实践
• AI 代码重构