1. 52 次工具调用到底是怎么花掉的我一直觉得 Claude Code 这类 CLI 编程助手最让人上头的点是“它真的会自己去翻代码库”但最让人血压升高的点也是“它真的会自己去翻代码库”。刚上手那会儿我在一个两万行左右的项目里让它排查登录流程的 token 过期问题它开场就是一句“让我先了解一下项目结构”然后 Glob 扫一遍、Bash 执行ls看目录、Read README、Read package.json、Grep 搜 token、再逐个打开匹配文件……一趟下来工具调用次数轻松突破 50。标题里说的 52 次几乎就是我那天的真实记录。这里的核心关键词是“工具调用”。Claude Code 本身不直接操作你的文件系统它通过调用一组预设工具来观察环境读文件叫Read搜索文件叫Glob查内容叫Grep执行命令叫Bash。每一次调用都是一次“模型发出操作请求 → 工具执行 → 返回结果 → 模型继续推理”的完整往返。次数越多耗时越长Token 消耗越大上下文里塞的中间信息也越杂。为什么默认情况下它这么能“翻”因为它对陌生代码库没有先验。它不知道你的auth逻辑散落在src/services还是libs/core只能像新人一样一层层扒目录、猜文件、搜符号。这不是 Claude Code 笨而是它缺少一张能一眼看懂全局的“代码地图”。所以我做了一个小工具名字就叫repomap。它能预先扫描项目结构把目录树、符号索引、文件摘要浓缩成一份 markdown 地图存到.claude/repomap.md。任务开始时Claude Code 只需要读一次这份地图再定位一次目标文件就能进入实质编码。同样的任务工具调用从 52 次降到 3 次左右。这篇文章会把这件事拆开讲清楚工具调用为什么这么贵、地图方案到底设计成什么样、具体怎么接入 Claude Code、有哪些我看别人文档看不出来的坑。适合正在用 Claude Code 写中型以上项目的开发者也适合所有被“AI 翻代码翻得又慢又费钱”这个问题困扰的人。1.1 repomap 到底是干什么的先看一次默认场景里的工具调用序列我按真实日志还原过序号工具调用目的1Glob**/*看全项目文件列表2Bashls -la确认目录层级3ReadREADME.md了解项目说明4Readpackage.json摸清依赖和脚本5Globsrc/**/*缩小到源码目录6Greptoken搜相关符号7Readsrc/api/client.ts看候选文件8Greplogin继续搜关联逻辑9Readsrc/hooks/useAuth.ts再看下一个候选.........52Read 某配置文件终于拼接出全貌这个序列里大量调用都是为了“排除干扰”读 README 是为了知道项目干嘛的读 package.json 是为了知道依赖和入口反复 Grep 是为了逐个确认匹配文件哪些真正相关。每步都有意义但效率极低。repomap的思路很简单把这些“探索步骤”提前到会话开始前一次性做完并把结果压缩成结构化摘要。地图里包含四块内容目录树但过滤掉.git、node_modules、dist、build、vendor这类噪音目录符号索引用正则或 ripgrep 提取函数、类、接口、常量的定义位置文件级摘要每个源码文件配一两句话说明说明里标注它的职责和可能关联的模块关键配置信息比如依赖清单、入口文件、测试命令。当 Claude Code 需要“了解项目结构”时它不再去 Glob 整个仓库再逐个 Read而是直接读这份地图一步到位。1.2 为什么是 3 次而不是 2 次或 30 次优化后的调用序列大致是Read.claude/repomap.md拿到项目全貌Grep 或 Glob 定位目标文件比如搜token出现的位置Read 具体目标文件开始真正分析问题。第 2 步有时可以省略如果地图里的符号索引已经把目标文件标出来了那 Claude 会直接跳到第 3 步。严格说优化后是 2 到 3 次标题写 3 次是为了保留那个“定位确认”动作毕竟完全跳过搜索有时会让模型心里没底。省下来的不是某一次调用而是几十次“盲搜 排除”的组合。这些调用每个都没毛病但合起来就是几百 KB 的中间 Token、几分钟的等待以及上下文窗口被大量无用文件内容挤占的风险。地图方案把这些全部提前压缩掉了。1.3 这件事的收益比想象中大我自己最直观的感受是三个字稳、快、省。稳指的是回答质量稳定。默认探索模式下Claude Code 很容易在翻了一堆无关文件之后“迷失重点”有时候它读到一个同名测试文件就开始跑偏。看地图开局的话它很清楚自己在哪个模块、要动哪些文件跑偏概率明显下降。快指的是端到端耗时。同一个“排查 token 过期”任务默认模式从发起到给出第一个可靠的结论大概三到四分钟用地图后基本一分钟内就能进入代码分析阶段后面 Diff 和改代码的速度其实差不了太多。省指的是 Token 消耗。工具调用越多往返上下文越冗长。我做过一个对比测试默认模式下一次中型仓库探索大约产生 8 万到 12 万 Token 的中间消耗地图模式只有不到 2 万。具体成本按官方定价算不同模型差别不小但量级上通常能省一半以上。这个数字后面我会详细拆。2. 先搞懂 Claude Code 的工具调用机制想真正理解 52 次到 3 次的优化逻辑不能只当“咒语”背下来得先明白工具调用是怎么跑起来的。Claude Code 的底层是一个 agentic loop也就是“智能体循环”模型看一眼当前状态决定下一步调用哪个工具、传什么参数工具执行完把结果塞回对话历史模型再决定下一步。这个循环一直重复直到任务完成或是它觉得自己信息足够了。你可以把模型想象成一个被蒙着眼睛、但能通过递纸条指挥别人的人类专家。每次递纸条都是一个回合纸条上写“去 3 楼档案室拿文件夹”对方回来告诉你“3 楼没有档案室是会议室”你得再写一张纸条。52 次工具调用就是 52 次“递纸条—等回复—再递纸条”的往返。虽然每个回合本身很快但累积起来延迟和成本都非常可观。2.1 工具调用为什么“贵”贵在三个方面。第一是延迟。每次工具调用在本地或远端都要走一次完整的模型推理。你可以把模型推理当成一次“思考”思考虽然快但几十次叠起来体感就是从“秒回”变成“在转圈”。有些时候 Claude Code 卡在某个环节反复 Glob我盯着转圈的闪烁光标真想替它把目录树打印出来。第二是 Token。工具调用的输入里包含工具定义、参数、可能的 system prompt 片段输出里包含工具调用本身和执行结果。系统把这些全部追加到对话历史里。越往后调用历史越长每次推理要读的 Token 越多成本是指数增长的“累积”不是线性叠加。第三是上下文污染。默认探索模式下模型会读到大量与任务无关的文件内容比如某个旧版组件的完整实现、某个被废弃的 SDK 调用示例。这些内容占据上下文窗口让模型对“什么才是重点”的判断受到干扰。有时候它引用了一个根目录config.example.js的写法我一看就知道它是被某次过度搜索带偏了。2.2 默认探索工具全家桶Claude Code 常见的几个工具每个都有它的典型适用场景也有它的“滥用”形态Read读文件最基础也最高频。问题在于模型会在不确定时连续 Read 多个候选文件而这些文件往往只有一两个真正相关。Glob按通配符列文件。很多人以为 Glob 很廉价其实返回几百个文件路径也不是小事路径列表本身也要占 Token。Grep搜索内容适合找符号引用。但如果搜索词太宽泛比如搜user返回的匹配行可能又长又多同样费用不低。Bash执行命令。Claude Code 会用它跑ls、find、git log。这个工具最灵活但也是最容易拖慢节奏的因为模型有时候会拿它试一些“探索性命令”比如先ls src再ls src/api一路 ls 到底。默认模式下Claude Code 更像一个“勤快的实习生”愿意花时间把所有角落都翻一遍。这对安全性和最终准确性是好事但代价就是效率。它缺少的是“老员工的直觉”知道该去哪个目录找、哪个文件里藏着核心逻辑、哪些文件根本不用看。2.3 少调用不是让模型“变笨”而是给它“导航”很多人会有个误解工具调用次数越少是不是说明模型偷懒了、少干活了完全不是。工具调用是手段不是目的。模型的目标是完成任务而不是“多摸几个文件”。地图方案的本质是提高单次工具调用的信息密度。一次Read .claude/repomap.md返回的可能是一份 300 行的浓缩摘要包含整个项目的骨架和关键符号位置作为对比默认模式下可能需要 30 次 Read 才能拼凑出同等级别的认知。信息量没少只是换了一种更高效的获取方式。这也是为什么优化后模型没有“变傻”反而回答更精准它把原来花在“找路”上的推理资源都用在了“想清楚怎么改代码”上。就像你在陌生城市打车与其让司机绕路试错不如先看一眼地图 App规划好路线再出发。3. 优化思路给 Agent 一张代码地图地图方案听上去很朴素但做的时候有个关键原则地图必须“既能看懂全局又不至于把原代码搬进去”。我见过不少人把整个项目 README 拼接成一份超长文档塞给 Claude Code结果上下文窗口直接爆掉效果适得其反。真正好用的地图应该像一个经验丰富的开发者进新团队时老同事花十分钟给他画的那张“项目速写”这是入口这是业务模块这几个目录别碰核心逻辑散落在哪儿。它不是代码本身而是代码的“目录和摘要”。3.1 地图里到底该放什么我设计的repomap.md分四个区块顺序也很讲究开头是项目级概览三到五行告诉模型这个项目是什么类型、用了什么技术栈、入口在哪、测试怎么跑。这部分相当于 README 的精简版模型读完就不会再花调用去读完整 README 和依赖清单。第二块是目录树但不是完整tree输出而是深度限制在三层以内、过滤掉噪音目录后的“骨架树”。比如src/ api/ # HTTP 请求层 components/ # UI 组件 hooks/ # 状态与副作用逻辑 utils/ # 通用工具第三块是符号索引。我会用简单脚本扫描所有源码文件提取function、class、interface、const xxx 这类声明并标出文件路径。对 Claude Code 来说符号索引相当于“带坐标的目录”它看完就知道搜validateToken该去哪个文件。最后是文件级摘要。每个核心文件配一两句话比如src/api/client.ts — axios 实例封装管理 baseURL 与拦截器token 刷新逻辑在 response 拦截器里。摘要不需要写完整实现只写职责和关联。这样当任务牵涉到某个模块时模型能立刻判断该不该读这个文件而不是把整个仓库读一遍。3.2 三种主流做法对比在动手之前我把市面上常见的做法都试了一圈各有取舍。方案原理优点缺点手写 CLAUDE.md在项目根目录维护一份说明文档简单直接、零依赖靠人工维护容易过期MCP 代码索引服务通过 MCP 协议提供语义索引查询精确、可查询任意符号多一个常驻服务配置复杂repomap 预生成地图脚本扫描后输出 markdown 快照透明可控、一次生成、成本极低需要手动刷新快照我最终选了第三种核心原因是“透明”和“可控”。预生成地图就是一个普通 markdown 文件模型用Read就能读不需要额外的 MCP 服务不会引入连接错误、权限问题也不依赖第三方工具链。对大多数项目来说这种静态快照已经足够。MCP 索引方案在超大型 monorepo 里确实更优雅几十万行代码的项目里靠一份静态地图可能覆盖不全。但代价是你要维护一个常驻服务并且 Claude Code 每次提问都要通过 MCP 工具查询反而增加工具调用。对大多数几万行到十几万行的项目静态地图是最适合的。3.3 地图怎么生成才不坑生成地图的脚本我建议用 Node.js 或 Python 写不要用纯 Shell。原因是跨平台路径处理、文件过滤、编码处理上脚本语言更稳。核心逻辑就三步第一步遍历目录过滤掉.git、node_modules、dist、build、vendor、coverage这些常见噪音目录。过滤规则最好写成清单方便按项目定制。第二步对每个源码文件提取摘要和符号。摘要部分我一开始想用正则提取文件头注释后来发现很多文件没有规范注释所以我改成了两层方案有注释就用注释没有注释就用文件名 目录名 符号列表拼出一个“推断摘要”。第三步输出 markdown控制总行数。建议地图文件控制在 300 到 500 行以内太大的话读一次本身就成了负担。对超大仓库可以按子模块拆成多个地图文件比如.claude/modules/api.md、.claude/modules/core.md让 Claude 按需读取。生成频率上我建议每次大改动后运行一次或者直接绑定到 Git 的 pre-commit 钩子。索引过期是这类方案最常见的坑后面我会专门讲。4. 实操把 52 次降到 3 次的具体配置这部分是完整的落地过程。我的环境是 macOSNode.js 20Claude Code 用了当时最新的 CLI 版本。如果你在 Windows 或 Linux 上原理一样只有个别路径写法有区别。4.1 环境准备与常见安装问题第一步是确保 Claude Code 版本够新。如果你还没装用 npm 全局安装npm install -g anthropic-ai/claude-code装完可以用claude --version确认版本。Claude Code 更新很快老版本的工具行为和 prompt 策略差异不小很多“奇怪行为”升个版本就没了。登录环节有个很容易踩的坑如果你在企业环境里可能会看到组织禁用了订阅访问的提示。这个通常跟账号订阅类型和组织策略有关跟工具本身没关系。遇到就找管理员确认订阅配置或走官方支持渠道网上那些“绕过”方案既不稳定也有安全风险。另外我想提一句这个优化方案和具体模型无关。我身边有人通过兼容 API 接入其他模型跑 Claude Code优化效果同样成立因为地图方案改动的是工具调用策略而不是模型本身的推理逻辑。4.2 写一个 repomap 生成脚本脚本我不追求完美够用、稳定、能跑就行。下面这个 Node.js 版本是我实际在用的简化版const fs require(fs); const path require(path); const { execSync } require(child_process); const ROOT process.cwd(); const IGNORE_DIRS new Set([.git, node_modules, dist, build, vendor, coverage, .next]); const SRC_EXTS new Set([.js, .ts, .tsx, .jsx, .py, .go, .rs, .java, .vue]); const OUTPUT path.join(ROOT, .claude, repomap.md); function walk(dir, depth 0) { if (depth 3) return []; const entries fs.readdirSync(dir, { withFileTypes: true }); const lines []; for (const entry of entries) { if (IGNORE_DIRS.has(entry.name)) continue; const full path.join(dir, entry.name); const rel path.relative(ROOT, full).replace(/\\/g, /); if (entry.isDirectory()) { lines.push( .repeat(depth) entry.name /); lines.push(...walk(full, depth 1)); } else if (SRC_EXTS.has(path.extname(entry.name))) { lines.push( .repeat(depth) entry.name); } } return lines; } function extractSymbols(file) { const src fs.readFileSync(file, utf8); const symbols []; const regex /(?:function\s(\w)|class\s(\w)|const\s(\w)\s*|interface\s(\w))/g; let m; while ((m regex.exec(src)) ! null) { symbols.push(m[1] || m[2] || m[3] || m[4]); } return symbols.slice(0, 10); } function buildMap() { const tree walk(ROOT).join(\n); let symbolSection \n## 符号索引\n\n; const files []; (function collect(dir) { for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { if (IGNORE_DIRS.has(entry.name)) continue; const full path.join(dir, entry.name); if (entry.isDirectory()) collect(full); else if (SRC_EXTS.has(path.extname(entry.name))) files.push(full); } })(ROOT); for (const file of files) { const rel path.relative(ROOT, file).replace(/\\/g, /); const symbols extractSymbols(file); if (symbols.length) symbolSection - ${rel}: ${symbols.join(, )}\n; } const md # 项目地图\n\n## 目录结构\n\n\\\text\n${tree}\n\\\\n${symbolSection}\n; fs.mkdirSync(path.dirname(OUTPUT), { recursive: true }); fs.writeFileSync(OUTPUT, md, { encoding: utf8 }); console.log(repomap written: ${OUTPUT}); } buildMap();这段脚本有两个细节值得说明目录树深度限制在 3 层以内避免树太长每个文件的符号最多提取 10 个防止某些工具类文件刷屏。实际项目里符号索引可能有很多行这个限制让地图保持紧凑。如果你不想维护脚本也可以用命令行临时凑一个精简版claude_scaffold() { { echo # 项目地图 tree -L 3 -I node_modules|.git|dist|build --dirsfirst rg -n ^(function|class|const|interface|def|type) --type-add src:*.{js,ts,tsx,jsx,py} -t src . } .claude/repomap.md }这个版本没有摘要和符号分类只是目录树加符号列表的平铺胜在快。适合临时用在一个还没完全熟悉的新项目上。4.3 把地图接入 Claude Code脚本只负责生成地图真正让 Claude Code“会先读地图”的关键在CLAUDE.md。这是一个 Claude Code 的项目级记忆文件每次会话开始时它会自动被注入。我的CLAUDE.md开头是这么写的在分析或修改本仓库代码之前先读取 .claude/repomap.md 了解项目结构和关键符号位置。 根据地图定位相关文件后再直接读取具体文件避免大范围搜索。这段指令要写得“引导性”而不是“强制性”。我一开始写的是“必须先读 .claude/repomap.md”结果模型真的每次必读哪怕只是让它在某个文件里加一行注释。后来改成“在分析或修改代码之前”模型就会判断任务是否需要先看地图短任务直接开干长任务自动先读反而更聪明。还有一个好习惯把/init流程也接上。Claude Code 的/init会分析项目并建议初始 CLAUDE.md。我会先跑一次repomap再执行/init这样它生成的 CLAUDE.md 里就能引用真实的地图文件而不是空对空地猜。4.4 实测对比同样的任务两种模式跑一趟拿一个真实任务举例在一个 Node.js TypeScript 的项目里要求“找到刷新 token 的逻辑并说明它在哪里更新 access token”。默认模式下我观察到 Claude Code 花了这些调用先 Glob 全项目看结构再 Bash 跑find然后 Read README 和 package.json再 GreprefreshToken拿到匹配后 Read 了几个候选文件发现不对又 GrepaccessToken再 Read 两个新文件……整个过程工具调用 52 次中间有两次因为读到的文件内容太杂模型差点把关注点带到 API 网关的鉴权逻辑上。地图模式下开场就是Read .claude/repomap.md。地图里写着- src/api/client.ts: axios 实例封装管理 baseURL 与拦截器 - src/hooks/useAuth.ts: 登录态管理包含 refreshToken 逻辑模型随即用Grep refreshToken src/hooks/useAuth.ts src/api/client.ts确认位置接着Read src/hooks/useAuth.ts开始详细分析。工具调用 3 次整个过程从发出指令到给出结论大约 40 秒。对比数据我整理成表指标默认模式地图模式工具调用次数523中间 Token 估算约 9 万约 1.5 万端到端耗时约 3 分 20 秒约 40 秒是否绕路是否Token 估算只算“探索阶段”产生的中间消耗不包括最终生成的代码文本。不同模型、不同任务差异不小但这个量级对比是稳定的。4.5 成本与参数估算很多朋友关心省了多少“钱”。我按 Claude 系列模型的常见定价习惯做了个粗略折算默认模式多出来的约 7.5 万 Token如果按输入 Token 算大约是几美分的量级。单次任务看似乎不多但我一天要跑二三十次这样的探索一个月下来就是几十美元的量级差距。具体价格要以你实际使用的订阅或 API 定价为准但省一半以上是完全可以达到的。地图文件本身也有成本比如 300 行地图大约 4000 到 5000 Token。这个成本在会话一开始付一次后面所有探索都免了性价比相当高。如果你用/clear清空会话记得让模型重新读地图否则它又把项目当陌生代码库一样从头翻。5. 踩坑实录与排查技巧这个方案我用了一两个月中间踩了不少坑。有些是脚本问题有些是 Claude Code 行为习惯导致的整理出来希望对你有用。5.1 常见问题速查表问题原因解决办法地图文件是旧内容模型引用了不存在的文件生成脚本没在改动后重新运行手动重跑脚本或加到 Git 钩子地图太大一次 Read 就把上下文撑爆文件 300 行上限被突破按模块拆地图或加大过滤规则模型读了地图后还是不看仍然到处 GrepCLAUDE.md 指令过于软弱把“先读地图”提到指令第一行并加限定词符号索引乱码或漏符号正则不支持项目语言扩展提取正则或引入 ripgrep 配合Windows 下脚本路径分隔符问题path.join用了反斜杠统一替换成/输出时规范化企业环境登录被禁订阅或组织策略限制走管理员配置或官方支持第三方 API 兼容层下自定义工具失效对接层不完全支持官方工具集只依赖文件读取不引入 MCP5.2 独家避坑技巧第一个坑是“地图塞了完整代码”。早期版本里我给每个文件附了一段源码示例想着模型需要上下文。结果地图文件直接破千行一次 Read 读进来几万 Token前面省的全吐回去了。后来我强制要求自己摘要只能写“职责 关联”最多不超过三行。第二个坑是“索引正则不够准”。比如 TypeScript 项目里const foo () {}这种箭头函数声明简单的function正则抓不到Python 项目里def又是另一套。我的做法是维护一份按语言区分的正则集ts/tsx用一组py用一组宁可少抓也不要抓错目录。抓到node_modules里的符号不仅没用还会带偏模型。第三个坑是“CLAUDE.md 里写了太多‘必须’”。Claude Code 对强制指令的执行方式有时候很呆板。你写“必须先读地图”它哪怕只是修改一行注释也会先读地图多花一次调用。改成“在分析或修改代码之前”这种语义化指令后它反而更聪明地判断什么时候该读。这算是 prompt 工程里很微妙的点。第四个坑是“多个索引方案同时开”。我一度既用了 MCP 代码索引又放了 repomap结果模型一会儿查 MCP 一会儿读文件工具调用次数反而更多。后来我给自己的规矩是任何场景只保留一种“了解项目结构”的方案地图文件优先。5.3 什么时候不该用这个方案地图方案不是万能的。以下几类场景我会刻意不用新项目还没成型、只有两三个文件的时候根本不用地图直接让 Claude 读文件更直接。刚 clone 下来但已经有一份由 AI 生成的 README 时地图大概率也是多余的因为模型可以直接读 README。短任务场景比如“给某个文件加一个导出语句”地图方案反而多读一次文件纯属浪费。代码库经常剧烈变动、但你来不及重新生成地图的时候死守一份旧地图去指导 Claude可能比让它自己探索还危险。判断标准只有一条地图带来的“方向增益”是否大于“一次读取的固定成本”。对中型以上项目、长会话、复杂改造任务增益远大于成本对轻量任务就别折腾了。6. 我的一点体会用了一段时间之后我最大的收获反而不是省了多少 Token而是“先给地图再看代码”这个习惯被我带回了日常开发里。以前接盘不熟悉的项目我也像 Claude Code 默认模式一样到处翻现在我会先花十分钟梳理目录结构、写一份简短的模块说明再开始改代码。脑子清晰很多返工也少了。repomap这个名字是我自己起的代码也谈不上多优雅但它解决了一个很实际的问题AI 编程助手在自己熟悉的上下文里可以很强但你要先想办法让它“熟悉”你的项目。与其让它每次会话都从零开始翻不如主动送它一张地图。后续我打算把地图生成挂到 CI 上每次合并主干后自动更新这样团队成员都能拿到最新快照也想试试按 Git 变更自动生成“增量地图”只标注最近改动的文件。这些还都是想法等跑通了再分享具体效果。