当你让AI修改一个功能时，它可能迅速扫描十几个文件，然后生成一份看似完整的补丁。但仔细检查后，问题就暴露了：它改的是早已废弃的入口，真正的测试文件根本没被触达，甚至顺手把业务逻辑塞进了UI层。这时候，问题往往不在模型的能力上，而是AI从一开始就没被正确引导到项目结构中。
看到更多文件，不等于真正理解项目
上下文窗口的扩大，确实能让AI同时保留更多代码、文件和历史对话。但“看到了”和“知道它们之间的关系”，这中间存在一道巨大的鸿沟。大上下文的确能带来帮助：
- 读取更多相关文件
- 保留更长的任务背景
- 对照更多实现细节
但它不会自动告诉你：
- 哪个文件才是真正的应用入口
- 哪些目录是核心业务模块
- 哪些文件只是生成物或旧版本实现
- 哪个测试覆盖当前行为
- 哪些边界不应该跨越
一个真实的项目仓库，从来不是文件的简单堆砌。它里面有入口、有分层、有调用链、有构建关系，还有历史遗留的兼容逻辑和暂时不能改动的配置。人类工程师接手一个新项目，需要经历“上手熟悉”的过程，AI也一样需要。
什么是代码仓库地图
代码仓库地图，并不是目录树截图，也不是把所有文件名罗列一遍。它是一份专门为新人（包括AI）准备的项目导航说明，重点描述结构关系和常见操作路径。一份合格的地图，至少要回答六个问题：
- 项目由哪些部分组成
- 每个部分负责什么功能
- 前端、后端和数据之间是如何流动的
- 常见任务通常从哪个文件开始修改
- 测试、构建和运行命令是什么
- 哪些地方风险较高，或者不建议直接修改
这份地图的价值，不是替代AI去读代码，而是帮它减少在错误方向上盲目摸索的时间。
一份最小的 repo-map.md
复制代码# repo-map.md## 项目概览## 主要目录## 前端入口## 后端入口## 数据流## 常见任务修改路径## 测试与验证命令## 生成文件与源文件## 不建议修改的文件## 常见坑
每一节都不需要写成大部头。比如“主要目录”只要解释清楚职责，“常见任务路径”只需列出从页面到接口再到测试的大致链路，这已经比让AI全靠自己猜测要强太多了。
仓库地图最重要的是“修改路径”
很多项目的文档只描述目录结构，却不告诉读者怎么完成任务。对AI来说，后者才是关键。举个例子，一个记账App可以这样写：
复制代码## 主要目录- frontend/src/pages：页面级流程
- frontend/src/components：可复用展示组件
- backend/app/api：接口入口
- backend/app/services：业务逻辑
- backend/tests：后端测试## 常见任务修改路径- 改页面交互：先看 pages，再看 components 和状态管理
- 改接口行为：先看 api，再看 service 和 schema
- 改统计口径：先看 stats service，再看查询测试
- 改识别规则：先看 parser，再补 parser tests
它没有解释每一行代码，但指明了AI应该沿着哪条路径去查找。这样做能极大地减少“只改了前端、没改接口”，或者“只改了实现、忘记补测试”这类尴尬情况。
用仓库地图约束AI的行动顺序
更推荐的做法，是把地图放在任务的第一步，而不是等AI改错了再回头补救。
复制代码1. 先阅读 repo-map.md
2. 根据任务列出影响范围
3. 说明计划修改哪些文件
4. 标出不涉及的模块
5. 人类确认范围后再修改
6. 按地图中的命令执行验证
7. 把新发现的坑补回地图
这里最关键的一步是第三步。让AI先说出“我要改哪些文件”，本质上是在强迫它把自己的项目理解外显出来。这样一来，人类工程师就能在真正产出diff之前，发现AI的方向是不是跑偏了。
一个具体的对比
假设需求是：给交易列表增加按分类筛选。没有仓库地图时，AI可能会直接去改列表组件，在前端做本地过滤；它完全没意识到项目后端已经有现成的查询参数，也不知道统计页面其实用了同一个查询服务。有地图时，AI应该先列出影响范围：
- 前端筛选控件和列表状态
- 后端查询参数与service
- 交易列表相关测试
- 统计口径是否需要同步
这个结果并不代表AI一定不会犯错，但至少能让错误更早暴露出来，改动范围也变得更容易控制。
老项目尤其需要仓库地图
新项目的目录通常比较干净，但老项目就不一样了，经常会有重名模块、废弃入口、正在迁移中的代码、临时脚本和不完整的测试。这些信息对熟悉项目的人来说是常识，但对AI来说，完全是盲区。所以，不妨在地图里明确写清楚：
- 当前正在使用的入口和已经废弃的入口
- 哪些文件是生成物
- 哪些迁移中的文件不能删除
- 哪些命令必须在特定目录下执行
- 哪些模块正在迁移，暂时不要扩展
仓库地图不是一次性完工的设计文档。每次AI踩到新坑，或者团队发现一条更稳定的修改路径，都可以补充进去；如果项目结构发生了变化，也要及时删掉过期信息。
我给这个记账App写的最小地图
一开始不需要画复杂架构图。我会先写一份能帮AI找路的文本地图：
复制代码# repo-map.md## 项目入口- 前端入口：frontend/src/main.ts
- 路由：frontend/src/router/index.ts
- 后端入口：backend/app/main.py
- API 路由：backend/app/api/## 业务链路- 录入：EntryPage -> /api/parse -> parser service
- 保存：EntryPage -> /api/transactions -> transaction service
- 统计：StatsPage -> /api/stats -> stats service
- 预算提醒：HomePage -> /api/alerts -> alert service## 常见修改路径- 改输入解析：parser -> parser tests -> API integration test
- 改账单列表：BillsPage -> TransactionList -> transactions API
- 改统计口径：stats service -> stats tests -> API response## 不要直接修改- frontend/dist/：构建产物
- 已发布的数据库迁移：除非明确要求，不删除历史迁移
- runtime-logs/：只读日志，不当作源文件
这份地图有一个重要特点：它不仅描述了“文件在哪里”，还写了“任务怎么走”。当AI接到“修复最近7天查询结果不对”的任务时，它应该沿着parser、stats service和对应测试去查，而不是只在页面组件里翻来覆去找字符串。
让AI先证明自己看懂了地图
推荐使用一个固定的任务前提示：
复制代码请先阅读 repo-map.md，不要修改代码。针对“修复最近 7 天支出统计”这个任务，请输出：1. 当前请求从哪个页面或接口进入
2. 可能涉及哪些模块
3. 哪些文件只是展示层，哪些文件负责统计口径
4. 计划修改的文件和不修改的文件
5. 最小验证命令如果地图和实际代码不一致，请先列出不一致之处。
这一步非常有用，因为AI的错误会在改代码之前就暴露出来。比如，如果它把StatsPage.vue当成了统计计算的核心入口，那你就知道，要么是地图没写清楚，要么是它的理解出了问题，总得修正一个。
地图要记录“不能相信什么”
很多项目的问题，不在于缺少文件说明，而在于仓库里充斥着大量容易误导人的文件。所以，有必要专门记录：
- 哪些目录是构建产物
- 哪些模块已经废弃
- 哪些测试依赖本地数据库
- 哪些接口目前固定了
user_id = 1 - 哪些查询只支持规则表达，不支持任意口语
这些“负面信息”很容易被忽略，但恰恰是AI接手项目时最容易踩的坑。一份好的仓库地图，不只告诉AI该去哪里，也要告诉它哪些地方不能光凭文件名做推断。
最后
大上下文让AI能看到更多代码，而仓库地图则让AI知道这些代码之间的关系。真正稳定的AI编程，需要的不仅仅是更多的材料，而是更好的结构。对于个人项目来说，一份几十行的repo-map.md，往往比一次性把整个仓库塞进对话要更有价值。