1. 撞墙那一刻5小时配额到底卡住了什么第一次被 Claude Code 的配额墙拦下来是在一个周四的凌晨两点。当时我正在重构一个老项目的鉴权模块CLI 里已经连续跑了三个多小时的自动化任务——批量改文件、跑测试、根据报错回滚再改。屏幕上突然弹出一行提示大意是当前会话的用量已经触顶需要等待下一个周期窗口恢复。那一瞬间的感觉就像你正开着车在高速上油表突然归零而最近的加油站还在五十公里外。这个“5小时配额墙”是 Claude Code 这类 CLI 编程助手在订阅制下的一种典型限流机制。它不是按天算而是按滚动的时间窗口来算你的调用量。你用得越猛撞墙越快。对于把 Claude Code 当成主力开发工具的人来说这不是一个可以忽略的小问题——它直接决定了你的工作流能不能连续跑下去。我后来花了大概两周时间反复试错总结出了一套“三板斧”式的断点续传方案。核心思路很简单既然配额会断那就让工作流本身具备断点续传的能力。不是去对抗配额而是去适应它。这套方案让我在配额受限的情况下依然能把一个需要十几个小时才能跑完的大型重构任务拆成多个配额窗口内可完成的片段每个片段结束后自动保存状态下一个窗口恢复时从断点继续几乎不需要人工干预。这篇文章就是把这套方案完整拆开讲清楚。适合谁看如果你正在用 Claude Code 或者类似的 CLI 编程助手做实际项目开发尤其是那种需要批量处理、长时间运行的任务那这篇内容应该能帮你省下不少重新来过的时间。如果你只是偶尔用用可能感受不深但了解一下断点续传的设计思路对理解任何长时任务的容错机制都有好处。先说清楚一个前提我这里讲的“断点续传”不是指网络传输层面的断点续传而是任务执行层面的状态保存与恢复。Claude Code 在跑一个工作流时会产生大量的中间状态——改了哪些文件、当前进行到哪一步、哪些测试通过了哪些没通过。如果配额断了这些状态如果没保存下次就得从头再来。而从头再来的代价不仅仅是时间还有配额本身——你会在重复劳动上浪费掉宝贵的调用次数。所以三板斧的第一板斧就是状态外置。第二板斧是任务分片。第三板斧是自动恢复。下面逐个展开。2. 第一板斧状态外置让进度不丢2.1 为什么状态不能留在 Claude Code 的会话里Claude Code 的会话是有生命周期的。当你关闭终端、或者配额耗尽导致会话中断那个会话里的上下文——包括它记住的“我已经改了哪些文件”“当前正在处理哪个模块”——基本上就没了。下次你重新启动它是一张白纸你得重新告诉它项目结构、任务目标、当前进度。这个过程本身就消耗配额而且容易出错。我踩过的坑是这样的有一次我让 Claude Code 批量给一个项目里的所有 API 接口加参数校验。它跑了大概两个小时改了三十多个文件。配额断了之后我重新启动跟它说“继续上次的任务”结果它完全不记得上次改到哪了又从第一个文件开始改。更糟糕的是有些文件已经被改过了它又改了一遍导致代码里出现了重复的校验逻辑。最后我花了比重新写还多的时间去清理。这个教训让我意识到任何跨会话的任务状态必须存在 Claude Code 之外的地方。它可以是文件系统里的一个进度文件可以是 Git 的提交记录也可以是一个简单的 JSON 状态文件。关键是这个状态要能被下一个会话读取并且足够详细让新的会话能准确知道“从哪里继续”。2.2 用 Git 提交作为天然断点最省事的状态外置方案其实是 Git。你不需要额外维护一个状态文件因为 Git 的提交历史本身就是一份完整的进度记录。具体做法是在让 Claude Code 执行批量任务时要求它每完成一个逻辑单元就提交一次。比如批量改接口每改完一个模块就git commit一次提交信息里写清楚这个模块改了什么。这样即使配额断了下次你只需要让 Claude Code 执行git log看看最近提交到哪了然后从下一个模块继续。这里有个细节要注意提交的粒度不能太粗也不能太细。太粗的话断点恢复时你不知道具体断在哪个文件太细的话提交历史会变得非常冗长反而增加恢复时的解析成本。我的经验是以“一个可独立验证的功能单元”为粒度。比如一个 Controller 层的接口改造或者一个 Service 方法的逻辑重写作为一个提交单元比较合适。实际操作时我会在给 Claude Code 的指令里明确写上这样的约束# 在任务指令中加入提交约束 每完成一个模块的修改后执行以下操作 1. 运行该模块相关的单元测试 2. 如果测试通过执行 git add 和 git commit 3. 提交信息格式refactor(auth): 完成 XXX 模块参数校验 4. 如果测试不通过先修复再提交不要跳过这样做的另一个好处是Git 的提交历史本身就是一份可回溯的审计日志。如果某个模块改出了问题你可以精确地回滚到那个提交之前的状态而不需要撤销整个任务。2.3 维护一个轻量级进度文件Git 提交虽然好用但它有一个局限它记录的是“已经完成”的状态不记录“正在进行中”的状态。如果配额是在一个模块改到一半的时候断的Git 里不会有这个半成品的提交下次恢复时你就不知道这个模块是改完了还是改了一半。所以我在 Git 之外还会让 Claude Code 维护一个简单的进度文件比如progress.json。这个文件的结构大概是这样{ task: API参数校验批量改造, total_modules: 12, completed: [user, order, product], in_progress: payment, in_progress_detail: 已修改 PaymentController 的 create 方法待修改 refund 方法, last_updated: 2025-01-15T02:30:00Z }这个文件不需要很复杂关键是要让下一个会话能一眼看懂当前状态。我通常会让 Claude Code 在每次开始一个新模块之前先更新这个文件的in_progress字段在完成一个模块之后把它移到completed列表里。这样即使是在模块中途断掉恢复时也能知道具体断在哪个方法上。注意这个进度文件本身也要纳入 Git 管理但不要和代码提交混在一起。我一般是单独提交提交信息写chore: 更新任务进度这样代码历史和进度历史是分开的互不干扰。2.4 状态外置的边界哪些信息值得存不是所有信息都值得往状态文件里塞。存太多维护成本高而且容易和实际代码状态不一致存太少恢复时信息不够又得重新探索。我的经验是状态文件里只需要存三类信息任务标识、完成边界、当前断点。任务标识就是你在做什么任务一句话说清楚完成边界是哪些单元已经确认完成这个用列表存当前断点是正在进行中的单元以及进行到哪一步了这个用文字描述清楚。至于具体的代码变更内容不需要存在状态文件里因为 Git 已经存了。状态文件的作用是“导航”不是“存档”。它告诉你该往哪走而不是替你记住走过的每一步。3. 第二板斧任务分片把大任务拆成配额窗口能装下的小块3.1 为什么必须分片配额窗口的时间账Claude Code 的配额窗口是滚动计算的具体机制各家可能略有不同但核心逻辑是你在一个时间窗口内的调用量有上限。这个上限对于轻量使用来说绰绰有余但对于批量任务来说很容易触顶。我做过一个粗略的估算。在一个中等规模的 Java 项目里让 Claude Code 批量给 50 个接口加参数校验每个接口平均需要 3 到 5 次交互读文件、改代码、跑测试、修错误总共大概 200 次左右的调用。如果配额窗口内能支撑的调用次数是 100 次左右那这个任务就必须拆成至少两个窗口来完成。如果不拆结果就是跑到一半撞墙然后你面临两个选择要么等下一个窗口从头再来浪费已完成的进度要么手动把剩下的任务拆出来单独跑但手动拆本身就消耗精力。而如果你提前就把它拆成两个窗口能装下的片段每个片段结束后状态是干净的下一个窗口直接接着跑就行。3.2 按模块边界分片而不是按文件数量分片最忌讳的是“按数量平均分”。比如你有 50 个接口简单粗暴地分成 5 片每片 10 个。这种做法的问题在于不同接口的复杂度差异很大。有的接口改起来很简单两三次交互就搞定了有的接口涉及复杂的业务逻辑可能要改十几轮。按数量分会导致有的片很快跑完有的片跑到一半就撞墙。更合理的做法是按模块边界分片。一个模块通常包含一组相关的接口它们共享相似的业务逻辑和代码结构。按模块分片的好处是每个片内的任务同质性高Claude Code 在处理时可以利用上下文复用效率更高。而且模块边界天然就是代码的边界分片后每个片段的改动是内聚的不会出现跨模块的依赖问题。具体操作时我会先让 Claude Code 扫描项目结构列出所有的模块和每个模块下的接口数量然后根据模块的复杂度和预估的交互次数把模块分组到不同的片里。比如分片包含模块预估交互次数预计耗时第1片user, auth40约1.5小时第2片order, product55约2小时第3片payment, refund60约2小时第4片report, export45约1.5小时这个预估不需要很精确大致准确就行。关键是每个片的预估交互次数要留出余量不要贴着配额上限去分。我一般会按配额上限的 70% 来规划留 30% 的缓冲给意外情况——比如某个接口改出问题需要多轮修复或者测试跑失败需要额外排查。3.3 分片之间的依赖处理分片有一个绕不开的问题模块之间可能有依赖。比如 payment 模块依赖 order 模块的接口如果你先改 payment 再改 order可能会出现编译不通过的情况。处理这个问题有两种策略。一种是按依赖顺序分片先改被依赖的模块再改依赖方。这样每个片跑完时项目整体是编译通过的。另一种是在分片时标记依赖关系让 Claude Code 知道哪些模块有跨片依赖在改的时候注意兼容性。我通常用第一种策略因为它更简单而且每个片结束后项目处于可运行状态方便验证。具体做法是让 Claude Code 先分析模块依赖图然后按拓扑排序的结果来分片。如果依赖关系比较复杂就手动调整一下顺序确保被依赖的模块排在前面。实操心得分片的时候尽量让每个片包含的模块数量在 2 到 4 个之间。太少了分片数量多每个片都要重新建立上下文浪费配额太多了单个片太长容易撞墙。2 到 4 个模块是一个比较平衡的范围。3.4 分片后的验证策略每个片跑完之后不能直接进入下一个片必须先验证。验证的内容包括代码能不能编译通过、已有的测试能不能跑通、新改的接口有没有明显的逻辑错误。这个验证步骤本身也消耗配额但它是值得的。因为如果带着错误进入下一个片错误会累积到最后可能整个项目都跑不起来修复的成本远高于每个片结束时及时验证。我一般会让 Claude Code 在每个片结束时执行一个固定的验证脚本大概包括这几步# 分片结束后的验证脚本 mvn clean compile -q # 编译检查 mvn test -pl 本片涉及的模块 # 跑本片模块的测试 git status # 确认没有未提交的变更如果编译或测试失败就让 Claude Code 先修复修复完再提交然后才进入下一个片。这个流程虽然看起来多了一步但实际上避免了大量返工。4. 第三板斧自动恢复让下一个窗口无缝接上4.1 恢复流程的标准化状态外置和任务分片做好了恢复本身其实就很简单了。但简单不等于可以随意恢复流程必须标准化否则每次恢复都要重新想一遍“我该从哪里开始”这本身就消耗精力。我的标准化恢复流程是这样的打开终端进入项目目录启动 Claude Code然后执行一条固定的恢复指令。这条指令的内容是让 Claude Code 读取进度文件确认当前断点然后从断点继续执行。具体来说我会在项目根目录放一个resume.md文件里面写清楚恢复的步骤。每次恢复时我只需要跟 Claude Code 说“按照 resume.md 的流程恢复任务”它就会自动执行。这个文件的内容大概是这样# 任务恢复流程 1. 读取 progress.json确认当前任务和断点 2. 执行 git log --oneline -10查看最近的提交记录 3. 如果 in_progress 字段不为空先完成该模块的剩余工作 4. 如果 in_progress 为空从 completed 列表之后的下一个模块开始 5. 每完成一个模块更新 progress.json 并提交 6. 当前分片的所有模块完成后执行验证脚本 7. 验证通过后更新 progress.json 的分片信息准备进入下一个分片这个文件的好处是它把恢复流程固化下来了。不管是我自己操作还是让 Claude Code 自动执行流程都是一致的不会因为状态不同而出现偏差。4.2 用脚本自动化恢复检查如果每次恢复都要手动敲一堆命令时间长了也会烦。所以我后来写了一个简单的 shell 脚本把恢复前的检查工作自动化了。这个脚本不直接调用 Claude Code而是帮我把恢复所需的信息准备好让我一眼就能看到当前状态。#!/bin/bash # resume-check.sh - 恢复前的状态检查 echo 当前任务状态 cat progress.json | python3 -m json.tool echo echo 最近提交记录 git log --oneline -10 echo echo 工作区状态 git status --short echo echo 当前分支 git branch --show-current这个脚本跑完我大概花十秒钟就能确认任务做到哪了、上次提交是什么、有没有未提交的变更、当前在哪个分支。然后我就可以放心地启动 Claude Code让它从正确的位置继续。4.3 处理恢复时的常见异常恢复过程中最常遇到的异常是“状态不一致”。比如 progress.json 里说某个模块已经完成了但 Git 里没有对应的提交或者 Git 里有提交但 progress.json 没更新。这种不一致通常是因为配额是在更新状态文件之后、提交代码之前断的或者反过来。处理这种不一致的原则是以 Git 为准以代码为准。因为代码是最终产物Git 是代码的权威记录。如果 progress.json 和 Git 不一致先检查代码的实际状态然后以代码为准来修正 progress.json。具体操作时我会让 Claude Code 先执行git diff和git status看看工作区里有没有未提交的变更。如果有说明上次是在改到一半的时候断的需要先决定这些变更是保留还是丢弃。如果变更是有意义的比如已经改了一半的代码就保留并继续如果是无意义的比如调试用的临时改动就丢弃。还有一种异常是“断点漂移”。比如 progress.json 里说当前在处理 payment 模块的 refund 方法但实际上代码里 refund 方法已经改完了只是状态文件没更新。这种情况就需要人工判断一下确认代码确实改完了然后手动更新状态文件跳到下一个模块。注意恢复时不要盲目相信状态文件也不要盲目相信代码。最好的做法是两者对照着看以代码的实际状态为准用状态文件来辅助理解意图。如果实在不确定就让 Claude Code 先跑一遍测试用测试结果来判断当前状态。4.4 恢复后的上下文重建Claude Code 在恢复后需要重新建立对项目的理解。这个过程本身会消耗一些配额但可以通过一些技巧来减少消耗。我的做法是在恢复时给 Claude Code 一个精简的上下文包而不是让它自己去探索整个项目。这个上下文包包括项目的技术栈和目录结构说明、当前任务的描述、当前断点的详细信息、以及相关的代码片段。这些信息大部分可以从 progress.json 和 resume.md 里提取不需要 Claude Code 自己去读大量文件。具体来说我会在恢复指令里加上这样的内容项目背景Spring Boot 3.x MyBatis Plus标准三层架构 当前任务批量给 Controller 层接口添加参数校验 当前断点payment 模块的 refund 方法已改完 create 方法 相关文件PaymentController.java, RefundService.java 约束使用 Jakarta Validation 注解不要引入新依赖这段上下文大概两三百字但能让 Claude Code 快速进入状态避免它花大量配额去重新理解项目结构。实测下来有这段上下文和没有这段上下文恢复后的首次有效交互时间能差一倍以上。5. 三板斧的协同一个完整的实战案例5.1 案例背景50个接口的参数校验改造拿我最近做的一个真实项目来说。这是一个电商后台系统有大概 50 个 REST 接口分布在 8 个模块里。需求是给所有接口的入参加上统一的参数校验包括非空检查、格式校验、范围校验等。这个任务如果让 Claude Code 一口气跑大概需要 4 到 5 个小时中间必然会撞上配额墙。所以我从一开始就按三板斧的思路来设计整个工作流。第一步是状态外置。我在项目根目录创建了progress.json初始化了任务信息和模块列表。同时跟 Claude Code 约定好每完成一个模块就提交一次 Git并更新进度文件。第二步是任务分片。我让 Claude Code 先扫描了所有 Controller列出了 8 个模块和每个模块下的接口数量。然后根据接口数量和预估复杂度把 8 个模块分成了 3 个片分片模块接口数预估交互次数第1片user, auth, product18约70次第2片order, cart, payment20约80次第3片refund, report12约50次第三步是自动恢复。我写好了resume.md把恢复流程固化下来。每次配额断了之后我只需要重新启动 Claude Code让它按resume.md恢复它就能自动从断点继续。5.2 第一次撞墙与恢复实录第一次撞墙发生在第 2 片的 order 模块。当时 Claude Code 正在改 OrderController 的 create 方法屏幕上弹出了配额提示。我看了一下进度文件in_progress字段是orderin_progress_detail是“已改完 query 和 update 方法正在改 create 方法”。因为状态文件是实时更新的所以我很清楚断点在哪。等下一个配额窗口恢复后我启动 Claude Code让它读取progress.json和resume.md然后从 create 方法继续。它先检查了 OrderController 的当前代码确认 query 和 update 方法确实已经改好了然后接着改 create 方法。整个过程大概花了五分钟重新建立上下文然后就开始有效工作了。如果没有状态外置这次恢复可能要花二十分钟以上——我得手动告诉它项目结构、任务目标、已经改了哪些、还剩哪些。而且很容易漏掉一些细节导致重复劳动。5.3 分片边界的验证与调整第 1 片跑完之后我让 Claude Code 执行了验证脚本。编译通过了但测试跑的时候发现 auth 模块有两个测试用例失败了。检查后发现是参数校验的注解加得太严格导致一些原本能通过的测试数据被拦截了。这个问题如果留到所有片都跑完再发现修复成本会高很多。因为后面的片可能会基于错误的校验逻辑继续改错误会累积。而在分片边界及时发现只需要调整 auth 模块的两个注解就行影响范围很小。修复完之后我更新了progress.json把第 1 片标记为完成然后进入第 2 片。整个过程中配额的使用是可控的没有出现因为修复问题而大量消耗配额的情况。5.4 最终效果与配额使用分析整个任务最终用了 4 个配额窗口完成总共大概花了 6 个小时包括等待窗口恢复的时间。如果不用三板斧按照之前的经验大概需要 8 到 10 个小时而且中间会有大量的重复劳动和状态混乱。从配额使用来看三板斧方案的实际有效调用占比大概在 85% 左右也就是说 85% 的配额花在了真正的代码修改上只有 15% 花在了上下文重建和状态恢复上。而不用三板斧的话这个比例大概只有 60% 左右大量的配额浪费在了重复理解和重复修改上。这个差距在大型任务上会非常明显。任务越大状态管理和恢复的成本占比越高三板斧的价值就越大。6. 常见问题与排查技巧实录6.1 状态文件与代码不一致怎么办这是最常见的问题。表现是progress.json里说某个模块完成了但 Git 里没有对应的提交或者代码里还有未完成的改动。排查思路是先看 Git 状态确认工作区有没有未提交的变更。如果有说明上次是在提交之前断的需要先决定这些变更怎么处理。如果变更是有意义的就提交如果是半成品就根据情况决定是继续完成还是回滚。如果 Git 状态是干净的但progress.json说某个模块没完成那就检查代码里那个模块的实际状态。可能是状态文件更新滞后了实际代码已经改完了。这种情况下手动更新状态文件把它标记为完成即可。实操心得为了避免这种不一致我后来养成了一个习惯——每次更新状态文件和提交代码都放在同一个操作序列里先提交代码再更新状态文件或者反过来但两者之间不要插入其他操作。这样即使断了不一致的范围也很小容易修复。6.2 恢复后 Claude Code 理解偏差有时候恢复后Claude Code 对当前状态的理解和你的预期不一致。比如它认为某个模块还没改但实际上已经改完了或者它认为某个约束条件不存在但实际上你在之前的会话里已经强调过了。这种偏差通常是因为恢复时的上下文不够精确。解决办法是在恢复指令里把关键信息再强调一遍尤其是那些容易混淆的点。比如注意user 模块已经完成不要重复修改。 注意参数校验使用 NotNull 和 Size不要用 Valid 以外的注解。 注意当前分支是 feature/param-validation不要切换分支。这些强调看起来啰嗦但能有效减少理解偏差。我一般会在resume.md里维护一个“当前约束”列表每次恢复时都带上确保 Claude Code 不会忘记。6.3 分片过大导致仍然撞墙如果分片的时候预估不准某个片实际需要的交互次数超过了配额窗口的上限那这个片跑到一半还是会撞墙。这时候就需要临时把这个片再拆成更小的子片。处理方法是在撞墙后检查当前片的进度找到已经完成的模块和未完成的模块把未完成的模块单独作为一个新的子片。然后更新progress.json把原来的片标记为“部分完成”新的子片作为下一个执行单元。为了避免这种情况我在分片时会尽量保守。宁可多分几个片也不要让单个片太长。因为多分片的成本只是多几次上下文重建而片太长撞墙的成本是状态混乱和重复劳动。6.4 配额窗口恢复时间不确定不同平台的配额窗口恢复机制不一样有的精确到分钟有的比较模糊。如果恢复时间不确定等待期间可以做些不消耗配额的事情比如整理代码、写文档、或者准备下一个任务的指令。我一般会在撞墙后先跑一下resume-check.sh确认状态是干净的然后把恢复指令准备好放在一个文件里。等配额恢复了直接启动 Claude Code粘贴指令就能快速接上。这样等待的时间不会浪费恢复的效率也更高。6.5 常见问题速查表问题现象可能原因排查方法解决措施恢复后重复修改已完成的模块状态文件未更新或未读取检查 progress.json 的 completed 列表恢复指令中明确列出已完成模块编译不通过分片边界有跨模块依赖检查报错的类和依赖关系调整分片顺序被依赖模块优先测试失败校验逻辑过严或过松查看失败用例的输入数据调整校验注解的参数状态文件与 Git 不一致更新和提交不同步对比 git log 和 progress.json以 Git 为准修正状态文件恢复后上下文理解偏差恢复指令信息不足检查 resume.md 是否完整补充关键约束和背景信息分片仍然撞墙预估交互次数偏低统计实际交互次数拆分子片减小粒度6.6 独家避坑技巧第一个技巧是在任务开始前先跑一个“探针”。拿一个最小的模块让 Claude Code 试跑一下统计实际消耗的交互次数然后根据这个数据来调整分片策略。这个探针本身消耗的配额很少但能大幅提高分片预估的准确性。第二个技巧是把恢复指令写成模板。不要每次恢复都重新想怎么说而是提前写好一个模板把变量部分比如当前断点、当前模块留空恢复时填上就行。这样既快又不容易漏掉关键信息。第三个技巧是用 Git 标签标记分片边界。每个片完成时打一个 Git tag比如slice-1-done。这样恢复时一眼就能看到哪些片已经完成了不需要去解析状态文件。标签比提交信息更醒目也更不容易被忽略。第四个技巧是在状态文件里记录“上次恢复时间”。这个信息看起来没用但实际上能帮你判断配额窗口的恢复节奏。如果你记录了几次恢复时间就能大致摸清配额窗口的规律从而更合理地安排任务节奏。7. 从三板斧延伸出去还能怎么优化三板斧解决的是“配额断了怎么继续”的问题但它不是终点。在实际使用中我还尝试了一些延伸优化有些效果不错有些则比较鸡肋这里一并分享出来。一个比较有效的优化是预判撞墙时间。通过记录每次撞墙前的交互次数和耗时可以大致估算出当前配额窗口还能支撑多久。当剩余时间不多时主动在当前模块完成后暂停而不是等到撞墙再被动中断。主动暂停的好处是状态更干净恢复时不需要处理半成品。另一个优化是把恢复过程也纳入自动化。我试过写一个脚本监控 Claude Code 的输出当检测到配额提示时自动保存状态并退出然后在下一个窗口自动重启并恢复。这个方案技术上可行但实际用起来有点复杂因为配额提示的格式可能变化而且自动重启的时机不好把握。目前我还是手动恢复为主但状态保存的部分已经自动化了。还有一个思路是多工具协同。Claude Code 撞墙的时候可以用其他 CLI 工具做一些不消耗 Claude Code 配额的工作比如用 Git 做代码审查、用本地脚本跑静态分析。这样等待配额恢复的时间也能被利用起来整体效率更高。不过这些延伸优化都有一个前提三板斧本身要跑通。如果状态外置、任务分片、自动恢复这三个基础环节还有问题那延伸优化只会让问题更复杂。所以我的建议是先把三板斧用熟再考虑加东西。我个人在实际操作中的体会是断点续传的核心不是技术而是习惯。状态外置要养成习惯每次改完就更新任务分片要养成习惯动手之前先规划自动恢复要养成习惯恢复流程标准化。这三个习惯养成了配额墙就不再是一个让人头疼的问题而只是一个需要绕一下的障碍。绕过去之后工作流还是那个工作流只是多了一个恢复的步骤而已。 
长河君 · 2026/10/4 6:05:49 · 阅读 1.2k Claude Code配额墙破解：三板斧实现断点续传
1. 撞墙那一刻5小时配额到底卡住了什么第一次被 Claude Code 的配额墙拦下来是在一个周四的凌晨两点。当时我正在重构一个老项目的鉴权模块CLI 里已经连续跑了三个多小时的自动化任务——批量改文件、跑测试、根据报错回滚再改。屏幕上突然弹出一行提示大意是当前会话的用量已经触顶需要等待下一个周期窗口恢复。那一瞬间的感觉就像你正开着车在高速上油表突然归零而最近的加油站还在五十公里外。这个“5小时配额墙”是 Claude Code 这类 CLI 编程助手在订阅制下的一种典型限流机制。它不是按天算而是按滚动的时间窗口来算你的调用量。你用得越猛撞墙越快。对于把 Claude Code 当成主力开发工具的人来说这不是一个可以忽略的小问题——它直接决定了你的工作流能不能连续跑下去。我后来花了大概两周时间反复试错总结出了一套“三板斧”式的断点续传方案。核心思路很简单既然配额会断那就让工作流本身具备断点续传的能力。不是去对抗配额而是去适应它。这套方案让我在配额受限的情况下依然能把一个需要十几个小时才能跑完的大型重构任务拆成多个配额窗口内可完成的片段每个片段结束后自动保存状态下一个窗口恢复时从断点继续几乎不需要人工干预。这篇文章就是把这套方案完整拆开讲清楚。适合谁看如果你正在用 Claude Code 或者类似的 CLI 编程助手做实际项目开发尤其是那种需要批量处理、长时间运行的任务那这篇内容应该能帮你省下不少重新来过的时间。如果你只是偶尔用用可能感受不深但了解一下断点续传的设计思路对理解任何长时任务的容错机制都有好处。先说清楚一个前提我这里讲的“断点续传”不是指网络传输层面的断点续传而是任务执行层面的状态保存与恢复。Claude Code 在跑一个工作流时会产生大量的中间状态——改了哪些文件、当前进行到哪一步、哪些测试通过了哪些没通过。如果配额断了这些状态如果没保存下次就得从头再来。而从头再来的代价不仅仅是时间还有配额本身——你会在重复劳动上浪费掉宝贵的调用次数。所以三板斧的第一板斧就是状态外置。第二板斧是任务分片。第三板斧是自动恢复。下面逐个展开。2. 第一板斧状态外置让进度不丢2.1 为什么状态不能留在 Claude Code 的会话里Claude Code 的会话是有生命周期的。当你关闭终端、或者配额耗尽导致会话中断那个会话里的上下文——包括它记住的“我已经改了哪些文件”“当前正在处理哪个模块”——基本上就没了。下次你重新启动它是一张白纸你得重新告诉它项目结构、任务目标、当前进度。这个过程本身就消耗配额而且容易出错。我踩过的坑是这样的有一次我让 Claude Code 批量给一个项目里的所有 API 接口加参数校验。它跑了大概两个小时改了三十多个文件。配额断了之后我重新启动跟它说“继续上次的任务”结果它完全不记得上次改到哪了又从第一个文件开始改。更糟糕的是有些文件已经被改过了它又改了一遍导致代码里出现了重复的校验逻辑。最后我花了比重新写还多的时间去清理。这个教训让我意识到任何跨会话的任务状态必须存在 Claude Code 之外的地方。它可以是文件系统里的一个进度文件可以是 Git 的提交记录也可以是一个简单的 JSON 状态文件。关键是这个状态要能被下一个会话读取并且足够详细让新的会话能准确知道“从哪里继续”。2.2 用 Git 提交作为天然断点最省事的状态外置方案其实是 Git。你不需要额外维护一个状态文件因为 Git 的提交历史本身就是一份完整的进度记录。具体做法是在让 Claude Code 执行批量任务时要求它每完成一个逻辑单元就提交一次。比如批量改接口每改完一个模块就git commit一次提交信息里写清楚这个模块改了什么。这样即使配额断了下次你只需要让 Claude Code 执行git log看看最近提交到哪了然后从下一个模块继续。这里有个细节要注意提交的粒度不能太粗也不能太细。太粗的话断点恢复时你不知道具体断在哪个文件太细的话提交历史会变得非常冗长反而增加恢复时的解析成本。我的经验是以“一个可独立验证的功能单元”为粒度。比如一个 Controller 层的接口改造或者一个 Service 方法的逻辑重写作为一个提交单元比较合适。实际操作时我会在给 Claude Code 的指令里明确写上这样的约束# 在任务指令中加入提交约束 每完成一个模块的修改后执行以下操作 1. 运行该模块相关的单元测试 2. 如果测试通过执行 git add 和 git commit 3. 提交信息格式refactor(auth): 完成 XXX 模块参数校验 4. 如果测试不通过先修复再提交不要跳过这样做的另一个好处是Git 的提交历史本身就是一份可回溯的审计日志。如果某个模块改出了问题你可以精确地回滚到那个提交之前的状态而不需要撤销整个任务。2.3 维护一个轻量级进度文件Git 提交虽然好用但它有一个局限它记录的是“已经完成”的状态不记录“正在进行中”的状态。如果配额是在一个模块改到一半的时候断的Git 里不会有这个半成品的提交下次恢复时你就不知道这个模块是改完了还是改了一半。所以我在 Git 之外还会让 Claude Code 维护一个简单的进度文件比如progress.json。这个文件的结构大概是这样{ task: API参数校验批量改造, total_modules: 12, completed: [user, order, product], in_progress: payment, in_progress_detail: 已修改 PaymentController 的 create 方法待修改 refund 方法, last_updated: 2025-01-15T02:30:00Z }这个文件不需要很复杂关键是要让下一个会话能一眼看懂当前状态。我通常会让 Claude Code 在每次开始一个新模块之前先更新这个文件的in_progress字段在完成一个模块之后把它移到completed列表里。这样即使是在模块中途断掉恢复时也能知道具体断在哪个方法上。注意这个进度文件本身也要纳入 Git 管理但不要和代码提交混在一起。我一般是单独提交提交信息写chore: 更新任务进度这样代码历史和进度历史是分开的互不干扰。2.4 状态外置的边界哪些信息值得存不是所有信息都值得往状态文件里塞。存太多维护成本高而且容易和实际代码状态不一致存太少恢复时信息不够又得重新探索。我的经验是状态文件里只需要存三类信息任务标识、完成边界、当前断点。任务标识就是你在做什么任务一句话说清楚完成边界是哪些单元已经确认完成这个用列表存当前断点是正在进行中的单元以及进行到哪一步了这个用文字描述清楚。至于具体的代码变更内容不需要存在状态文件里因为 Git 已经存了。状态文件的作用是“导航”不是“存档”。它告诉你该往哪走而不是替你记住走过的每一步。3. 第二板斧任务分片把大任务拆成配额窗口能装下的小块3.1 为什么必须分片配额窗口的时间账Claude Code 的配额窗口是滚动计算的具体机制各家可能略有不同但核心逻辑是你在一个时间窗口内的调用量有上限。这个上限对于轻量使用来说绰绰有余但对于批量任务来说很容易触顶。我做过一个粗略的估算。在一个中等规模的 Java 项目里让 Claude Code 批量给 50 个接口加参数校验每个接口平均需要 3 到 5 次交互读文件、改代码、跑测试、修错误总共大概 200 次左右的调用。如果配额窗口内能支撑的调用次数是 100 次左右那这个任务就必须拆成至少两个窗口来完成。如果不拆结果就是跑到一半撞墙然后你面临两个选择要么等下一个窗口从头再来浪费已完成的进度要么手动把剩下的任务拆出来单独跑但手动拆本身就消耗精力。而如果你提前就把它拆成两个窗口能装下的片段每个片段结束后状态是干净的下一个窗口直接接着跑就行。3.2 按模块边界分片而不是按文件数量分片最忌讳的是“按数量平均分”。比如你有 50 个接口简单粗暴地分成 5 片每片 10 个。这种做法的问题在于不同接口的复杂度差异很大。有的接口改起来很简单两三次交互就搞定了有的接口涉及复杂的业务逻辑可能要改十几轮。按数量分会导致有的片很快跑完有的片跑到一半就撞墙。更合理的做法是按模块边界分片。一个模块通常包含一组相关的接口它们共享相似的业务逻辑和代码结构。按模块分片的好处是每个片内的任务同质性高Claude Code 在处理时可以利用上下文复用效率更高。而且模块边界天然就是代码的边界分片后每个片段的改动是内聚的不会出现跨模块的依赖问题。具体操作时我会先让 Claude Code 扫描项目结构列出所有的模块和每个模块下的接口数量然后根据模块的复杂度和预估的交互次数把模块分组到不同的片里。比如分片包含模块预估交互次数预计耗时第1片user, auth40约1.5小时第2片order, product55约2小时第3片payment, refund60约2小时第4片report, export45约1.5小时这个预估不需要很精确大致准确就行。关键是每个片的预估交互次数要留出余量不要贴着配额上限去分。我一般会按配额上限的 70% 来规划留 30% 的缓冲给意外情况——比如某个接口改出问题需要多轮修复或者测试跑失败需要额外排查。3.3 分片之间的依赖处理分片有一个绕不开的问题模块之间可能有依赖。比如 payment 模块依赖 order 模块的接口如果你先改 payment 再改 order可能会出现编译不通过的情况。处理这个问题有两种策略。一种是按依赖顺序分片先改被依赖的模块再改依赖方。这样每个片跑完时项目整体是编译通过的。另一种是在分片时标记依赖关系让 Claude Code 知道哪些模块有跨片依赖在改的时候注意兼容性。我通常用第一种策略因为它更简单而且每个片结束后项目处于可运行状态方便验证。具体做法是让 Claude Code 先分析模块依赖图然后按拓扑排序的结果来分片。如果依赖关系比较复杂就手动调整一下顺序确保被依赖的模块排在前面。实操心得分片的时候尽量让每个片包含的模块数量在 2 到 4 个之间。太少了分片数量多每个片都要重新建立上下文浪费配额太多了单个片太长容易撞墙。2 到 4 个模块是一个比较平衡的范围。3.4 分片后的验证策略每个片跑完之后不能直接进入下一个片必须先验证。验证的内容包括代码能不能编译通过、已有的测试能不能跑通、新改的接口有没有明显的逻辑错误。这个验证步骤本身也消耗配额但它是值得的。因为如果带着错误进入下一个片错误会累积到最后可能整个项目都跑不起来修复的成本远高于每个片结束时及时验证。我一般会让 Claude Code 在每个片结束时执行一个固定的验证脚本大概包括这几步# 分片结束后的验证脚本 mvn clean compile -q # 编译检查 mvn test -pl 本片涉及的模块 # 跑本片模块的测试 git status # 确认没有未提交的变更如果编译或测试失败就让 Claude Code 先修复修复完再提交然后才进入下一个片。这个流程虽然看起来多了一步但实际上避免了大量返工。4. 第三板斧自动恢复让下一个窗口无缝接上4.1 恢复流程的标准化状态外置和任务分片做好了恢复本身其实就很简单了。但简单不等于可以随意恢复流程必须标准化否则每次恢复都要重新想一遍“我该从哪里开始”这本身就消耗精力。我的标准化恢复流程是这样的打开终端进入项目目录启动 Claude Code然后执行一条固定的恢复指令。这条指令的内容是让 Claude Code 读取进度文件确认当前断点然后从断点继续执行。具体来说我会在项目根目录放一个resume.md文件里面写清楚恢复的步骤。每次恢复时我只需要跟 Claude Code 说“按照 resume.md 的流程恢复任务”它就会自动执行。这个文件的内容大概是这样# 任务恢复流程 1. 读取 progress.json确认当前任务和断点 2. 执行 git log --oneline -10查看最近的提交记录 3. 如果 in_progress 字段不为空先完成该模块的剩余工作 4. 如果 in_progress 为空从 completed 列表之后的下一个模块开始 5. 每完成一个模块更新 progress.json 并提交 6. 当前分片的所有模块完成后执行验证脚本 7. 验证通过后更新 progress.json 的分片信息准备进入下一个分片这个文件的好处是它把恢复流程固化下来了。不管是我自己操作还是让 Claude Code 自动执行流程都是一致的不会因为状态不同而出现偏差。4.2 用脚本自动化恢复检查如果每次恢复都要手动敲一堆命令时间长了也会烦。所以我后来写了一个简单的 shell 脚本把恢复前的检查工作自动化了。这个脚本不直接调用 Claude Code而是帮我把恢复所需的信息准备好让我一眼就能看到当前状态。#!/bin/bash # resume-check.sh - 恢复前的状态检查 echo 当前任务状态 cat progress.json | python3 -m json.tool echo echo 最近提交记录 git log --oneline -10 echo echo 工作区状态 git status --short echo echo 当前分支 git branch --show-current这个脚本跑完我大概花十秒钟就能确认任务做到哪了、上次提交是什么、有没有未提交的变更、当前在哪个分支。然后我就可以放心地启动 Claude Code让它从正确的位置继续。4.3 处理恢复时的常见异常恢复过程中最常遇到的异常是“状态不一致”。比如 progress.json 里说某个模块已经完成了但 Git 里没有对应的提交或者 Git 里有提交但 progress.json 没更新。这种不一致通常是因为配额是在更新状态文件之后、提交代码之前断的或者反过来。处理这种不一致的原则是以 Git 为准以代码为准。因为代码是最终产物Git 是代码的权威记录。如果 progress.json 和 Git 不一致先检查代码的实际状态然后以代码为准来修正 progress.json。具体操作时我会让 Claude Code 先执行git diff和git status看看工作区里有没有未提交的变更。如果有说明上次是在改到一半的时候断的需要先决定这些变更是保留还是丢弃。如果变更是有意义的比如已经改了一半的代码就保留并继续如果是无意义的比如调试用的临时改动就丢弃。还有一种异常是“断点漂移”。比如 progress.json 里说当前在处理 payment 模块的 refund 方法但实际上代码里 refund 方法已经改完了只是状态文件没更新。这种情况就需要人工判断一下确认代码确实改完了然后手动更新状态文件跳到下一个模块。注意恢复时不要盲目相信状态文件也不要盲目相信代码。最好的做法是两者对照着看以代码的实际状态为准用状态文件来辅助理解意图。如果实在不确定就让 Claude Code 先跑一遍测试用测试结果来判断当前状态。4.4 恢复后的上下文重建Claude Code 在恢复后需要重新建立对项目的理解。这个过程本身会消耗一些配额但可以通过一些技巧来减少消耗。我的做法是在恢复时给 Claude Code 一个精简的上下文包而不是让它自己去探索整个项目。这个上下文包包括项目的技术栈和目录结构说明、当前任务的描述、当前断点的详细信息、以及相关的代码片段。这些信息大部分可以从 progress.json 和 resume.md 里提取不需要 Claude Code 自己去读大量文件。具体来说我会在恢复指令里加上这样的内容项目背景Spring Boot 3.x MyBatis Plus标准三层架构 当前任务批量给 Controller 层接口添加参数校验 当前断点payment 模块的 refund 方法已改完 create 方法 相关文件PaymentController.java, RefundService.java 约束使用 Jakarta Validation 注解不要引入新依赖这段上下文大概两三百字但能让 Claude Code 快速进入状态避免它花大量配额去重新理解项目结构。实测下来有这段上下文和没有这段上下文恢复后的首次有效交互时间能差一倍以上。5. 三板斧的协同一个完整的实战案例5.1 案例背景50个接口的参数校验改造拿我最近做的一个真实项目来说。这是一个电商后台系统有大概 50 个 REST 接口分布在 8 个模块里。需求是给所有接口的入参加上统一的参数校验包括非空检查、格式校验、范围校验等。这个任务如果让 Claude Code 一口气跑大概需要 4 到 5 个小时中间必然会撞上配额墙。所以我从一开始就按三板斧的思路来设计整个工作流。第一步是状态外置。我在项目根目录创建了progress.json初始化了任务信息和模块列表。同时跟 Claude Code 约定好每完成一个模块就提交一次 Git并更新进度文件。第二步是任务分片。我让 Claude Code 先扫描了所有 Controller列出了 8 个模块和每个模块下的接口数量。然后根据接口数量和预估复杂度把 8 个模块分成了 3 个片分片模块接口数预估交互次数第1片user, auth, product18约70次第2片order, cart, payment20约80次第3片refund, report12约50次第三步是自动恢复。我写好了resume.md把恢复流程固化下来。每次配额断了之后我只需要重新启动 Claude Code让它按resume.md恢复它就能自动从断点继续。5.2 第一次撞墙与恢复实录第一次撞墙发生在第 2 片的 order 模块。当时 Claude Code 正在改 OrderController 的 create 方法屏幕上弹出了配额提示。我看了一下进度文件in_progress字段是orderin_progress_detail是“已改完 query 和 update 方法正在改 create 方法”。因为状态文件是实时更新的所以我很清楚断点在哪。等下一个配额窗口恢复后我启动 Claude Code让它读取progress.json和resume.md然后从 create 方法继续。它先检查了 OrderController 的当前代码确认 query 和 update 方法确实已经改好了然后接着改 create 方法。整个过程大概花了五分钟重新建立上下文然后就开始有效工作了。如果没有状态外置这次恢复可能要花二十分钟以上——我得手动告诉它项目结构、任务目标、已经改了哪些、还剩哪些。而且很容易漏掉一些细节导致重复劳动。5.3 分片边界的验证与调整第 1 片跑完之后我让 Claude Code 执行了验证脚本。编译通过了但测试跑的时候发现 auth 模块有两个测试用例失败了。检查后发现是参数校验的注解加得太严格导致一些原本能通过的测试数据被拦截了。这个问题如果留到所有片都跑完再发现修复成本会高很多。因为后面的片可能会基于错误的校验逻辑继续改错误会累积。而在分片边界及时发现只需要调整 auth 模块的两个注解就行影响范围很小。修复完之后我更新了progress.json把第 1 片标记为完成然后进入第 2 片。整个过程中配额的使用是可控的没有出现因为修复问题而大量消耗配额的情况。5.4 最终效果与配额使用分析整个任务最终用了 4 个配额窗口完成总共大概花了 6 个小时包括等待窗口恢复的时间。如果不用三板斧按照之前的经验大概需要 8 到 10 个小时而且中间会有大量的重复劳动和状态混乱。从配额使用来看三板斧方案的实际有效调用占比大概在 85% 左右也就是说 85% 的配额花在了真正的代码修改上只有 15% 花在了上下文重建和状态恢复上。而不用三板斧的话这个比例大概只有 60% 左右大量的配额浪费在了重复理解和重复修改上。这个差距在大型任务上会非常明显。任务越大状态管理和恢复的成本占比越高三板斧的价值就越大。6. 常见问题与排查技巧实录6.1 状态文件与代码不一致怎么办这是最常见的问题。表现是progress.json里说某个模块完成了但 Git 里没有对应的提交或者代码里还有未完成的改动。排查思路是先看 Git 状态确认工作区有没有未提交的变更。如果有说明上次是在提交之前断的需要先决定这些变更怎么处理。如果变更是有意义的就提交如果是半成品就根据情况决定是继续完成还是回滚。如果 Git 状态是干净的但progress.json说某个模块没完成那就检查代码里那个模块的实际状态。可能是状态文件更新滞后了实际代码已经改完了。这种情况下手动更新状态文件把它标记为完成即可。实操心得为了避免这种不一致我后来养成了一个习惯——每次更新状态文件和提交代码都放在同一个操作序列里先提交代码再更新状态文件或者反过来但两者之间不要插入其他操作。这样即使断了不一致的范围也很小容易修复。6.2 恢复后 Claude Code 理解偏差有时候恢复后Claude Code 对当前状态的理解和你的预期不一致。比如它认为某个模块还没改但实际上已经改完了或者它认为某个约束条件不存在但实际上你在之前的会话里已经强调过了。这种偏差通常是因为恢复时的上下文不够精确。解决办法是在恢复指令里把关键信息再强调一遍尤其是那些容易混淆的点。比如注意user 模块已经完成不要重复修改。 注意参数校验使用 NotNull 和 Size不要用 Valid 以外的注解。 注意当前分支是 feature/param-validation不要切换分支。这些强调看起来啰嗦但能有效减少理解偏差。我一般会在resume.md里维护一个“当前约束”列表每次恢复时都带上确保 Claude Code 不会忘记。6.3 分片过大导致仍然撞墙如果分片的时候预估不准某个片实际需要的交互次数超过了配额窗口的上限那这个片跑到一半还是会撞墙。这时候就需要临时把这个片再拆成更小的子片。处理方法是在撞墙后检查当前片的进度找到已经完成的模块和未完成的模块把未完成的模块单独作为一个新的子片。然后更新progress.json把原来的片标记为“部分完成”新的子片作为下一个执行单元。为了避免这种情况我在分片时会尽量保守。宁可多分几个片也不要让单个片太长。因为多分片的成本只是多几次上下文重建而片太长撞墙的成本是状态混乱和重复劳动。6.4 配额窗口恢复时间不确定不同平台的配额窗口恢复机制不一样有的精确到分钟有的比较模糊。如果恢复时间不确定等待期间可以做些不消耗配额的事情比如整理代码、写文档、或者准备下一个任务的指令。我一般会在撞墙后先跑一下resume-check.sh确认状态是干净的然后把恢复指令准备好放在一个文件里。等配额恢复了直接启动 Claude Code粘贴指令就能快速接上。这样等待的时间不会浪费恢复的效率也更高。6.5 常见问题速查表问题现象可能原因排查方法解决措施恢复后重复修改已完成的模块状态文件未更新或未读取检查 progress.json 的 completed 列表恢复指令中明确列出已完成模块编译不通过分片边界有跨模块依赖检查报错的类和依赖关系调整分片顺序被依赖模块优先测试失败校验逻辑过严或过松查看失败用例的输入数据调整校验注解的参数状态文件与 Git 不一致更新和提交不同步对比 git log 和 progress.json以 Git 为准修正状态文件恢复后上下文理解偏差恢复指令信息不足检查 resume.md 是否完整补充关键约束和背景信息分片仍然撞墙预估交互次数偏低统计实际交互次数拆分子片减小粒度6.6 独家避坑技巧第一个技巧是在任务开始前先跑一个“探针”。拿一个最小的模块让 Claude Code 试跑一下统计实际消耗的交互次数然后根据这个数据来调整分片策略。这个探针本身消耗的配额很少但能大幅提高分片预估的准确性。第二个技巧是把恢复指令写成模板。不要每次恢复都重新想怎么说而是提前写好一个模板把变量部分比如当前断点、当前模块留空恢复时填上就行。这样既快又不容易漏掉关键信息。第三个技巧是用 Git 标签标记分片边界。每个片完成时打一个 Git tag比如slice-1-done。这样恢复时一眼就能看到哪些片已经完成了不需要去解析状态文件。标签比提交信息更醒目也更不容易被忽略。第四个技巧是在状态文件里记录“上次恢复时间”。这个信息看起来没用但实际上能帮你判断配额窗口的恢复节奏。如果你记录了几次恢复时间就能大致摸清配额窗口的规律从而更合理地安排任务节奏。7. 从三板斧延伸出去还能怎么优化三板斧解决的是“配额断了怎么继续”的问题但它不是终点。在实际使用中我还尝试了一些延伸优化有些效果不错有些则比较鸡肋这里一并分享出来。一个比较有效的优化是预判撞墙时间。通过记录每次撞墙前的交互次数和耗时可以大致估算出当前配额窗口还能支撑多久。当剩余时间不多时主动在当前模块完成后暂停而不是等到撞墙再被动中断。主动暂停的好处是状态更干净恢复时不需要处理半成品。另一个优化是把恢复过程也纳入自动化。我试过写一个脚本监控 Claude Code 的输出当检测到配额提示时自动保存状态并退出然后在下一个窗口自动重启并恢复。这个方案技术上可行但实际用起来有点复杂因为配额提示的格式可能变化而且自动重启的时机不好把握。目前我还是手动恢复为主但状态保存的部分已经自动化了。还有一个思路是多工具协同。Claude Code 撞墙的时候可以用其他 CLI 工具做一些不消耗 Claude Code 配额的工作比如用 Git 做代码审查、用本地脚本跑静态分析。这样等待配额恢复的时间也能被利用起来整体效率更高。不过这些延伸优化都有一个前提三板斧本身要跑通。如果状态外置、任务分片、自动恢复这三个基础环节还有问题那延伸优化只会让问题更复杂。所以我的建议是先把三板斧用熟再考虑加东西。我个人在实际操作中的体会是断点续传的核心不是技术而是习惯。状态外置要养成习惯每次改完就更新任务分片要养成习惯动手之前先规划自动恢复要养成习惯恢复流程标准化。这三个习惯养成了配额墙就不再是一个让人头疼的问题而只是一个需要绕一下的障碍。绕过去之后工作流还是那个工作流只是多了一个恢复的步骤而已。