Claude Code SDK #28：Sessions 全解——--continue × --resume × branch，把长任务从一次对话变成可恢复工作流

很多人把 Claude Code 的 session 当成「聊天记录」。这会低估它。

在官方定义里，session 是绑定到项目目录的一段已保存对话；Claude Code 会在本地持续保存它，所以你可以退出后回来、给它命名、从中间分叉，甚至把代码和对话一起回滚到某个早先状态。1

对开发者来说，这不是一个 UI 小功能，而是把一次性问答改造成可恢复工作流的底座。今天拆 Sessions。

1. 先记住一句话：session 是「项目目录里的工作上下文」

Claude Code 的 session 不是全局聊天列表。官方文档说得很直接：session 与项目目录绑定，picker 默认展示当前 worktree 的交互式 session，以及曾用 /add-dir 加入当前目录的 session。1

这解释了一个常见误会：你拿到一个 session ID，在另一个目录里执行 resume，可能会看到 No conversation found with session ID:。原因不是 ID 失效，而是 session ID 查找范围被限定在当前项目目录及其 git worktrees。1

Claude Code session 与项目目录、transcript、resume、fork 的关系示意图 — 根据官方 Sessions 文档整理：session 围绕项目目录保存，并可通过 picker、命名和 branch 重新进入。1

如果你每天都在同一个仓库里做功能开发，这个设计很顺手：Claude Code 不需要你重新解释项目背景，也不会把另一个仓库的上下文混进来。反过来，如果你在 monorepo、worktree、临时目录之间来回切，目录边界就要想清楚。

2. resume 不是一个命令，而是一组入口

官方文档把恢复 session 的入口列成了几类：claude --continue 恢复当前目录最近一次 session，claude --resume 打开 picker 或按 ID / 名称恢复，claude --from-pr 恢复与某个 PR 关联的 session，交互式会话里还可以用 /resume 切换对话。1

场景	推荐入口	适合什么时候用
刚才中断，想接着干	`claude --continue` / `claude -c`	当前目录最近一次对话就是你要找的那条；CLI reference 也把 `-c` 解释为继续当前目录最近对话。2
要找某个历史任务	`claude --resume` / `claude -r`	需要按 ID、名称或 picker 选择；CLI reference 说明 `--resume, -r` 可以按 session ID 或名称恢复，也可以打开交互式选择器。2
PR 对应的修复没做完	`claude --from-pr`	resume 与 pull request 关联的 session，参数可以是 PR number 或 GitHub / GitLab / Bitbucket URL。2
已在会话里，想换另一条线	`/resume`	在当前 Claude Code 会话内切换到另一个 conversation。1

最常用的组合大概是这样：

Claude Code resume 命令选择卡 — 根据官方 CLI reference 和 Sessions 文档整理：先从当前目录最近 session 开始，找不到再进入 picker 或按名称恢复；高风险尝试前使用 fork。2

# 继续当前目录最近一次对话
claude --continue

# 打开 session picker
claude --resume

# 按名称恢复
claude --resume auth-refactor

这里有个细节：claude -p 或 Agent SDK 创建的 session 不会出现在 session picker 里，但仍可以用 session ID 恢复，前提是你在它启动时所在的目录执行 resume。1

这对自动化脚本很关键。脚本里跑出来的 session，不一定会像交互式任务一样出现在 picker；你需要保存 ID，并记录它属于哪个项目目录。

3. 给 session 命名，比事后翻列表靠谱

官方建议给 session 起可描述的名字，原因很现实：你并行做多个任务时，picker 里只靠第一句 prompt 或自动摘要很难找。启动时可以用 claude -n auth-refactor 命名；会话中可以用 /rename auth-refactor；在 session picker 里也可以高亮后按 Ctrl+R 重命名。1

我建议把名字写成「模块 + 动作」，少用抽象词：

claude -n auth-refresh-token
claude -n billing-webhook-tests
claude -n sdk-session-docs-digest

这样做的收益很朴素：几天后回来，你知道哪条 session 是在改 refresh token，哪条是在补 webhook 测试。官方还提到，plan mode 接受计划时会根据 plan 内容命名 session，除非你已经手动设置了名字。1

4. session picker 是一个「工作区切换器」

/resume 或 claude --resume 不只是列出历史对话。picker 里可以用上下箭头移动、左右箭头展开或折叠分组、Space 预览内容、/ 进入搜索、Ctrl+B 过滤当前 git branch。1

两个快捷键尤其值得记：Ctrl+W 会把范围扩到当前仓库的所有 worktree；Ctrl+A 会扩到这台机器上的所有项目。选择同仓库其他 worktree 的 session 时，Claude Code 会在原地恢复；选择无关项目的 session 时，它会把 cd 和 resume 命令复制到剪贴板。1

这说明 picker 的模型不是「所有聊天全局平铺」，而是先尊重项目边界，再允许你主动放宽范围。对 monorepo 用户，这个差别很大。

5. branch：试另一条路，但别污染原 session

从 session 里执行 /branch try-streaming-approach，会复制当前对话并切到新分支，原 session 保持不变。命令行里也可以把 --continue 或 --resume 与 --fork-session 组合使用。1

# 从最近一次会话 fork 一条新线
claude --continue --fork-session

# 从指定会话 fork
claude --resume auth-refactor --fork-session

这适合三类任务：

你想尝试另一种实现，但还不确定要不要保留。
你要让 Claude Code 做一轮大改，担心讨论路径被带偏。
你准备把同一个问题拆成两个方向，让两个 session 各自推进。

官方特别提醒：branch 之后，原 session 不会改变；如果两个终端 resume 同一个 session 而不 fork，消息会交织到同一份 transcript 里。1

这句话值得写进团队规范：多人或多终端接同一条线之前，先判断要 resume 还是 fork。想共享同一条历史就 resume；想保留原路径就 fork。

6. /clear、/compact、/context：session 内部的上下文管理

session 还解决另一个问题：长会话撑爆上下文怎么办。

官方 Sessions 文档列了三个命令：/clear 用空上下文重新开始，但之前对话仍保存且可恢复；/compact [instructions] 用摘要替换历史；/context 查看当前上下文消耗。1

我的使用顺序通常是：

先跑 /context，确认上下文到底被哪些内容吃掉。
如果早期讨论已经过时，用 /compact，并给一句明确指令，比如「保留已确认的 API 决策和未完成 TODO」。
如果你要换任务，不要硬压缩，直接 /clear 或新开一条 session。

这里不要把 /compact 当万能清洁剂。它会保留摘要，不会保留每个细节；如果你后面要追查某个工具输出或一段报错原文，最好先 /export 保存。

7. transcript：可恢复性的真正落点在本地文件

Claude Code 的 session 会作为本地 transcript 文件保存；/export 可以把当前对话复制到剪贴板或写成普通文本文件。官方说明 transcript 以 JSONL 形式存放在 ~/.claude/projects/.../*.jsonl 一类路径下，项目路径会参与生成存储位置。1

文档还提到两个配置边界：如果要把 session 存到 ~/.claude 之外，可以设置 CLAUDE_CONFIG_DIR；这些本地文件默认 30 天后清理，也可以通过 cleanupPeriodDays 调整。1

如果你把 Claude Code 用在 CI 或自动化脚本里，这里有两条实践建议：

需要审计的任务，结束时显式 /export，不要只依赖默认清理周期。
不想留下 transcript 的非交互任务，使用 --no-session-persistence；CLI reference 说明它会禁用 session 持久化，print mode 下可用。2

8. session 和 checkpoint 的边界：一个管对话，一个管回滚点

Sessions 文档说，如果要在单个 session 内做基于 checkpoint 的回退，应该看 Checkpointing；branch 则适合保留原 session、另开一条尝试路径。1

Checkpointing 文档给出的核心机制是：Claude Code 会在工作时自动跟踪 Claude 通过文件编辑工具做出的改动，并在每个用户 prompt 前创建 checkpoint；这些 checkpoint 会跨 session 保留，并随 session 一起按默认 30 天周期清理。3

Claude Code checkpoint 的代码、对话和摘要动作矩阵 — 根据官方 Checkpointing 文档整理：restore 会回退状态，summarize 会压缩对话片段。3

/rewind 或空输入时双击 Esc 会打开 rewind 菜单；如果输入框里已有文字，双击 Esc 会先清空输入，而不是打开菜单。3

rewind 菜单里的动作要分清：Restore code and conversation 同时回退代码和对话；Restore conversation 只回退对话；Restore code 只回退文件；Summarize from here 和 Summarize up to here 则是压缩对话，不改变磁盘文件。3

最容易踩坑的是 Bash。Checkpointing 明确说，它不跟踪 Bash 命令造成的文件修改，比如 rm file.txt、mv old.txt new.txt、cp source.txt dest.txt 这类变化无法通过 rewind 撤销；它只跟踪 Claude 文件编辑工具做出的直接编辑。3

所以边界可以这样记：

你要做什么	用什么	为什么
今天继续昨天那条开发线	session resume	session 保存对话并绑定项目目录，可通过 `--continue`、`--resume` 或 `/resume` 回来。1
想试一条新实现路线	branch / fork-session	branch 会复制当前对话并切到新分支，原 session 不变。1
改坏了文件，想回到某个 prompt 前	checkpoint / rewind	checkpoint 在每个用户 prompt 前创建，可选择恢复代码、对话或两者。3
想要长期版本历史	Git	官方文档说 checkpoint 是 session 级快速恢复，不能替代 Git 这样的长期版本控制。3

9. 一套可以直接照做的 Sessions 使用顺序

如果你准备把 Claude Code 用成日常开发工具，而不是偶尔问两句，我建议按这个顺序配置习惯：

每个重要任务启动时命名：claude -n module-action。
每次回来先用 claude --continue，找不到再用 claude --resume 打 picker。
进入 picker 后，优先用搜索和 Ctrl+B 缩小到当前 branch；跨 worktree 再按 Ctrl+W。
准备走高风险路线前先 fork：claude --continue --fork-session。
大改之前确认 Git 工作区干净；checkpoint 只能帮你处理 Claude 编辑工具做的改动，Bash 改出来的文件不在它的撤销范围内。3
长任务结束前 /export 一份文本，尤其是 CI、代码审计、迁移方案这类需要复盘的工作。

Sessions 的价值不在于「能不能找回聊天记录」。真正的价值是：你可以把 Claude Code 的一次交互拆成多天、多分支、可恢复、可审计的开发流程。做到这一步，它才更像一个能长期协作的 coding agent，而不是一个开在终端里的问答框。