你让 AI 修改一个功能它很快读了十几个文件也给出了一份看起来完整的 patch。但检查以后发现它改的是已经废弃的入口没有找到真正的测试文件还把业务逻辑塞进了 UI 层。这个时候问题不一定是模型能力不够而是它没有被正确地带进项目。看到更多文件不等于理解项目上下文窗口变大确实可以让 AI 同时保留更多代码、文档和历史对话。但“看到了”与“知道它们之间的关系”是两回事。大上下文能帮助 AI读取更多相关文件保留更长的任务背景对照更多实现细节但它不会自动告诉 AI哪个文件是真正的应用入口哪些目录是核心业务模块哪些文件只是生成物或旧实现哪个测试才覆盖当前行为哪些边界不应该跨越一个真实仓库不是文件的简单集合。它里面有入口、分层、调用链、构建关系、历史兼容逻辑和暂时不能动的配置。人类工程师接手项目时需要 onboardingAI 同样需要。什么是代码仓库地图代码仓库地图不是目录树截图也不是把所有文件都写一遍。它是一份面向新人和 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 应该先列出前端筛选控件和列表状态后端查询参数与 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往往比一次性把整个仓库塞进对话更有价值。仓库地图不是给 AI 看目录而是告诉 AI 从哪里理解项目、从哪里开始修改、改完以后如何证明自己没有走错路。