鹅厂打饭阿姨都懂的 Claude Code 上下文管理：Auto-Compact 与 CLAUDE.md 配置实战

1. 打饭窗口前的那个问题Claude Code 上下文为什么会满Claude Code 是 Anthropic 推出的命令行编程 Agent它能在终端里读代码、改文件、跑测试、执行命令适合需要长时间连续编码的开发者。但很多人用着用着就会发现一个现象任务跑到一半它开始忘事——前面说好不要动的文件被改了已经排除的方案又被重新提出来甚至开始重复读同一个文件。这不是模型变笨了而是上下文窗口被撑满了。上下文窗口不是模型的长期记忆它只是模型一次推理时能看到的全部 token 空间。每一轮对话系统都会把系统提示词、工具定义、历史消息、文件内容、命令输出、CLAUDE.md 等全部拼成输入。Claude Code 作为 Agent每一轮都可能调用工具工具结果又会进入上下文所以它的消耗速度远高于普通聊天。我试过让它修一个登录超时的问题它先搜 login再读登录页、读 API 封装、读鉴权中间件、跑测试、看报错、改代码、再跑测试。整个过程下来光测试日志和文件内容就吃掉了几万 token。真正把窗口撑爆的往往不是用户说了多少而是工具调用轨迹太重。Claude Code 对此的应对分两层一层是 Auto-Compact在接近上限时自动把旧轨迹压成任务状态快照另一层是 CLAUDE.md把稳定规则从对话历史里挪出来压缩后重新注入。下面从配置和验证两个角度把这两层拆开讲清楚。2. 前置准备TaoToken 接入 Claude Code 的 Key 与地址要让 Claude Code 跑起来先得有一个能用的 API 入口。TaoToken 提供 Claude Code 的接入能力官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。第一步打开控制台创建 API Key。地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 。登录后进入 API Keys 页面点新建复制生成的 key形如sk-xxxxxxxx。这个 key 只显示一次建议先存到密码管理器里。第二步如果你打算长期用 Claude Code 做编码和 Agent 任务可以看一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan 。它面向的就是这种长会话、高频工具调用的场景比按量计费更可控。第三步把 key 写进环境变量。Claude Code 读取的是ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL两个变量。在~/.zshrc或~/.bashrc里加export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_BASE_URLhttps://taotoken.net/api然后source ~/.zshrc让配置生效。注意 base url 后面不要多加/v1Claude Code 会自己拼路径。第四步验证 key 是否可用。可以用 curl 直接打一次模型对话接口curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 只回复 ok}] }返回里能看到content字段带ok说明 key 和地址都通了。如果返回 401检查 key 有没有多余空格返回 404检查 base url 是不是写成了带/v1的形式。3. 可复制配置CLAUDE.md 骨架与 settings.json 片段CLAUDE.md 是 Claude Code 的项目级记忆文件放在项目根目录每次会话启动时自动注入。它的价值在于这些规则不依赖聊天历史即使 Auto-Compact 把旧对话压掉了根目录的 CLAUDE.md 仍会在压缩后重新注入。所以稳定规则写这里临时要求放对话里。下面是一份可以直接改的 CLAUDE.md 骨架# 项目说明 ## 技术栈 - 包管理器pnpm禁止使用 npm 或 yarn - 语言TypeScript 5.x严格模式 - 测试框架vitest ## 常用命令 - 安装依赖pnpm install - 跑测试pnpm test - 单文件测试pnpm test file - 类型检查pnpm tsc --noEmit ## 编码规范 - 遵循现有目录结构和命名风格 - 新增函数必须写 JSDoc - 不要引入新的第三方依赖除非明确要求 ## 禁止事项 - 不要修改数据库 schema - 不要改动 public API 的请求/响应结构 - 不要删除已有测试用例 ## 关键术语 - 订单 指 Order 实体不是 OrderItem - 同步 指 syncOrder 流程不是数据库主从同步这份骨架的重点是把跨任务都成立的规则固化下来。判断标准很简单如果这条规则下个任务还用得上就写进 CLAUDE.md如果只对当前这个 bug 有效就留在对话里。接下来是 settings.json。Claude Code 的配置文件在~/.claude/settings.json可以控制权限、环境变量和上下文相关行为{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key }, permissions: { allow: [ Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm tsc:*) ], deny: [ Bash(rm -rf:*), Bash(git push:*) ] } }allow里放的是高频且安全的操作避免每次都要确认deny里放的是危险操作直接拦掉。这样 Agent 在长会话里跑工具时不会因为反复弹确认而打断节奏也不会误删东西。如果你想让压缩行为更可控可以在项目根目录再放一个.claude/settings.json覆盖全局配置。项目级配置优先级更高适合团队共享。4. 验证请求压缩前后 token 占用的实测动作配置写完了得知道上下文到底花了多少。Claude Code 提供了/context命令在会话里直接输入就能看到当前 token 占用分布。启动 Claude Codeclaude进入会话后先输入/context你会看到类似这样的输出Context Usage System prompt: 2,100 tokens Tools: 4,800 tokens Messages: 1,200 tokens CLAUDE.md: 600 tokens Free space: 191,300 tokens这时候 Messages 还很小。现在让它做一个稍复杂的任务比如读一下 src/auth 目录找出 token 续期逻辑跑一下相关测试。等它跑完再输入/contextContext Usage System prompt: 2,100 tokens Tools: 4,800 tokens Messages: 38,500 tokens CLAUDE.md: 600 tokens Free space: 154,000 tokensMessages 从 1,200 涨到 38,500这就是工具调用轨迹的消耗。继续让它改代码、再跑测试Messages 会继续涨。当它接近上限时Auto-Compact 会触发你会看到一条提示说明正在压缩会话。压缩完成后再看/contextContext Usage System prompt: 2,100 tokens Tools: 4,800 tokens Messages: 6,300 tokens CLAUDE.md: 600 tokens Free space: 186,300 tokensMessages 从 38,500 掉回 6,300这就是压缩的效果。注意 CLAUDE.md 那 600 token 还在因为它在压缩后被重新注入了。这就是为什么稳定规则要放 CLAUDE.md——它不会因为压缩而消失。如果你想手动控制压缩时机用/compact/compact 保留 auth 模块的修改进度和未完成的测试用例这样压缩摘要会聚焦在你指定的内容上。如果当前任务已经做完直接/clear清空历史开始新任务。三个命令的语义对照命令作用什么时候用/context查看 token 占用分布想知道上下文花在哪/compact摘要当前会话并继续任务没做完但上下文快满了/clear清空聊天历史任务已切换旧上下文不需要了5. 本篇常见错排查压缩后断片、规则丢失、token 不降5.1 压缩后 Agent 开始重复之前排除过的方案这是最典型的症状。原因通常是压缩摘要里没有保留已排除路径这一项。Auto-Compact 的摘要质量取决于当前会话里有没有明确表达过排除结论。如果你只是让它试了一下没成功但没让它说这条路不通摘要里可能就不会记。解决办法是在排除某个方案时明确说一句记录一下X 方案已验证不通原因是 Y后续不要再走这条路。 这样摘要里就会带上这条结论。5.2 CLAUDE.md 写了但压缩后规则还是丢了检查两件事。第一CLAUDE.md 是不是放在项目根目录。嵌套目录里的 CLAUDE.md 要等 Agent 读到那个目录的文件时才会加载压缩后不一定立即重新注入。第二规则是不是写得太模糊。比如注意代码质量这种模型没法执行要写成新增函数必须写 JSDoc这种可判断的。5.3/context显示 token 没降多少可能有两个原因。一是压缩刚触发摘要本身也占 token如果原会话特别长压缩后 Messages 可能仍有几万。二是工具定义和系统提示词是固定开销压缩动不了它们。如果 Tools 占了很大比例说明你开的工具太多可以在 settings.json 里限制权限范围减少不必要的工具加载。5.4 压缩后 Agent 不记得当前改到哪个文件了这是文件状态没进摘要。在压缩前主动说一句当前已修改 src/auth/refresh.ts 的 refreshToken 函数还没跑测试。 或者用/compact时带上 focus 参数。Auto-Compact 会优先保留用户明确强调的状态。5.5 长会话里 Agent 越来越慢不一定是上下文的问题也可能是工具调用次数太多。用/context看 Messages 占比如果已经超过 70%手动/compact一次。如果压缩后还是慢考虑/clear重开把当前进度写进 CLAUDE.md 或一个临时笔记文件让新会话读。6. 什么时候手动清理什么时候交给自动压缩判断标准其实很简单看当前任务是否还需要继续。如果任务没做完上下文快满了用/compact并在压缩时说明保留重点。Auto-Compact 也会自动触发但手动触发的好处是你能控制摘要的焦点。压缩后 Agent 能接着干因为它拿到的是任务状态快照不是流水账。如果任务已经做完或者你要切换到完全不相关的新任务直接/clear。旧上下文对新任务只有干扰没有价值。很多 Agent 漂移的案例根源就是旧任务的残留状态污染了新任务的判断。稳定规则永远放 CLAUDE.md不要依赖对话历史。临时状态放对话里压缩时明确保留。工具输出能截关键就截关键不要让几百行日志完整进上下文。如果你还没配好接入先去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys 拿一个 key接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 。想先验证模型对话是否正常可以用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchat 试一轮。长期做编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan 比按量计费更适合高频工具调用的场景。