1. 从用量砍半说起一个让我重新审视 AI 编码工作流的信号九月底那几天我在整理自己的 AI 工具账单时发现了一个挺有意思的现象同样强度的日常开发任务OpenAI 这边的 token 消耗比上个月少了将近一半而 Claude Code 的使用时长反而在稳步上升。这个变化不是刻意控制的结果而是工作流自然演进出来的。我一开始以为是任务量变少了翻了一下 git 提交记录和项目进度发现产出其实没降甚至因为几个重构任务并行推进代码改动量还更大了一些。这就值得琢磨了。用量砍半这件事表面上看是省钱往深了说其实是每一次调用是否都花在了刀刃上的问题。过去我习惯把 AI 当成一个万能问答机遇到任何问题都丢过去让它从头解释一遍。现在我的做法变了能用本地工具静态分析解决的绝不调用大模型能用一次精准 prompt 拿到结果的绝不来回追问三轮。这种转变背后是对AI 编码代理这个角色定位的重新理解——它不是聊天机器人而是一个需要被编排、被约束、被复用的工程组件。这篇日记式的总结我想把最近这段时间在 Claude Code 上的折腾、踩坑和自我优化过程完整地梳理一遍。涉及的内容包括为什么 Claude Code 的代理式工作模式比传统补全更省 token、安装配置过程中那些官方文档没写清楚的细节、如何用第三方模型接入来进一步压低成本、以及我自己总结出来的一套让 AI 少说废话多干活的 prompt 编排习惯。如果你也在用或者准备用 Claude Code 这类命令行编码代理这些经验应该能帮你少走一些弯路。需要先说明一点下面提到的所有工具、模型、配置方式都是基于我个人的实际使用场景总结的不同人的项目结构、网络环境、团队规范不一样具体参数需要自己调整。我不会给出任何万能配置因为那东西不存在。2. Claude Code 到底解决的是什么问题代理式编码和传统补全的本质区别2.1 从补全下一行到完成一个任务大多数人最早接触的 AI 编码辅助是 IDE 里的行级或函数级补全。你敲几个字符它猜你接下来要写什么。这种模式的问题在于它只对局部负责不知道你这个改动在整个项目里意味着什么。你让它补一个函数它补得漂漂亮亮但这个函数调用的接口可能已经在上周被重构掉了。Claude Code 这类工具走的是另一条路。它把整个项目目录作为上下文你给它一个自然语言描述的任务它自己去读文件、找依赖、改代码、跑测试最后告诉你改完了这是 diff。这个过程中它可能会执行终端命令比如npm test、git diff、grep之类的。这就是所谓的代理式agentic工作模式。我举个自己项目里的真实例子。有一次我需要把一个旧的日期处理库从 moment.js 换成 dayjs涉及十几个文件。如果用传统补全我得一个个文件打开手动改 import手动替换 API 调用还得注意 moment 和 dayjs 在某些方法上的行为差异。用 Claude Code 的话我只需要说一句把项目里的 moment 全部替换成 dayjs注意处理 format 和 diff 方法的兼容性它就会自己去扫描、替换、然后跑一遍测试看有没有挂。这个差别带来的 token 消耗结构是完全不同的。传统补全每次请求都很小但请求次数极多代理式编码单次请求的上下文很大但一次能解决一整类问题。我那个用量砍半的观察很大程度上就是因为把大量碎片化的补全请求合并成了少数几个高质量的代理任务。2.2 为什么它比复制粘贴到网页版更省心很多人现在的习惯还是打开网页版对话把代码贴进去让它改再贴回来。这个流程在单文件、小改动的时候还行一旦涉及多文件就非常痛苦。你得手动维护上下文得自己判断它改的地方对不对还得处理它幻觉出来的不存在的 API。Claude Code 跑在终端里直接操作你的工作目录改完的代码就在原地你可以立刻git diff看改动不满意就git checkout回滚。这个就地操作 版本控制兜底的组合是我认为它最实用的地方。它把 AI 的输出从一段需要你手动搬运的文本变成了一次可以直接审查的代码变更。提示第一次用代理式工具改代码之前务必确保工作区是干净的git status没有未提交改动这样出问题可以一键回滚。我吃过这个亏有一次它改到一半我手动干预结果两边改动混在一起回滚都回不干净。2.3 它不适合什么场景说句实在话Claude Code 不是万能的。我总结下来以下几类任务用它反而低效需要大量业务背景知识的改动比如这个订单状态机为什么这么设计它读代码能读出结构但读不出你们团队三年前为什么做了这个决策。UI 像素级调整它看不到渲染结果只能根据 CSS 猜改出来的东西经常需要你手动微调。涉及外部系统状态的调试比如线上数据库的某个字段为什么是脏数据它没有那个环境的访问权限。认清边界之后我把它主要用在重构、批量替换、写测试、补文档、排查静态可分析的 bug 这几类任务上。这几类任务恰好是 token 消耗的大头优化它们用量自然就下来了。3. 安装与配置那些官方文档一笔带过、实际会卡住你的细节3.1 环境准备阶段最容易忽略的两件事Claude Code 的安装本身不复杂官方给的命令就那么一条。但我在 macOS、Ubuntu、Windows 三个环境上都装过之后发现真正卡人的不是安装命令而是安装之前的两个前置条件。第一是 Node.js 版本。它依赖的某些包对 Node 版本有要求我一开始在 Ubuntu 上用系统自带的旧版本 Node装完跑起来各种奇怪的模块报错。后来统一用 nvm 管理切到当前 LTS 版本问题就没了。这个坑的隐蔽之处在于安装过程本身不报错是运行的时候才出问题很容易误以为是工具本身的 bug。第二是终端环境的 PATH 配置。如果你是用 npm 全局安装的要确认 npm 的全局 bin 目录在 PATH 里。我在 macOS 上遇到过装完了但claude命令找不到的情况查了半天发现是 shell 配置文件里 PATH 没包含 npm 全局目录。这个用npm config get prefix看一下就知道该往 PATH 里加什么。# 查看 npm 全局安装路径 npm config get prefix # 确认该路径下的 bin 目录在 PATH 中 echo $PATH3.2 登录方式的选择直接登录还是走 API KeyClaude Code 支持两种认证方式一种是直接用账号登录一种是配置 API Key。这两种方式在体验上有实际差别不是随便选一个就行。直接登录的好处是省事不用管 key 的轮换和额度。但它的限制在于某些地区可能不在支持范围内而且登录态偶尔会过期需要重新认证。API Key 的方式更灵活可以配合第三方中转服务使用也能更精细地控制用量和成本但需要你自己管理 key 的安全性。我自己的做法是主力开发机用直接登录因为稳定测试机和 CI 环境用 API Key因为需要自动化。这样两边的好处都能占到。注意API Key 千万不要硬编码在项目文件里然后提交到 git。我见过有人把 key 写在.env里但忘了加.gitignore结果推到公开仓库几分钟内就被扫到并盗用了。正确做法是放在系统环境变量或者专门的密钥管理工具里。3.3 编辑器集成VS Code 插件配置的几个关键项Claude Code 有 VS Code 插件装完之后需要在设置里配几个东西才能用得顺手。我踩过的坑主要集中在它到底以哪个目录作为工作根目录这个问题上。默认情况下插件会以你打开的 workspace 根目录作为上下文范围。如果你的项目是 monorepo根目录下有十几个子包它扫描起来会非常慢而且容易把不相关的代码也读进去。我的做法是在 monorepo 里针对具体子包单独打开一个窗口或者用配置项把上下文范围限制到当前子目录。另一个关键项是是否允许自动执行终端命令。这个默认是关的需要你手动确认每一次命令执行。我建议新手保持这个默认等你对它的行为模式足够熟悉了再考虑对某些安全命令比如ls、cat、git status开启自动执行。千万别一上来就全开万一它执行了个rm -rf之类的哭都来不及。配置项建议值原因工作目录范围限制到具体子项目避免 monorepo 全量扫描拖慢速度自动执行命令初期关闭熟悉后按白名单开启防止误执行破坏性命令上下文文件数上限根据项目大小调整太大浪费 token太小信息不全是否读取 .gitignore开启避免把 node_modules 等读进去3.4 第三方模型接入用 CC Switch 之类的工具切换后端这是最近社区里讨论很多的一个方向。Claude Code 本身是绑定特定模型的但通过一些切换工具可以把它接到其他模型后端上比如 DeepSeek、Qwen、GLM 这些。这么做的主要动机是成本——某些国产模型在代码任务上的表现已经相当能打价格却低不少。我用 CC Switch 这类工具的实际体验是配置本身不难难的是模型能力匹配。不同模型对工具调用的支持程度不一样有的模型能很好地理解读文件、改文件、跑命令这套代理协议有的则经常在工具调用格式上出错导致任务中断。所以切换后端之后一定要拿几个典型任务测一下别直接上生产项目。配置的大致思路是在切换工具里填好目标模型的 API 端点和 key然后让它接管 Claude Code 的请求转发。具体字段每个工具不太一样但核心就是端点 认证 模型名这三样。# 大致的环境变量思路具体字段以工具文档为准 export ANTHROPIC_BASE_URL你的中转端点 export ANTHROPIC_API_KEY你的key export ANTHROPIC_MODEL目标模型名提示切换后端之后先在一个测试仓库里跑几个简单任务验证工具调用是否正常确认没问题再切到主力项目。我见过有人直接切到生产仓库结果模型工具调用格式不对把文件改得乱七八糟。4. 让 AI 少说废话多干活我的 prompt 编排与成本控制习惯4.1 任务描述的颗粒度太粗和太细都费钱这是我这段时间最大的心得。给代理式工具下任务颗粒度控制直接决定了 token 消耗和成功率。任务描述太粗比如优化一下这个项目它会先花大量 token 去扫描、理解、猜测你的意图然后可能给你一个你根本不想要的方案。这中间的探索过程全是白花的钱。任务描述太细比如把每一步操作都写清楚先打开 A 文件第 30 行把 xxx 改成 yyy那你还不如自己改用 AI 的意义就没了而且它可能因为你的描述和实际代码对不上而反复确认。我摸索出来的甜点区是说清楚目标和约束不说具体步骤。比如把 src/utils 下所有日期处理函数统一用 dayjs 重写保持函数签名不变改完跑一遍相关测试。这个描述给了它目标统一用 dayjs、范围src/utils、约束签名不变、跑测试但没规定它怎么改。它自己会去读文件、判断哪些是日期处理函数、怎么替换。4.2 用先规划后执行模式避免返工Claude Code 有个很好用的模式你可以先让它给出一个执行计划你确认之后再让它动手。这个模式在复杂任务上能省下大量返工成本。我现在的习惯是凡是涉及超过 5 个文件的任务第一步都是让它先列计划。它列出来的计划里经常会有一些我没想到的点比如这个改动会影响 X 模块的测试需要同步更新。我确认计划没问题再让它执行。这样比它闷头改完发现方向错了要省得多。这个规划步骤本身也消耗 token但相比返工重来的成本这笔投入非常划算。我算过一笔账一个中等复杂度的重构任务直接执行如果方向错了返工一次的成本大约是规划成本的 3 到 5 倍。4.3 上下文管理什么时候该开新会话代理式工具的一个特点是会话越长上下文里积累的信息越多每次请求携带的 token 也越多。如果你一个会话里连续做了五六个不相关的任务后面的任务会背着前面所有任务的上下文包袱又慢又贵。我的做法是一个任务一个会话。任务完成、验证通过之后直接开新会话做下一个。这样每个会话的上下文都是干净的只包含当前任务相关的信息。有人担心开新会话会丢失之前的理解。其实不会因为代码改动已经落到文件里了新会话读文件就能拿到最新状态。真正需要跨任务保留的是那些决策背景比如我们为什么选了这个方案这种我会写在项目的文档或者 commit message 里而不是指望 AI 记住。4.4 用本地工具做前置过滤减少无效调用回到开头说的用量砍半很大一部分功劳要归给前置过滤。很多问题其实不需要 AI 就能定位比如语法错误linter 和编译器直接告诉你类型错误TypeScript 的类型检查未使用的变量、importESLint 规则简单的拼写错误grep 一下就能找到我现在的流程是先跑一遍 lint 和类型检查把这类低级问题清掉剩下的真正需要理解语义的问题才交给 AI。这样 AI 处理的都是硬骨头每一次调用的价值都更高。# 典型的前置检查流程 npm run lint # 先清掉风格和明显错误 npm run typecheck # 再清掉类型问题 npm test # 跑一遍测试看有没有已知失败 # 以上都过了剩下的问题才交给 AI 分析这个习惯养成之后我发现 AI 的一次成功率明显提高了因为它拿到的输入更干净不会被一堆低级错误干扰判断。5. 实测中的意外情况与排查链路5.1 工具调用失败从报错信息倒推根因用代理式工具最常见的意外就是工具调用失败。表现是它想读某个文件或者跑某个命令但执行报错然后它可能卡在那里反复重试或者干脆放弃。我遇到过一次典型的它想读一个文件但报文件不存在。我一看路径发现它把相对路径理解错了因为我的工作目录和它以为的不一样。这个问题的根因是启动 Claude Code 时的当前目录不对。解决办法很简单就是在正确的项目根目录下启动。排查这类问题的思路是先看它想做什么再看它实际做了什么最后对比差异。报错信息通常会告诉你它尝试的路径或命令你手动执行一遍就能看出是路径问题、权限问题还是命令本身不存在。5.2 模型幻觉出不存在的 API如何快速识别这是所有 AI 编码工具的通病。它会很自信地调用一个根本不存在的函数或者用一个库的旧版 API。识别方法其实不难看它改完的代码能不能通过类型检查和测试。如果它调用了一个不存在的函数TypeScript 会直接报错测试也会挂。我的习惯是AI 改完代码后第一件事不是看 diff而是直接跑类型检查和测试。这两个过了再去看 diff 审查逻辑。这样能把大部分幻觉挡在早期。如果测试挂了我会把报错信息直接贴回给它让它自己修。通常它能根据具体的报错定位到问题。如果它连续两次修不好我就手动介入因为再让它试下去就是浪费 token 了。5.3 上下文丢失长会话后期忘记前面说过的话长会话跑到后面模型可能会忘记你前面强调过的约束。比如你一开始说了不要改测试文件跑到后面它还是改了。这不是它故意的而是上下文太长早期的指令权重被稀释了。应对办法有两个一是前面说的一个任务一个会话从根上避免长会话二是把关键约束写在任务描述的最前面和最后面两头都强调一遍。我实测下来把约束放在任务描述末尾比放在开头更有效因为模型对最近的内容注意力更高。5.4 网络与依赖问题那些和 AI 本身无关的坑有些报错看起来像是 AI 工具的问题其实是环境问题。比如依赖装不上、网络请求超时、某个可选依赖缺失。我遇到过missing optional dependency这类报错查下来是某个平台特定的二进制包没装上跟 AI 逻辑一点关系都没有。这类问题的排查原则是先确认是不是环境问题再怀疑工具本身。方法很简单把报错信息里的命令手动跑一遍如果手动也失败那就是环境问题跟 AI 无关。手动能成功但 AI 执行失败才需要去看工具的配置。报错类型大概率原因排查方向文件不存在工作目录不对确认启动目录命令找不到PATH 配置问题检查环境变量依赖缺失安装不完整重装依赖工具调用格式错误模型不支持该协议换模型或换后端上下文超限会话太长开新会话6. 自我优化循环我是怎么让这套工作流越用越顺的6.1 记录每次翻车形成自己的避坑清单我从开始用这类工具起就有一个习惯每次它翻车我都在一个笔记文件里记一笔——什么任务、什么表现、根因是什么、怎么解决的。积累了两三个月之后这个清单成了我最值钱的东西。因为 AI 工具的行为模式是有规律的同一个坑你踩过一次下次就能提前规避。比如我现在知道涉及数据库 migration 的任务它容易出错那我就会在任务描述里额外强调不要自动执行 migration只生成文件。这种针对性的约束都是从历史翻车记录里总结出来的。6.2 把重复性任务模板化有些任务我每周都要做比如给新写的函数补单元测试、更新 API 文档。这类任务我把它固化成了模板 prompt存在一个文件里用的时候直接复制。模板化的好处是你不用每次重新想怎么描述而且模板是经过多次迭代优化的成功率比临时想的描述高。我的模板一般包含任务目标、范围限定、约束条件、验收标准这四块。6.3 定期回顾用量找出高消耗低产出的任务类型这就是开头用量砍半的由来。我每个月会看一下用量分布找出哪些任务类型消耗特别高但产出一般。上个月我发现让它解释一段复杂代码的逻辑这类任务消耗很高但解释完我还得自己验证价值有限。于是我把这类任务改成了先自己读读不懂再问且问的时候带上我的理解让它纠正这样 token 消耗降下来了理解深度反而上去了。6.4 保持对工具的怀疑不盲信输出最后说一个心态层面的东西。AI 编码工具再强它也是在猜你的意图。它给出的方案看起来合理不代表真的对。我现在对它的输出始终保持一层怀疑改完的代码一定跑测试涉及业务逻辑的一定人工 review涉及数据操作的一定先在测试环境验证。这种怀疑不是不信任而是把它当成一个能力很强但需要监督的初级同事。你信任它的执行力但关键决策还得自己把关。这个定位摆正了用起来就顺了也不会因为它偶尔翻车就全盘否定。说到底工具是死的人是活的。Claude Code 也好其他代理式工具也好它们能帮你省下大量重复劳动但省下来的时间该花在哪、怎么花还是得自己想清楚。我这段时间最大的收获不是学会了某个具体命令而是想明白了哪些活该交给 AI哪些活必须自己干这条边界。边界清楚了用量自然就下来了产出反而上去了。