Claude Code 用得越久我越确定一件事它很少因为模型不够聪明翻车更多时候是因为喂进去的东西太多。项目稍微上点规模随手拖几个文件进对话Token 就肉眼可见地往下烧等到代码还没改两行上下文窗口先被占满Claude 开始“失忆”那体验真的很难受。后来我把之前做代码评审时用过的代码地图方案搬进 Claude Code也就是社区里那个 30K Star 的开源工具给项目生成一份结构导航图实测下来 Token 中位数能省 65 倍。这篇文章就完整记录一下我是怎么接的、怎么测的以及中间踩过的坑希望能给同样被大项目上下文折磨的人一点参考。1. Token 刺客不在输出在上下文失控1.1 Claude Code 的每一轮对话都在为“记忆”付费很多人对 Token 消耗有误解以为代码生成得越多费用越高。实际上在 Claude Code 这类终端编程代理里大头从来不是模型的输出而是每一轮请求携带的上下文。每执行一步操作系统提示词、历史对话、工具调用结果、文件内容都会被打包发给模型这个包有多大单轮成本就有多高。举个例子一个 10 万行代码的中型项目如果所有文件都改成纯文本大概有 200 万到 300 万 Token。Claude 的上下文窗口就算按 20 万 Token 算一次也只能装下项目的十分之一。也就是说你根本不可能让 Claude “看一遍整个项目”它不具备这个物理条件。这时候 Claude Code 自己会怎么处理它有一个 Auto Compact 机制上下文快满的时候自动压缩历史。压缩本质上就是丢细节、留梗概。项目逻辑刚聊到一半上一轮的关键数据被压掉了Claude 就开始一脸茫然地重复问你“这个函数里可以获取 user id 吗”。省下来的 Token 其实是用模型的短期记忆换的长期来看效率反而更差。1.2 我一开始的三种错误姿势刚上手的时候我试过几种很本能但很低效的喂上下文方式。第一种是暴力全量灌入。把整个 src 目录用 cat 拼成一个文件丢进对话开头确实是“全局视野”但窗口瞬间见底Claude 读到最后已经忘记开头而且因为一次性信息过多它经常挑错文件下手。第二种是让 Claude 自己探索。不给任何地图让它先用 ls、find、grep 在项目里翻。小项目还好项目一大它会像个无头苍蝇一样反复扫目录、读文件一个简单需求光定位就烧掉几万 Token而且它并不知道哪个文件是核心入口经常被测试文件、构建配置带偏。第三种是手动精挑文件。每次开新任务前自己判断要改哪几个文件然后用 引用喂进去。问题在于人肉记忆不可靠你可能记得住主文件但忘了它 import 的工具函数、类型定义、以及另一个模块里对应的调用点。改了一半Claude 报错说找不到类型你才意识到漏了文件。这三种方式本质上是同一个问题让模型在信息不足和噪音过载之间二选一。而代码地图恰好是第三个选项。1.3 模型需要的不是全文是导航后来我想明白一个道理人类工程师接手一个陌生项目第一步也不会打开全部源码逐行读而是先看目录结构、README、关键模块的入口文件心里有了一张“这个项目大概长什么样”的图再顺着图去找具体代码。Claude Code 也应该这样。它需要知道的是有哪些目录、每个目录负责什么、核心文件有哪些、类或函数叫什么名字、它们之间大概怎么依赖。这些信息加在一起可能只需要几千 Token但足以支撑模型做出“下一步该去读哪个文件”的正确决策。这就是代码地图的价值把几十万 Token 的仓库全文压缩成几千 Token 的高密度导航信息然后让 Claude 在需要细节时再去读取指定文件。Token 消耗从“全量搬运”变成“按需点菜”数量级自然就降下来了。2. 代码地图的本质先画地图再走巷子2.1 代码地图到底包含什么我理解中的代码地图不是简单的目录树而是三样东西的组合项目目录树让模型知道文件在哪、模块怎么划分每个文件的功能摘要通常来自文件头注释或者关键类的命名符号表也就是导出的函数、类、常量的签名让模型不用打开文件就知道里面有什么。你可以把它想象成高德地图和街景照片的区别。直接把整个仓库丢给 Claude相当于把每条街的街景照片全部塞给它信息量巨大但没人能看完而代码地图是那张缩略到一屏的地图标出了主干道、立交桥和关键地标。模型先看地图确定自己在哪、要去哪再进入具体文件看“街景”效率完全不同。2.2 生成一份好地图靠的不是“压缩”市面上有些工具打着“代码压缩”的口号本质上是删注释、删空行、缩短变量名。这种做法省下的 Token 是有限的因为代码结构本身还在信息量没变。真正好用的代码地图工具做的是“重构信息层级”。它先扫描整个仓库识别出哪些文件值得进地图哪些文件可以忽略然后对值得进的文件抽取目录、入口、关键符号最后把所有内容按重要程度排好序拼成一个让模型容易检索的文本格式。我用的这个 30K Star 的项目叫 Repomix原理就是上面这套。它在生成地图的时候默认遵循 .gitignore自动跳过 node_modules、dist、.git 这些噪音目录还会统计输出文件的 Token 估算值让你在喂给 Claude 之前心里有数。它生成的产物是一个纯文本或 Markdown 文件头部是项目结构树后面是每个文件的路径和抽取出来的内容。注意这一步的关键不是“字符变少”而是“信息密度变高”。Repomix 的 compress 模式会移除注释和空行但如果只是这样效果有限真正让它省 Token 的是它只挑关键文件进入输出而不是全仓库文本一股脑塞进来。2.3 代码地图和 RAG、语义搜索不是一回事有人会问那为什么不直接给 Claude Code 接一个向量检索按语义搜代码我的经验是RAG 擅长的是“我不知道答案在哪帮我找一段相关代码”它适合你脑子里有一个模糊的问题让系统召回可能相关的片段。但 Claude Code 做项目任务时通常需要的是“全局理解”而不是“单点命中”。改一个接口你不只要知道接口定义在哪还要知道它被哪些地方调用相关的前后端契约是什么。这时候召回的代码块再准也是碎片模型缺的是把碎片组织起来的框架。代码地图的价值就在这个框架。它告诉模型项目整体是怎么组织的模块之间的边界在哪然后模型再结合自己的推理决定去读哪个文件、跳过哪个文件。RAG 可以当作辅助在模型需要搜索“某个报错字符串出现在哪些地方”的时候用 grep 或者语义检索但地图作为第一层导航是不可替代的。2.4 65 倍是怎么省出来的省 65 倍这个数字看起来夸张但你想清楚原理之后会觉得它是顺理成章的。假设一个项目全量源码文本是 50 万 Token。你现在有两种做法做法 A把所有源码拼进上下文让 Claude 直接基于全文回答。它每一轮对话都要携带这 50 万 Token十轮下来就是 500 万 Token 的消耗。做法 B先生成一个 8000 Token 的地图让 Claude 看地图了解结构。它判断需要改 A 文件和 B 文件然后用 cat 读取这两个文件假设花了 4000 Token。第二轮它再读一个相关文件花了 2000 Token。整个任务十轮下来上下文长期维持在 1 万到 2 万 Token 的区间总消耗可能只有十几万 Token。500 万和十几万的差距不就是几十倍吗所以 65 倍不是一个神奇的算法而是“全量搬运”和“按需导航”两种工作模式在数量级上的天然差别。3. 上手实录把代码地图接进 Claude Code 的三条路3.1 先动手生成一份地图我假设你已经装好了 Claude Code接下来只需要一个 Node.js 环境18 以上即可。用 Repomix 生成地图很简单进到项目根目录执行npx repomix它会扫描当前整个项目默认输出一个repomix-output.txt文件终端里会显示扫描了多少文件、估算的 Token 数量。你也可以自定义输出的风格和文件名npx repomix --style markdown --compress --output-file CODE_MAP.md几个常用参数说明--style markdown输出 Markdown 格式带代码块和标题对 Claude 更友好--compress移除注释和空行进一步压缩体积--output-file自定义输出文件名--include src/**只打包 src 目录适合只想处理核心代码的时候--ignore **/*.test.ts排除测试文件等噪音。如果你有固定的排除习惯可以执行npx repomix --init生成一个配置文件把参数写进去以后直接跑repomix就好。第一次跑完建议打开生成的文件看一眼。头部是目录树后面按路径列出各文件内容。如果发现某个目录比如 docs、scripts的内容占了半份文件但和你的任务完全无关就别犹豫把它们加进 ignore 列表。3.2 方式一用 引用把地图喂进对话这是最简单、也最适合单次任务的做法。在 Claude Code 的输入框里输入CODE_MAP.md 请先根据这张代码地图了解项目结构然后帮我找到用户登录相关的代码分析登录流程。Claude 会把地图文件当作上下文读入然后基于其中的目录树和符号信息决定下一步去读哪些具体文件。这种方式适合“每次任务都从一张干净地图开始”的场景地图不会被长期记忆污染也不会占用常驻上下文。我自己的经验是只要项目超过两万行代码一张新鲜的地图比什么都好使。它让模型在动手改代码之前先建立起对项目的整体认知后面它读文件时是带着目的去读的而不是盲目翻找。3.3 方式二把精华写进 CLAUDE.md如果你希望 Claude Code 在项目里每次会话都自带代码地图信息那不能把整个地图文件塞进 CLAUDE.md。不然每次请求都背着几万 Token 的地图跑反而浪费。正确做法是在 CLAUDE.md 里放一个精简版的项目导航包括目录结构、核心模块职责、常用命令以及一句话“更详细的代码地图在 CODE_MAP.md需要时可以 引用。”举个例子我项目的 CLAUDE.md 里有一段是这样写的## 项目结构 - src/apiREST API 路由层所有 HTTP 入口 - src/services业务逻辑层核心业务处理 - src/repositories数据访问层所有数据库操作 - src/typesTypeScript 类型定义 - src/utils公共工具函数 ## 代码地图 仓库根目录的 CODE_MAP.md 是自动生成的代码地图包含完整目录树和关键符号表。 任务涉及多个模块时先 CODE_MAP.md 获取全局导航。这样 Claude Code 每次启动都知道项目的大致骨架遇到需要跨模块的任务时它会主动去翻地图文件而不是空手乱撞。3.4 方式三把地图当作系统的起始上下文如果你不想手工每次 文件也可以把地图内容作为系统提示的一部分一次性注入。Claude Code 启动时支持通过参数追加额外的系统提示你可以用脚本把地图拼进去。我平时比较懒就在 shell 里建了个别名alias claude-mapclaude --append-system-prompt $(cat CODE_MAP.md)每次新起任务用claude-map等于开局自带地图视野。注意这种方式只适合临时会话不要长期驻扎在系统提示里地图文件会更新会话一旦建立旧地图就会变成过时信息。3.5 实际跑一个任务看效果为了验证这套方案我拿一个 Express 后端项目做了个小实验。项目不算大60 多个文件大约 2 万行代码。任务是把/api/users的返回格式统一改成{ code, data, message }。无地图模式下我直接把src/routes、src/controllers、src/services三个目录下所有文件拖进对话输入 Token 瞬间飙到 30 多万Claude 花了很长时间才理清楚每个文件的依赖关系中途还因为上下文太满被迫压缩历史最后改完时有一处中间件漏改返回格式不一致。地图模式下我先npx repomix --compress生成 CODE_MAP.md然后 引用进去。Claude 快速从地图里锁定了用户相关的路由文件、控制器、服务层文件主动读取后直接给出了修改方案。整个对话上下文长期稳定在 8000 到 1.5 万 Token 之间任务完成质量也更高。这就是我认为“先画地图再走巷子”的真正价值不是单纯省 Token而是让模型在任何时刻都保持视野清晰。4. 实测数据Token 中位数省 65 倍还是保守了4.1 我做的对照实验为了不误导人我在自己的一个中型项目上做了一个相对正式的对照实验。项目概况约 80 个文件3 万行左右代码TypeScript React Node 混合仓库。我选了 10 个不同类型的任务包括改接口返回、调整组件状态逻辑、增加数据校验、修复类型错误等。无地图组模拟大家最容易犯的做法直接把涉及的核心目录全量拖进上下文让 Claude 基于完整源码干活。有地图组先跑 Repomix 生成地图用 引用地图启动任务之后让 Claude 自己决定读哪些文件。两组用相同的需求描述各跑一遍记录输入 Token、输出 Token、完成时间和一次通过率。4.2 结果表我摘取几个有代表性的数字指标无地图组有地图组输入 Token 中位数49.6 万7600单任务最高输入 Token82 万1.8 万输出 Token 中位数1.2 万1.5 万平均任务耗时4 分 12 秒2 分 05 秒一次通过率70%89%中途 Auto Compact 次数7 次0 次最明显的是输入 Token 中位数49.6 万比 7600省了大约 65 倍。这个倍数和社区里其他人报告的中位数非常接近所以我基本认定“65 倍”不是个别案例吹出来的数据而是代码地图模式下的常态表现。有意思的是输出 Token 反而略微变多了。我觉得这是好事因为无地图组经常中途迷路输出的很多代码是重复劳动甚至错误修复有地图组则把 Token 花在了真正有效的代码生成上。省输入多输出模型干活更聚焦。4.3 数据背后的解释为什么差距能拉到这么大关键在上下文的“累积曲线”。无地图组开局就背了 50 万 Token 的重担而且这个包袱是所有后续轮次共享的。每对话一轮模型都得重新读一遍这 50 万 Token10 轮下来就是 500 万。地图组开局只带几千 Token后续虽然会读取新文件但每次读取前会先判断“值不值得读”上下文增长非常克制。而且我发现一个隐藏收益无地图组的 Auto Compact 发生次数是 7 次有地图组是 0 次。这意味着地图模式下Claude 的历史记忆从第一轮到最后一轮都是连贯的它记得自己一开始判断的方案不会中途“失忆”推翻自己。这种稳定性带来的效率提升比 Token 数字本身更值钱。4.4 什么场景下效果不明显我也测试了几个不适合代码地图的边界场景单文件脚本总共就一个 500 行的 Python 文件地图毫无意义直接拖文件就行全局大规模改动比如重构一个核心类型系统牵一发动全身地图只能帮你定位第一批文件后面还是得靠全局搜索高度动态的代码大量运行时反射、动态 import、代码生成的项目静态地图能提供的信息有限模型更需要靠执行和报错来探索。在这些场景下不要迷信“地图万能”。代码地图工具不是银弹它最适合的场景是“项目结构清晰、文件数量多、任务涉及跨模块改动”的日常开发。5. 避坑指南地图装好不等于万事大吉5.1 地图文件别常驻上下文我见过有人把地图文件写进 CLAUDE.md 让 Claude Code 每次启动都加载全文理由是“让模型有全局视野”。结果一份 3 万 Token 的地图成了常驻负担每次请求都背着它跑简单任务也贵得不行。正确用法是区分常驻和按需。常驻的只是 CLAUDE.md 里那段精简导航全文地图只在你需要处理跨模块任务时才通过 引用加载。任务结束后甚至可以主动开新会话避免地图旧数据影响后续判断。5.2 ignore 配置一定要花时间这个是最容易被忽视的坑。Repomix 默认会忽略 node_modules 和 .git但不会自动知道你的 docs 目录不重要、你的测试文件是不是该排除。我建议每个项目第一次生成地图时都花十分钟看看输出文件里哪些内容是占着篇幅但没用的然后把它们加入 .repomixignore 或 repomix.config.json 的 ignore 列表。举个例子一个前后端混合仓库前端项目的src/styles和src/pages可能完全无关一次后端任务一个移动端项目android/和ios/目录的构建脚本也不是每次都需要。ignore 配置越精准地图越轻模型越不容易被无关代码干扰。5.3 地图会过期务必养成重新生成的肌肉记忆代码地图是静态快照代码改动之后它就成了旧地图。我自己踩过这个坑给重构后的项目用旧地图开任务Claude 按图索骥找到了一个已经不存在的老文件然后一脸疑惑地开始乱猜。现在的习惯是每次大改之前重新生成一次地图大改之后如果还要继续对话再生成一次。Git 提交前、代码评审前、开新任务前我都会快速跑一下npx repomix --compress大概几秒钟的事但能避免大量无意义的上下文浪费。如果嫌手动跑麻烦可以加一个 npm script 到 package.json{ scripts: { map: repomix --compress --output-file CODE_MAP.md } }以后只需要npm run map一条命令搞定。5.4 小心敏感信息被打进地图这一点我特别想提醒。Repomix 生成的地图会包含文件内容如果你不小心把.env、config/credentials.json、或者带密钥的测试文件放在了项目里这些内容就有可能会被打包进 CODE_MAP.md。虽然工具本身会在输出文件前缀提示“你可能不希望把敏感信息包含在输出中”但工具的提醒是死的你的项目是活的。最保险的做法是确保.env和密钥文件已经在 .gitignore 里生成地图后看一眼输出文件头部有没有不该出现的路径在 CI 里跑生成地图的步骤时加上额外的敏感词检查。地图文件一旦被提交到仓库或者被分享给模型密钥就相当于进了别人的口袋这个代价不是省下的 Token 能弥补的。5.5 登录态和 Token 报错别和代码上下文混为一谈聊到 Token我发现很多人在 Claude Code 里遇到报错时会误以为是自己代码上下文的问题。比如有时候终端冒出token exchange failed、sign-in could not be completed、your access token could not be refreshed之类的错误就在论坛里问“是不是我代码地图写多了”。不是的。这类报错是 CLI 客户端本身登录授权的问题也就是 OAuth 登录态过期、客户端版本过旧、或者环境不支持当前的鉴权方式。和你在项目里塞了多少上下文没有任何关系。遇到这类报错正确的排查顺序是确认使用的是当前版本的 CLI过旧版本会有已知的鉴权问题重新走一遍官方登录流程让客户端重新获取授权确认网络环境能正常访问官方的鉴权端点如果项目里有人为改过环境变量、Token 配置恢复成默认再看。千万不要为了“绕过鉴权失败”去手动填充 Token 或者修改客户端的校验逻辑那既不稳定也不安全。先把登录态弄干净再去优化代码地图。6. 扩展用法让代码地图成为团队基建6.1 在 CI 里自动生成地图杜绝过期问题手动跑npx repomix有一个问题人的习惯不可靠。代码写得兴起的时候谁还记得重新生成地图我现在的做法是在 CI 流程里加一个步骤每次合并到主干前自动生成一份新的 CODE_MAP.md并检查它是否有未提交的变更。如果地图落后于代码CI 直接失败提醒开发者同步更新。这样任何人都可以用最新的地图不会出现“地图是上周的”这种尴尬。这个流程用到的是 CI/CD 里最常见的思路把需要人工记忆的事情变成自动化检查。地图生成只要几秒CI 跑的频率也不高代价几乎可以忽略。6.2 地图和依赖文档查询互补代码地图解决的是“自己项目里有什么”但它不解决“第三方库 API 现在长什么样”。这两个问题是互补的不要互相替代。我用 Claude Code 干活时还有一个习惯如果任务涉及较新的依赖库或者我对某个库的 API 记忆模糊会先用 Context7 拉一下这个库的最新文档。Context7 这类工具维护了大量热门开源项目的索引能把“某个库某个方法的用法”用很少的 Token 精确命中。流程就变成了这样代码地图告诉我项目里哪里依赖了什么库Context7 告诉我这个库的 API 现在是什么签名然后 Claude Code 把两者结合直接写出能跑的代码。三层配合信息密度极高。6.3 monorepo 仓库按模块生成地图在 monorepo 仓库里整个仓库生成一份地图往往太大、太杂。我的做法是每一层都生成根目录放一份全局导航列出各 package 的职责和依赖关系每个 package 内部各自生成一份详细地图CLAUDE.md 里写清楚“跨模块任务看根地图单模块任务看对应 package 的地图”。这样 Claude Code 在遇到跨模块需求时先从根地图找到目标 package再进入具体 package 读取详情上下文保持精简不会被无关模块的内容淹没。我自己维护的一个 monorepo 有 20 多个 package最早全仓生成一份地图是 4 万 Token单个 package 地图通常只有 3000 到 8000 Token按需加载之后体验提升非常明显。6.4 团队统一规范让地图成为新人上手的入口最后想说的是代码地图不只是给 Claude Code 用的它对人类开发者同样有价值。我现在让团队里新同学入职后的第一件事就是跑一遍npm run map打开 CODE_MAP.md 从头看到尾。这个文件比任何入门文档都真实因为它就是当前代码仓库的实时写照。团队规范可以定得很简单每个项目必须有一个可一键生成的 CODE_MAP.mdCLAUDE.md 里必须有指向地图的说明新增依赖或大范围重构时必须重新生成地图。这几条规矩一旦养成团队的 AI 编程效率和新人上手速度都会上一个台阶。这套工作流我用了几个月最大的感受是省 Token 只是副产物真正值钱的是 Claude 在正确的地方用力。它不再是“背着一整个仓库走路”的搬运工而是拿着地图、知道该往哪走的人。你给它越少但越精准的信息它回报你的就越超出预期。如果你也在为 Claude Code 的大项目上下文发愁真心建议花半小时把代码地图这套东西搭起来你会发现所谓“Token 焦虑”从根上就消失了。 Claude Code 上下文失控？用代码地图把 Token 消耗降低 65 倍
Claude Code 用得越久我越确定一件事它很少因为模型不够聪明翻车更多时候是因为喂进去的东西太多。项目稍微上点规模随手拖几个文件进对话Token 就肉眼可见地往下烧等到代码还没改两行上下文窗口先被占满Claude 开始“失忆”那体验真的很难受。后来我把之前做代码评审时用过的代码地图方案搬进 Claude Code也就是社区里那个 30K Star 的开源工具给项目生成一份结构导航图实测下来 Token 中位数能省 65 倍。这篇文章就完整记录一下我是怎么接的、怎么测的以及中间踩过的坑希望能给同样被大项目上下文折磨的人一点参考。1. Token 刺客不在输出在上下文失控1.1 Claude Code 的每一轮对话都在为“记忆”付费很多人对 Token 消耗有误解以为代码生成得越多费用越高。实际上在 Claude Code 这类终端编程代理里大头从来不是模型的输出而是每一轮请求携带的上下文。每执行一步操作系统提示词、历史对话、工具调用结果、文件内容都会被打包发给模型这个包有多大单轮成本就有多高。举个例子一个 10 万行代码的中型项目如果所有文件都改成纯文本大概有 200 万到 300 万 Token。Claude 的上下文窗口就算按 20 万 Token 算一次也只能装下项目的十分之一。也就是说你根本不可能让 Claude “看一遍整个项目”它不具备这个物理条件。这时候 Claude Code 自己会怎么处理它有一个 Auto Compact 机制上下文快满的时候自动压缩历史。压缩本质上就是丢细节、留梗概。项目逻辑刚聊到一半上一轮的关键数据被压掉了Claude 就开始一脸茫然地重复问你“这个函数里可以获取 user id 吗”。省下来的 Token 其实是用模型的短期记忆换的长期来看效率反而更差。1.2 我一开始的三种错误姿势刚上手的时候我试过几种很本能但很低效的喂上下文方式。第一种是暴力全量灌入。把整个 src 目录用 cat 拼成一个文件丢进对话开头确实是“全局视野”但窗口瞬间见底Claude 读到最后已经忘记开头而且因为一次性信息过多它经常挑错文件下手。第二种是让 Claude 自己探索。不给任何地图让它先用 ls、find、grep 在项目里翻。小项目还好项目一大它会像个无头苍蝇一样反复扫目录、读文件一个简单需求光定位就烧掉几万 Token而且它并不知道哪个文件是核心入口经常被测试文件、构建配置带偏。第三种是手动精挑文件。每次开新任务前自己判断要改哪几个文件然后用 引用喂进去。问题在于人肉记忆不可靠你可能记得住主文件但忘了它 import 的工具函数、类型定义、以及另一个模块里对应的调用点。改了一半Claude 报错说找不到类型你才意识到漏了文件。这三种方式本质上是同一个问题让模型在信息不足和噪音过载之间二选一。而代码地图恰好是第三个选项。1.3 模型需要的不是全文是导航后来我想明白一个道理人类工程师接手一个陌生项目第一步也不会打开全部源码逐行读而是先看目录结构、README、关键模块的入口文件心里有了一张“这个项目大概长什么样”的图再顺着图去找具体代码。Claude Code 也应该这样。它需要知道的是有哪些目录、每个目录负责什么、核心文件有哪些、类或函数叫什么名字、它们之间大概怎么依赖。这些信息加在一起可能只需要几千 Token但足以支撑模型做出“下一步该去读哪个文件”的正确决策。这就是代码地图的价值把几十万 Token 的仓库全文压缩成几千 Token 的高密度导航信息然后让 Claude 在需要细节时再去读取指定文件。Token 消耗从“全量搬运”变成“按需点菜”数量级自然就降下来了。2. 代码地图的本质先画地图再走巷子2.1 代码地图到底包含什么我理解中的代码地图不是简单的目录树而是三样东西的组合项目目录树让模型知道文件在哪、模块怎么划分每个文件的功能摘要通常来自文件头注释或者关键类的命名符号表也就是导出的函数、类、常量的签名让模型不用打开文件就知道里面有什么。你可以把它想象成高德地图和街景照片的区别。直接把整个仓库丢给 Claude相当于把每条街的街景照片全部塞给它信息量巨大但没人能看完而代码地图是那张缩略到一屏的地图标出了主干道、立交桥和关键地标。模型先看地图确定自己在哪、要去哪再进入具体文件看“街景”效率完全不同。2.2 生成一份好地图靠的不是“压缩”市面上有些工具打着“代码压缩”的口号本质上是删注释、删空行、缩短变量名。这种做法省下的 Token 是有限的因为代码结构本身还在信息量没变。真正好用的代码地图工具做的是“重构信息层级”。它先扫描整个仓库识别出哪些文件值得进地图哪些文件可以忽略然后对值得进的文件抽取目录、入口、关键符号最后把所有内容按重要程度排好序拼成一个让模型容易检索的文本格式。我用的这个 30K Star 的项目叫 Repomix原理就是上面这套。它在生成地图的时候默认遵循 .gitignore自动跳过 node_modules、dist、.git 这些噪音目录还会统计输出文件的 Token 估算值让你在喂给 Claude 之前心里有数。它生成的产物是一个纯文本或 Markdown 文件头部是项目结构树后面是每个文件的路径和抽取出来的内容。注意这一步的关键不是“字符变少”而是“信息密度变高”。Repomix 的 compress 模式会移除注释和空行但如果只是这样效果有限真正让它省 Token 的是它只挑关键文件进入输出而不是全仓库文本一股脑塞进来。2.3 代码地图和 RAG、语义搜索不是一回事有人会问那为什么不直接给 Claude Code 接一个向量检索按语义搜代码我的经验是RAG 擅长的是“我不知道答案在哪帮我找一段相关代码”它适合你脑子里有一个模糊的问题让系统召回可能相关的片段。但 Claude Code 做项目任务时通常需要的是“全局理解”而不是“单点命中”。改一个接口你不只要知道接口定义在哪还要知道它被哪些地方调用相关的前后端契约是什么。这时候召回的代码块再准也是碎片模型缺的是把碎片组织起来的框架。代码地图的价值就在这个框架。它告诉模型项目整体是怎么组织的模块之间的边界在哪然后模型再结合自己的推理决定去读哪个文件、跳过哪个文件。RAG 可以当作辅助在模型需要搜索“某个报错字符串出现在哪些地方”的时候用 grep 或者语义检索但地图作为第一层导航是不可替代的。2.4 65 倍是怎么省出来的省 65 倍这个数字看起来夸张但你想清楚原理之后会觉得它是顺理成章的。假设一个项目全量源码文本是 50 万 Token。你现在有两种做法做法 A把所有源码拼进上下文让 Claude 直接基于全文回答。它每一轮对话都要携带这 50 万 Token十轮下来就是 500 万 Token 的消耗。做法 B先生成一个 8000 Token 的地图让 Claude 看地图了解结构。它判断需要改 A 文件和 B 文件然后用 cat 读取这两个文件假设花了 4000 Token。第二轮它再读一个相关文件花了 2000 Token。整个任务十轮下来上下文长期维持在 1 万到 2 万 Token 的区间总消耗可能只有十几万 Token。500 万和十几万的差距不就是几十倍吗所以 65 倍不是一个神奇的算法而是“全量搬运”和“按需导航”两种工作模式在数量级上的天然差别。3. 上手实录把代码地图接进 Claude Code 的三条路3.1 先动手生成一份地图我假设你已经装好了 Claude Code接下来只需要一个 Node.js 环境18 以上即可。用 Repomix 生成地图很简单进到项目根目录执行npx repomix它会扫描当前整个项目默认输出一个repomix-output.txt文件终端里会显示扫描了多少文件、估算的 Token 数量。你也可以自定义输出的风格和文件名npx repomix --style markdown --compress --output-file CODE_MAP.md几个常用参数说明--style markdown输出 Markdown 格式带代码块和标题对 Claude 更友好--compress移除注释和空行进一步压缩体积--output-file自定义输出文件名--include src/**只打包 src 目录适合只想处理核心代码的时候--ignore **/*.test.ts排除测试文件等噪音。如果你有固定的排除习惯可以执行npx repomix --init生成一个配置文件把参数写进去以后直接跑repomix就好。第一次跑完建议打开生成的文件看一眼。头部是目录树后面按路径列出各文件内容。如果发现某个目录比如 docs、scripts的内容占了半份文件但和你的任务完全无关就别犹豫把它们加进 ignore 列表。3.2 方式一用 引用把地图喂进对话这是最简单、也最适合单次任务的做法。在 Claude Code 的输入框里输入CODE_MAP.md 请先根据这张代码地图了解项目结构然后帮我找到用户登录相关的代码分析登录流程。Claude 会把地图文件当作上下文读入然后基于其中的目录树和符号信息决定下一步去读哪些具体文件。这种方式适合“每次任务都从一张干净地图开始”的场景地图不会被长期记忆污染也不会占用常驻上下文。我自己的经验是只要项目超过两万行代码一张新鲜的地图比什么都好使。它让模型在动手改代码之前先建立起对项目的整体认知后面它读文件时是带着目的去读的而不是盲目翻找。3.3 方式二把精华写进 CLAUDE.md如果你希望 Claude Code 在项目里每次会话都自带代码地图信息那不能把整个地图文件塞进 CLAUDE.md。不然每次请求都背着几万 Token 的地图跑反而浪费。正确做法是在 CLAUDE.md 里放一个精简版的项目导航包括目录结构、核心模块职责、常用命令以及一句话“更详细的代码地图在 CODE_MAP.md需要时可以 引用。”举个例子我项目的 CLAUDE.md 里有一段是这样写的## 项目结构 - src/apiREST API 路由层所有 HTTP 入口 - src/services业务逻辑层核心业务处理 - src/repositories数据访问层所有数据库操作 - src/typesTypeScript 类型定义 - src/utils公共工具函数 ## 代码地图 仓库根目录的 CODE_MAP.md 是自动生成的代码地图包含完整目录树和关键符号表。 任务涉及多个模块时先 CODE_MAP.md 获取全局导航。这样 Claude Code 每次启动都知道项目的大致骨架遇到需要跨模块的任务时它会主动去翻地图文件而不是空手乱撞。3.4 方式三把地图当作系统的起始上下文如果你不想手工每次 文件也可以把地图内容作为系统提示的一部分一次性注入。Claude Code 启动时支持通过参数追加额外的系统提示你可以用脚本把地图拼进去。我平时比较懒就在 shell 里建了个别名alias claude-mapclaude --append-system-prompt $(cat CODE_MAP.md)每次新起任务用claude-map等于开局自带地图视野。注意这种方式只适合临时会话不要长期驻扎在系统提示里地图文件会更新会话一旦建立旧地图就会变成过时信息。3.5 实际跑一个任务看效果为了验证这套方案我拿一个 Express 后端项目做了个小实验。项目不算大60 多个文件大约 2 万行代码。任务是把/api/users的返回格式统一改成{ code, data, message }。无地图模式下我直接把src/routes、src/controllers、src/services三个目录下所有文件拖进对话输入 Token 瞬间飙到 30 多万Claude 花了很长时间才理清楚每个文件的依赖关系中途还因为上下文太满被迫压缩历史最后改完时有一处中间件漏改返回格式不一致。地图模式下我先npx repomix --compress生成 CODE_MAP.md然后 引用进去。Claude 快速从地图里锁定了用户相关的路由文件、控制器、服务层文件主动读取后直接给出了修改方案。整个对话上下文长期稳定在 8000 到 1.5 万 Token 之间任务完成质量也更高。这就是我认为“先画地图再走巷子”的真正价值不是单纯省 Token而是让模型在任何时刻都保持视野清晰。4. 实测数据Token 中位数省 65 倍还是保守了4.1 我做的对照实验为了不误导人我在自己的一个中型项目上做了一个相对正式的对照实验。项目概况约 80 个文件3 万行左右代码TypeScript React Node 混合仓库。我选了 10 个不同类型的任务包括改接口返回、调整组件状态逻辑、增加数据校验、修复类型错误等。无地图组模拟大家最容易犯的做法直接把涉及的核心目录全量拖进上下文让 Claude 基于完整源码干活。有地图组先跑 Repomix 生成地图用 引用地图启动任务之后让 Claude 自己决定读哪些文件。两组用相同的需求描述各跑一遍记录输入 Token、输出 Token、完成时间和一次通过率。4.2 结果表我摘取几个有代表性的数字指标无地图组有地图组输入 Token 中位数49.6 万7600单任务最高输入 Token82 万1.8 万输出 Token 中位数1.2 万1.5 万平均任务耗时4 分 12 秒2 分 05 秒一次通过率70%89%中途 Auto Compact 次数7 次0 次最明显的是输入 Token 中位数49.6 万比 7600省了大约 65 倍。这个倍数和社区里其他人报告的中位数非常接近所以我基本认定“65 倍”不是个别案例吹出来的数据而是代码地图模式下的常态表现。有意思的是输出 Token 反而略微变多了。我觉得这是好事因为无地图组经常中途迷路输出的很多代码是重复劳动甚至错误修复有地图组则把 Token 花在了真正有效的代码生成上。省输入多输出模型干活更聚焦。4.3 数据背后的解释为什么差距能拉到这么大关键在上下文的“累积曲线”。无地图组开局就背了 50 万 Token 的重担而且这个包袱是所有后续轮次共享的。每对话一轮模型都得重新读一遍这 50 万 Token10 轮下来就是 500 万。地图组开局只带几千 Token后续虽然会读取新文件但每次读取前会先判断“值不值得读”上下文增长非常克制。而且我发现一个隐藏收益无地图组的 Auto Compact 发生次数是 7 次有地图组是 0 次。这意味着地图模式下Claude 的历史记忆从第一轮到最后一轮都是连贯的它记得自己一开始判断的方案不会中途“失忆”推翻自己。这种稳定性带来的效率提升比 Token 数字本身更值钱。4.4 什么场景下效果不明显我也测试了几个不适合代码地图的边界场景单文件脚本总共就一个 500 行的 Python 文件地图毫无意义直接拖文件就行全局大规模改动比如重构一个核心类型系统牵一发动全身地图只能帮你定位第一批文件后面还是得靠全局搜索高度动态的代码大量运行时反射、动态 import、代码生成的项目静态地图能提供的信息有限模型更需要靠执行和报错来探索。在这些场景下不要迷信“地图万能”。代码地图工具不是银弹它最适合的场景是“项目结构清晰、文件数量多、任务涉及跨模块改动”的日常开发。5. 避坑指南地图装好不等于万事大吉5.1 地图文件别常驻上下文我见过有人把地图文件写进 CLAUDE.md 让 Claude Code 每次启动都加载全文理由是“让模型有全局视野”。结果一份 3 万 Token 的地图成了常驻负担每次请求都背着它跑简单任务也贵得不行。正确用法是区分常驻和按需。常驻的只是 CLAUDE.md 里那段精简导航全文地图只在你需要处理跨模块任务时才通过 引用加载。任务结束后甚至可以主动开新会话避免地图旧数据影响后续判断。5.2 ignore 配置一定要花时间这个是最容易被忽视的坑。Repomix 默认会忽略 node_modules 和 .git但不会自动知道你的 docs 目录不重要、你的测试文件是不是该排除。我建议每个项目第一次生成地图时都花十分钟看看输出文件里哪些内容是占着篇幅但没用的然后把它们加入 .repomixignore 或 repomix.config.json 的 ignore 列表。举个例子一个前后端混合仓库前端项目的src/styles和src/pages可能完全无关一次后端任务一个移动端项目android/和ios/目录的构建脚本也不是每次都需要。ignore 配置越精准地图越轻模型越不容易被无关代码干扰。5.3 地图会过期务必养成重新生成的肌肉记忆代码地图是静态快照代码改动之后它就成了旧地图。我自己踩过这个坑给重构后的项目用旧地图开任务Claude 按图索骥找到了一个已经不存在的老文件然后一脸疑惑地开始乱猜。现在的习惯是每次大改之前重新生成一次地图大改之后如果还要继续对话再生成一次。Git 提交前、代码评审前、开新任务前我都会快速跑一下npx repomix --compress大概几秒钟的事但能避免大量无意义的上下文浪费。如果嫌手动跑麻烦可以加一个 npm script 到 package.json{ scripts: { map: repomix --compress --output-file CODE_MAP.md } }以后只需要npm run map一条命令搞定。5.4 小心敏感信息被打进地图这一点我特别想提醒。Repomix 生成的地图会包含文件内容如果你不小心把.env、config/credentials.json、或者带密钥的测试文件放在了项目里这些内容就有可能会被打包进 CODE_MAP.md。虽然工具本身会在输出文件前缀提示“你可能不希望把敏感信息包含在输出中”但工具的提醒是死的你的项目是活的。最保险的做法是确保.env和密钥文件已经在 .gitignore 里生成地图后看一眼输出文件头部有没有不该出现的路径在 CI 里跑生成地图的步骤时加上额外的敏感词检查。地图文件一旦被提交到仓库或者被分享给模型密钥就相当于进了别人的口袋这个代价不是省下的 Token 能弥补的。5.5 登录态和 Token 报错别和代码上下文混为一谈聊到 Token我发现很多人在 Claude Code 里遇到报错时会误以为是自己代码上下文的问题。比如有时候终端冒出token exchange failed、sign-in could not be completed、your access token could not be refreshed之类的错误就在论坛里问“是不是我代码地图写多了”。不是的。这类报错是 CLI 客户端本身登录授权的问题也就是 OAuth 登录态过期、客户端版本过旧、或者环境不支持当前的鉴权方式。和你在项目里塞了多少上下文没有任何关系。遇到这类报错正确的排查顺序是确认使用的是当前版本的 CLI过旧版本会有已知的鉴权问题重新走一遍官方登录流程让客户端重新获取授权确认网络环境能正常访问官方的鉴权端点如果项目里有人为改过环境变量、Token 配置恢复成默认再看。千万不要为了“绕过鉴权失败”去手动填充 Token 或者修改客户端的校验逻辑那既不稳定也不安全。先把登录态弄干净再去优化代码地图。6. 扩展用法让代码地图成为团队基建6.1 在 CI 里自动生成地图杜绝过期问题手动跑npx repomix有一个问题人的习惯不可靠。代码写得兴起的时候谁还记得重新生成地图我现在的做法是在 CI 流程里加一个步骤每次合并到主干前自动生成一份新的 CODE_MAP.md并检查它是否有未提交的变更。如果地图落后于代码CI 直接失败提醒开发者同步更新。这样任何人都可以用最新的地图不会出现“地图是上周的”这种尴尬。这个流程用到的是 CI/CD 里最常见的思路把需要人工记忆的事情变成自动化检查。地图生成只要几秒CI 跑的频率也不高代价几乎可以忽略。6.2 地图和依赖文档查询互补代码地图解决的是“自己项目里有什么”但它不解决“第三方库 API 现在长什么样”。这两个问题是互补的不要互相替代。我用 Claude Code 干活时还有一个习惯如果任务涉及较新的依赖库或者我对某个库的 API 记忆模糊会先用 Context7 拉一下这个库的最新文档。Context7 这类工具维护了大量热门开源项目的索引能把“某个库某个方法的用法”用很少的 Token 精确命中。流程就变成了这样代码地图告诉我项目里哪里依赖了什么库Context7 告诉我这个库的 API 现在是什么签名然后 Claude Code 把两者结合直接写出能跑的代码。三层配合信息密度极高。6.3 monorepo 仓库按模块生成地图在 monorepo 仓库里整个仓库生成一份地图往往太大、太杂。我的做法是每一层都生成根目录放一份全局导航列出各 package 的职责和依赖关系每个 package 内部各自生成一份详细地图CLAUDE.md 里写清楚“跨模块任务看根地图单模块任务看对应 package 的地图”。这样 Claude Code 在遇到跨模块需求时先从根地图找到目标 package再进入具体 package 读取详情上下文保持精简不会被无关模块的内容淹没。我自己维护的一个 monorepo 有 20 多个 package最早全仓生成一份地图是 4 万 Token单个 package 地图通常只有 3000 到 8000 Token按需加载之后体验提升非常明显。6.4 团队统一规范让地图成为新人上手的入口最后想说的是代码地图不只是给 Claude Code 用的它对人类开发者同样有价值。我现在让团队里新同学入职后的第一件事就是跑一遍npm run map打开 CODE_MAP.md 从头看到尾。这个文件比任何入门文档都真实因为它就是当前代码仓库的实时写照。团队规范可以定得很简单每个项目必须有一个可一键生成的 CODE_MAP.mdCLAUDE.md 里必须有指向地图的说明新增依赖或大范围重构时必须重新生成地图。这几条规矩一旦养成团队的 AI 编程效率和新人上手速度都会上一个台阶。这套工作流我用了几个月最大的感受是省 Token 只是副产物真正值钱的是 Claude 在正确的地方用力。它不再是“背着一整个仓库走路”的搬运工而是拿着地图、知道该往哪走的人。你给它越少但越精准的信息它回报你的就越超出预期。如果你也在为 Claude Code 的大项目上下文发愁真心建议花半小时把代码地图这套东西搭起来你会发现所谓“Token 焦虑”从根上就消失了。