你让 Claude Code “重构全应用的 auth 流程”，它开始读 src/auth/ 加 src/api/ 里的每个文件、把三个大配置文件塞进 context，重构做到一半撞上下文上限、自动摘要——把你刚花 40K token 建好的 plan 丢掉了。下一条消息提了一个和原 plan 第 3 步矛盾的方案。根因：你交给 Claude 的任务总信息预算超过了模型的 200K 上下文窗口，摘要必然发生。修法是把任务拆到每个子任务舒服地装进 60-80K token，子任务之间靠磁盘留状态。
常见原因
1. 任务涉及的文件多到一个 context 装不下
一次重构 30 个文件意味着读 30 个、改的时候还得记得它们的内容、再写回。每文件 3-5K token，光读完就 100-150K。模型只剩 50K 用来思考——非平凡重构根本不够。
如何判断：session 开局是一长串 Read / Grep，没做任何 Edit 之前上下文用量指示器就过 50%。
2. CLAUDE.md 或 AGENTS.md 太大
5000 行的 CLAUDE.md 每次 session 启动就吃 15-25K token——还没收到你第一条消息预算就少了。有用的任务就没有它需要的余量。
如何判断：全新 session 上来就显示用了 >10% 上下文——还没干活就这样。wc -l CLAUDE.md 量一下、嵌套的 AGENTS.md 也量一下。
3. 搜索范围过宽
在大仓库里 Grep -r "auth" 出几千条匹配；模型”为了周全”全部装进 context。其实大部分匹配根本不相关。
如何判断：Grep 之后 context 跳了 20K+ token。看 Grep 输出——几百行就是范围太宽。
4. 长长的工具错误 trace 吃光预算
Bash 命令失败每次打 200 行栈追踪、重试 4 次——光这一项就 30-40K token、全是噪音。
如何判断：session 里有多次工具失败、每次失败后上下文指示器都往上爬。
5. plan mode 出的 plan 太大
“周全的 plan”列出每个文件、每个步骤，膨胀到 8-12K token。加上为验证 plan 做的支撑读取——还没生成代码模型已经用了 50% 上下文。
如何判断：plan mode 产出超过 200 行；session 开始执行的时候上下文已经用了不少。
6. 该重启没重启的长 session
跑了 4 小时还没 restart 的 session、plan + 决定 + 工具调用 + 错误 + 重试都堆在那里。哪怕没有单个大动作、累积负载也会装满窗口。
如何判断：session 跑了几小时；最近消息有摘要指示、或者 context > 80%。
动手前先确认
- 开始新任务前先看一眼 Claude Code 的上下文用量指示器。
- 估一下任务规模：涉及多少文件、多少工具、多大输出。任何一个数字感觉大就先拆。
- 分清哪些文件真要整文件读、哪些可以采样或 grep。
需要收集的信息
- 当前 CLAUDE.md 和 AGENTS.md 大小（
wc -l）。 - 大概的 session 时长和最近做过的操作。
- 任务原文和已经下过的约束。
- 任务涉及区域文件数粗估。
- 这个 session 里用没用过 sub-agent。
- 有没有进度文件（
.agent-progress.md之类）。
最短修复路径
Step 1：把任务拆成”能装进一个 context”的小块
把任务改写成 3-5 个有顺序的子任务，每个大概 60-80K token：
旧（一个任务、太大）：
"重构全应用的 auth 流程"
新（四个子任务）：
1. 读当前 auth 模块，把重构 plan 写到 .auth-refactor-plan.md
2. 重构 src/auth/login.ts 和 src/auth/session.ts（提交）
3. 在 src/api/* 里把调用方更新到新接口（提交）
4. 更新测试并跑（提交）每一步都能独立提交、独立开新 context。
Step 2：读得多的调查交给 sub-agent
“去搞清楚 X 是怎么运作的”这类任务通过 Task 工具开 sub-agent。sub-agent 读 30 个文件、返回一份 500 token 的摘要——你的主上下文只看到摘要：
开 sub-agent：
"读 src/auth/ 和 src/api/auth* 下所有文件，输出一份 markdown 报告：
当前公开接口、调用方、session 存储、错误处理模式。只返回报告。"主 session 上下文干净；sub-agent 的读取在自己窗口里。
Step 3：用定点读取替换整文件读取
不要 Read src/api/users.ts（500 行、4K token），改成：
Grep "session" src/api/users.ts → 12 个匹配、200 token
Read src/api/users.ts:120-150 → 30 行、250 token大部分 edit 需要的是文件里的一小块、不是整个文件。
Step 4：CLAUDE.md 瘦身、只留承重内容
CLAUDE.md 应该控制在 500 行以下（约 2K token）。把陈旧或者很少用的内容挪到限定范围的文件、按需加载：
CLAUDE.md → 留：架构决定、约定、绝对不能违反的规则
apps/web/AGENTS.md → web 特定细节（只在 apps/web/ 工作时加载）
docs/historical-decisions.md → 归档的历史理由（要用时再读）Step 5：步骤之间把 plan 和状态落盘
把 plan 写到文件里、每步完成就提交、下一步开新 context 只输入 plan 文件：
# 重构 Step 1：
echo "## 重构 plan" > .auth-refactor-plan.md
# Claude 把 plan 写进这个文件
# Step 2（新 session）：
# 开新 session，粘："读 .auth-refactor-plan.md，只执行第 2 步"每一步上下文起点从 60% 降到 <10%。
Step 6：在干净边界 restart
上下文指示器过 60% 就收尾当前子任务、开新 session——不要硬撑到 95% 再被强制摘要丢掉工作。
收尾信号：用到 60%，收尾当前步、提交、restart
紧急信号：用到 80%，保存当前状态、restart干净边界 restart 永远比从撞坏的状态救回来便宜。
怎么确认已经修好
- 当前任务装得下预算——执行全程用量保持在 70% 以下。
- 任务中途没发生自动摘要。
- 如果上下文 reset 了，每个子任务都能从保存的 plan 独立重跑。
- 最终结果和原 plan 一致、没有因为有损记忆漂移。
- commit 按子任务结构的逻辑增量落地。
长期预防
- 60% 用量当收尾触发、不当”还能继续”信号。
- CLAUDE.md 控制在 500 行以下；少用的内容挪到限定范围文件。
- 默认走 Grep + 定点 Read、不要默认整文件 Read。
- 涉及 >10 个文件的任务先拆再开始。
- 任何需要读 >5 个文件的调查走 sub-agent。
- 超过 20 分钟的任务都把 plan 和进度落盘——上下文 reset 也不丢。
- 每个多文件重构做完后回顾哪些文件是真要读、哪些是防御性读。
常见坑
- 把 2000 行的文件粘进对话”做参考”——这一粘吃掉 8K token 余量。
- 一个 session 里把同一个文件读三次、agent 忘了自己已经有过。
- 跑产生海量 stdout 的
Bash（find /、tree、cat 大日志）——管道接head或者写到文件再 refer。 - 上下文用量指示器过 90% 才看——这时候摘要在即、你依赖的 plan 可能就在淘汰队列里。
- 把任务拆成”子任务”但每个还是巨大（3 个子任务各 100K）——子任务必须真的能装下。
- 把 sub-agent 当贵——和被强制摘要毁掉 plan 比 sub-agent 便宜得多。
FAQ
Q：Claude Code 实际上下文上限是多少？ A：底层模型 200K token 窗口（Opus 4.7 / Sonnet 4.6）。Claude Code 给系统消息和工具定义留了一部分，实际工作预算大约 180K。自动摘要通常在工作预算 90% 左右触发。
Q：摘要一定会丢信息吗？ A：会——设计如此。摘要 = 压缩，压缩有损。具体细节总会丢一部分。修法是把承重细节放到 CLAUDE.md 或者进度文件里、跨摘要存活。
Q：怎么看当前上下文用量？ A：Claude Code 在状态栏 / 底栏显示，看版本。如果你的版本没显示、就盯 “compacting context” 或 “summarizing earlier conversation” 之类指示作为替代。
Q：大任务用 Opus 还是 Sonnet？ A：两者都是 200K 窗口。Opus 在复杂多步 plan 上推理更好；Sonnet 在执行阶段更快更便宜。超大重构用 Opus 出 plan、用 Sonnet 子 agent 执行。
Q：能扩上下文窗口吗？ A：不能——模型定窗口。任务超过窗口的唯一办法是拆分。
相关阅读
标签: #Claude Code #agent #排查