多文件重构做到一半，Claude Code 停止输出、报「You’ve reached your usage limit」。你的活儿一半进度——3 个文件改了，2 个还没。session 死了。明天回来，agent 完全不记得做到哪了。
Claude Code 的 limit 是分层的：每模型 5 小时滚动窗口、跨模型周上限、Sonnet 单独周上限——任意一个撞了都停，rollover 不是立即的。修法不是”等”，而是分清你撞了哪种 limit、捕获状态供 resume、设计未来 task 让 limit 撞了不会一次丢整个 session。
常见原因
按命中率从高到低：
1. 当前模型的 5 小时滚动窗口耗尽
每个模型有自己的 5 小时桶——Opus 有自己的、Sonnet 有自己的。烧光 Opus 不影响 Sonnet，反之亦然。
如何判断：错误信息点名模型、给小时级 reset 时间（如「resets in 3h 24m」）——5 小时窗。
2. 周上限（跨模型）耗尽
Pro 和 Max 套餐有跨模型周 token 上限。即便你 5 小时 Opus 窗口是新的，周上限撞了任何模型都不能用，要等周 reset。
如何判断：错误说「weekly」或给天级 reset。/limits 看周桶接近 100%。
3. Sonnet 周上限耗尽但 Opus 还有
某些套餐有独立 Sonnet 周上限（更小）。Sonnet 先停，切 Opus 还能跑——不知道分模型上限就会迷惑。
如何判断：Sonnet 报错但 /model opus 还能用。
4. 长 session 被算成一个大桶
4 小时 Claude Code session 工具调用密集就能烧掉大半周上限。多次 Read / Grep / Bash 让 token 用量远超 chat turn 数暗示的。
如何判断：session 长且工具调用多，周桶比预期降得快。
5. 多并行 session 共享额度
你开了两个 Claude Code 实例（一个终端、一个 IDE），或后台跑了自动 agent——同账号共享额度，相互竞争。
如何判断：limit 比你活跃用量解释的更快撞——查有没有后台 agent 或忘了的 session。
6. 把 429 / 容量错误误认成额度
「Claude is at capacity, try again later」是服务端临时限流不是你的额度。有时和真额度错误一起显示，被误读。
如何判断：错误说「at capacity」「try again」没数字 reset——是 429，等 1-2 分钟重试，不要重构 session。
最短修复路径
按紧迫度。Step 1（捕状态）在做其他任何事之前必做。
Step 1：立刻停 + 落盘状态
每次重试都烧更多额度。先存状态：
做其他任何事之前：
1. 写 `STATUS.md`：
- 任务：<一句话>
- 已改文件（全路径）
- 还需要改的（全路径）
- 已定的决定（用 REST 不用 GraphQL 等）
- 恢复时的下一步
2. `git add -A && git commit -m "wip: <task>"`Checkpoint commit + STATUS.md 是你的 resume 点。
Step 2：分清撞了哪种 limit
chat 里或 /limits（客户端支持的话）：
- "resets in Xh" → 5 小时窗口。等或切模型。
- "weekly" / "resets in X days" → 周上限。等或切套餐。
- "at capacity" → 临时 429。等 1-2 分钟重试。
- 单模型（Sonnet/Opus）→ 只那个模型的桶，试另一个。不同 limit = 不同恢复路径，不要瞎等。
Step 3：合适的话切模型 tier 恢复
只一个模型窗口出问题：
/model haiku
# 或
/model sonnetHaiku per-token 便宜、额度通常更厚。可以做：
- 任务的低风险部分（移文件、简单 edit）
- 读代码 + 总结
- 出 status report
更强的模型留给下一步非琐碎推理——等它窗口恢复。
Step 4：从 STATUS.md 恢复，不从记忆
准备恢复（新 session）：
读 STATUS.md。它有 prior session 完整状态。
从 "next step" 恢复。不要重做已完成的。
对照 `git log` 确认哪些已 commit。新 session 对 snapshot 是全 context——没有衰减记忆风险。
Step 5：未来 task 切成小 checkpoint
bug 不真在撞 limit，而是大 task 没 checkpoint：
切成 ~30 分钟 agent 时间的单元：
- 单元 1：实现新 schema migration
- 单元 2：写 migration 测试
- 单元 3：更新 consumer 代码
- 单元 4：更新测试每单元后：
- commit
- STATUS.md 加一行更新
- 暂停或继续
单元间撞 limit 没损失。
Step 6：避免同账号并行 session
两个 Claude Code 实例同账号 = 额度竞争。要么：
- 一个实例顺序工作
- 要么不同账号（team plan），各有各的额度
内部用并行 sub-agent（Task tool）的话，它们共享父 session 额度——可以用，但盯紧合计。
预防建议
- 任务切成 ~30 分钟 checkpoint，每个后 commit + STATUS.md
- 反应前分清 5 小时 vs 周 vs 429——不同恢复路径
- 低风险步骤用便宜模型（Haiku），Opus 留给硬推理
- 同账号同套餐永远不并行跑 Claude Code
- 主动看
/limits，撞上限前在干净边界 restart - 关键 deadline 不要按猜的额度安排——Anthropic 上限会变，看官方 limits doc
相关阅读
- Claude Code 卡在循环里
- Claude Code 中途丢了项目上下文
- Claude Code 部分执行后卡住
- Claude Code 新手入门
- Claude Code 工作流
- Claude Code 项目配置
标签: #排查 #Claude Code #排查 #使用上限