摘要本文面向经常用 Claude Code 跑长任务的开发者解决“中断后 AI 忘了做到哪一步”的痛点。核心是断点续做套件Git 存代码PROGRESS.md存进度SessionStart/Stop两个 Hook 自动注入与兜底。接入 3 步日常 3 条命令中断后 1 分钟内恢复不重做不重跑。标签Claude Code · AI 编程 · Hooks · Git · 工作流一、问题中断之后AI 把做过的事全忘了我平时用 Claude Code 做的多是周期长、步骤多的任务一个需求要拆成十几步有的测试一跑就是几分钟。这类任务很难在一个会话里跑完中途被打断几乎是必然的。常见的中断有四类中断类型典型表现额度耗尽回复到一半提示usage limit或429网络 / 接口异常ECONNRESET、timeout、529 overloaded电脑卡死或意外关机只能强制重启Claude Code 进程直接消失终端崩溃或会话被关误关窗口、终端无响应、SSH / WSL 断开中断本身不可怕可怕的是恢复的时候#现象后果1找不到之前的对话claude -c接不上只能重新给 AI 讲一遍前情提要2改到一半的代码既没提交也没记录AI 不知道改到哪了经常整段重写3上下文太长被自动压缩细节被“概括”掉已通过的测试被重跑已放弃的方案被再试一次4计划和进度只存在于对话里第二天自己也说不清做到第几步5直接在 main 分支上改半成品污染主分支想回滚找不到干净的节点二、原因进度只存在对话里而对话是“易失”的2.1 根因可以把对话上下文理解成内存容量有限、会被压缩、一断电就没。如果计划、进度、中间结论只放在对话里又没有任何“存盘”动作那么任何一次中断都会让它们丢失或变得不可信代码没存盘没测完就不提交中断时半成品处于游离状态进度没存盘做到第几步、哪些测试过了、哪些方案放弃了只有对话知道恢复没入口新会话启动时AI 不会主动去读任何“存档”。2.2 自带的恢复手段为什么不够用Claude Code 本身有几种恢复方式但都有前提自带功能局限claude -c/claude --resume会话记录按启动目录保存。换了目录、或在 WSL 和 Windows 之间切换就找不到了会话本身损坏或太长也很难用自动压缩compact能让会话继续但细节会被概括掉“哪个测试已通过”这类信息最容易丢会话内回退/rewind解决的是“在当前会话里撤销改动”不解决跨会话的进度延续结论进度必须保存在项目文件夹里而不是依赖“继续上次会话”。三、方案让任务状态“落盘”3.1 设计思路一句话任务状态只以文件和 Git 为准不依赖对话记忆。围绕这一点做了三层保障层级载体作用代码层Git 提交task/*分支每完成一小步就提交每轮回复结束自动做一次wip兜底提交进度层.claude/state/PROGRESS.md记录目标、步骤勾选、当前步、下一步、最近测试、决策与踩坑恢复层SessionStartHook新会话、claude -c、上下文压缩后自动把进度和 Git 状态塞进上下文配合三条斜杠命令形成闭环/plan-task 目标 → 拆成 S1…Sn 小步写 PROGRESS.md切到 task/简称 分支 ↓ 小步推进标记 [~] → 改代码 → 跑测试日志存档 → Git commit Sn → 更新 PROGRESS.md ↓ 每轮回复结束Stop Hook 自动 wip 提交兜底 /checkpoint → 额度快用完 / 要离开时主动存档并写清“下一步” ↓ ……中断…… ↓ /resume-task → 核对 PROGRESS.md / Git / 测试日志从“下一步”继续不重做不重跑3.2 套件结构.claude/ ├── agents/state-auditor.md # 只读核对子代理haiku 模型省额度 ├── commands/ │ ├── plan-task.md # /plan-task 制定计划 │ ├── checkpoint.md # /checkpoint 立即存档 │ └── resume-task.md # /resume-task 断点恢复 ├── hooks/ │ ├── session-start.sh # 启动时注入进度 │ └── stop-checkpoint.sh # 每轮结束自动 wip 提交 ├── resume-kit/ │ ├── install.sh # 安装脚本合并而非覆盖可重复运行 │ ├── hooks.json # 待合并的 hooks 配置 │ └── CLAUDE.snippet.md # 追加到 CLAUDE.md 的续做规则 └── state/ ├── PROGRESS.template.md # 进度文件模板 └── logs/ # 测试日志不提交套件下载在这里放 GitHub 仓库或 CSDN 资源链接3.3 核心实现1Hook 配置SessionStart的matcher同时覆盖startup|resume|compact。其中compact是关键上下文被压缩之后会重新注入一次进度解决“压缩后失忆”。{hooks:{SessionStart:[{matcher:startup|resume|compact,hooks:[{type:command,command:bash \$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh\}]}],Stop:[{hooks:[{type:command,command:bash \$CLAUDE_PROJECT_DIR/.claude/hooks/stop-checkpoint.sh\}]}]}}2session-start.sh把存档喂给新会话SessionStartHook 的标准输出会进入 Claude 的上下文。脚本输出PROGRESS.md前 150 行、当前分支、最近 8 条提交和未提交改动cd$CLAUDE_PROJECT_DIR2/dev/null||exit0P.claude/state/PROGRESS.mdif[-f$P];thenecho 断点续做当前任务进度$Phead-n150$Pelseecho 断点续做尚无 PROGRESS.md。开始新任务请用 /plan-task 目标 fiifgitrev-parse --is-inside-work-tree/dev/null21;thenecho git当前分支$(gitbranch --show-current)gitlog--oneline-8echo--- 未提交改动 ---gitstatus--short|head-n40fi“未提交改动”这一段很重要电脑死机或终端崩溃时Stop Hook 来不及运行但已经写到磁盘上的改动还在新会话一启动就能看到。3stop-checkpoint.sh每轮结束自动兜底提交为安全起见只在task/*分支生效绝不在 main/master 上自动提交有改动才提交。设置环境变量RESUME_KIT_AUTOCOMMIT0可关闭。cd$CLAUDE_PROJECT_DIR2/dev/null||exit0[${RESUME_KIT_AUTOCOMMIT:-1}0]exit0branch$(gitbranch --show-current2/dev/null)case$branchintask/*);;*)exit0;;# 非任务分支直接放行esacif[-n$(gitstatus--porcelain)];thengitadd-Agitcommit-q--no-verify-mwip: auto-checkpoint$(date%m%d-%H%M)fi4CLAUDE.md 续做规则安装脚本会把一段规则追加到项目的CLAUDE.md约束 AI 的工作方式开工前先读PROGRESS.md再看git log --oneline -10、git status、git diff --stat按“小步”工作每步可独立测试约 15 分钟内标记[~]→ 测试 →git commit -m Sn: 说明→ 更新 PROGRESS测试输出用21 | tee .claude/state/logs/$(date %m%d-%H%M).log | tail -n 40存档只读摘要节省上下文遇到wip提交或未提交改动先读 diff在半成品上续写不要从头重写已记为 pass 且相关代码没改过的测试不重跑放弃的方案写进“决策与踩坑”不再尝试不在 main/master 上直接开发任务分支统一叫task/简称。5三条命令命令何时用做什么/plan-task 目标开始新任务拆成 5–15 个可独立测试的小步写 PROGRESS.md切到task/简称分支并提交只做计划等你回复“开始”再执行 S1/checkpoint额度快用完 / 要离开停止新改动提交当前步完成用Sn未完成用wip(Sn)把“下一步”写成可直接执行的指令/resume-task [补充]中断后恢复用 state-auditor 子代理核对 PROGRESS / git / 日志不一致时以 git 为准修正简短汇报后从“下一步”继续# 任务一句话目标 更新YYYY-MM-DD HH:MM | 分支task/简称 | 最近提交hash ## 验收标准 - [ ] 可验证的结果例如pytest 全部通过 / 指标达到 X ## 步骤[x]完成 [~]进行中 [ ]未开始 - [ ] S1 步骤 — 验收怎么算完成 ## 当前步详情只写进行中的那一步 ## 下一步写到可以直接执行的程度 ## 最近测试 ## 决策与踩坑不要重复尝试四、安装4.1 UbuntuWSL一次性准备sudoaptupdatesudoaptinstall-ygitunzipgitconfig--globaluser.name你的名字# 不设置所有自动提交都会失败gitconfig--globaluser.emailyouexample.comgitconfig--globalinit.defaultBranch mainmkdir-p~/toolscp/mnt/c/Users/Windows用户名/Downloads/claude-resume-kit.zip ~/tools/ claude--version# 确认 Claude Code 已安装每个项目接入一次已有代码的项目跳过mkdir直接cd进去已是 git 仓库则跳过第 2 步# 1. 进入项目根目录mkdir-p~/projects/new-projectcd~/projects/new-project# 2. 初始化 gitgitinitgitcommit --allow-empty-minit# 3. 解压套件到项目根目录unzip~/tools/claude-resume-kit.zip# 4. 安装合并 CLAUDE.md、settings.json、.gitignore、.gitattributesbash.claude/resume-kit/install.sh# 5. 提交并启动gitadd-Agitcommit-madd resume kitclaude4.2 WindowsPowerShellClaude Code 在 Windows 上用Git Bash执行 Hook没装 Git for Windows 套件就不会生效。一次性准备# 先到 git-scm.com 安装 Git for Windows默认选项即可然后git--versionTest-PathC:\Program Files\Git\bin\bash.exe# 应返回 Truegit config--global user.name你的名字# 与 WSL 的配置不共享要单独设一次git config--global user.emailyouexample.comgit config--global init.defaultBranch main mkdir D:\tools-ForceCopy-Item$HOME\Downloads\claude-resume-kit.zipD:\tools\ claude--version每个项目接入一次路径含空格时必须加引号# 1. 进入项目根目录mkdirD:\projects\new project;cdD:\projects\new project# 2. 初始化 gitgit init;git commit--allow-empty-minit# 3. 解压不要用资源管理器的“全部解压”它会多套一层文件夹Expand-ArchiveD:\tools\claude-resume-kit.zip-DestinationPath.-Force# 4. 用 Git Bash 运行安装脚本写完整路径不要只敲 bashC:\Program Files\Git\bin\bash.exe.claude/resume-kit/install.sh# 5. 提交并启动LF/CRLF 警告可忽略git add-A;git commit-madd resume kitclaude 安装脚本会向.gitattributes写入*.sh text eollf保证 Hook 脚本始终是 LF 换行。4.3 验证安装进入 Claude Code 后输入/hooks能看到SessionStart和Stop两个 Hook 即安装成功。之后输入/plan-task 任务目标开始。五、日常使用不同中断场景怎么恢复5.1 正常流程场景终端里Claude Code 里开始新任务cd项目目录 →claude/plan-task 目标确认步骤后回复“开始”额度快用完 / 要离开—/usage看额度然后/checkpoint⚠️ 每次启动前务必先cd到项目根目录。Hook 和会话记录都按启动目录识别项目。5.2 按中断类型恢复中断类型恢复做法额度耗尽429/usage limit等额度重置后cd项目目录 →claude→/resume-task。上下文很长时开新会话比claude -c更省额度网络 / 接口异常ECONNRESET、529等先恢复网络换节点或稍等几分钟再claude -c→/resume-task网络仍不稳时见 5.3电脑卡死 / 意外关机重启后claude→/resume-task。最后一轮的 wip 提交可能没来得及做但未提交改动会被 SessionStart Hook 列出来AI 会在半成品上续写终端崩溃 / 窗口被关回到同一目录claude -c接不上就claude→/resume-task换环境WSL ↔ Windows会话记录不互通但 PROGRESS.md 和 git 都在项目里直接claude→/resume-task/resume-task后面可以附加要求例如/resume-task 先修 test_x 再继续 S35.3 网络不稳定时的恢复技巧/resume-task默认会调用子代理做核对网络抖动时子代理容易失败可以这样/resume-task 网络不稳定不要用子代理你自己核对后先汇报等我确认再继续5.4 任务完成后把task/简称分支上零碎的 S1…Sn 和 wip 提交压成一个合回 maingitcheckout maingitmerge--squashtask/简称gitcommit-m任务说明六、常见问题现象原因处理/hooks里看不到 Hook.claude不在项目根目录“全部解压”多套了一层或没运行安装脚本确认.claude/settings.json在项目根目录重新运行安装脚本没有自动 wip 提交只在task/*分支生效回复中途被打断时 Stop Hook 不会运行用/plan-task建分支关键节点手动/checkpointAuthor identity unknown没设置 git 身份WSL 和 Windows 要各设一次执行一次性准备里的git configclaude -c接不上启动目录不同或跨了 WSL / Windows回到同一目录仍不行就claude/resume-taskWindows 里敲bash进了 Ubuntu装了 WSL 后bash指向 WSL用完整路径C:\Program Files\Git\bin\bash.exe$\r: command not found.sh被转成了 CRLF重新解压加-Force并重新运行安装脚本LF will be replaced by CRLF警告Windows 版 Git 默认转换换行忽略即可.sh已被.gitattributes锁定为 LF七、局限与注意事项最后一小段可能会丢Stop Hook 只在一轮回复正常结束时运行。如果中断发生在回复中途最近一次 wip 提交之后的改动不会自动提交——不过只要已写到磁盘新会话会通过git status看到它们。/checkpoint仍然要靠自觉看到额度快用完时手动存档“下一步”会写得比自动兜底清楚得多。注意.gitignore自动提交用的是git add -A接入前确认密钥、大文件、数据集已被忽略。PROGRESS.md 的质量决定恢复质量步骤拆得越小、“下一步”写得越具体恢复时重复的工作就越少。八、总结这套方案的思路很朴素状态外置不信任对话记忆进度写进 PROGRESS.md代码写进 Git小步提交每步可独立测试中断的代价最多是一小步自动兜底StopHook 每轮自动 wip 提交SessionStartHook 在启动 / 恢复 / 压缩后自动注入进度有据恢复/resume-task以 Git 和测试日志为准核对核对不重做、不重跑、不重踩坑。接入只要3 步解压 → 安装 → 提交日常只记3 条命令/plan-task、/checkpoint、/resume-task。如果你也常被 Claude Code 的“中途失忆”困扰欢迎照着搭一套试试也欢迎在评论区分享你的续做经验。参考资料Claude Code 官方文档 · Hooks