Claude Code 会持续保存终端会话。一个任务可以跨多次启动继续，也可以从同一个历史节点分支尝试不同方案。文件检查点适合短期撤销，Git 负责长期历史；Git worktree 则让多个 Claude Code 会话拥有相互隔离的工作目录。

本文继续使用虚构的 task-board 项目，假设团队同时进行三项工作：

  1. 为 POST /tasks 增加幂等性；
  2. 修复任务列表的分页缺陷；
  3. 独立审查幂等性实现。

文章将用命名会话、上下文管理、检查点、Git 和 worktree 组织这些工作，并说明子代理、Agent view 与实验性 Agent teams 的适用边界。

0. 会话与并行命令速查

0.1 命名与恢复

1
2
3
4
claude --name task-idempotency
claude --continue
claude --resume
claude --resume task-idempotency

会话内：

1
2
3
4
/rename task-idempotency
/resume
/branch alternative-schema
/export task-idempotency.txt

0.2 管理上下文

1
2
3
4
5
/context
/compact 保留需求、修改文件、测试结果和下一步
/clear
/btw 临时问题
/rewind

0.3 启动隔离工作树

1
2
3
claude --worktree task-idempotency --name task-idempotency
claude --worktree pagination-fix --name pagination-fix
claude --worktree idempotency-review --permission-mode plan

0.4 查看并清理

1
2
3
4
git worktree list
git status --short
git branch --show-current
git worktree remove .claude/worktrees/<name>

在删除工作树前必须确认没有未提交文件或未推送提交。非交互模式不会替用户弹出退出清理对话。

1. 会话的含义

Claude Code CLI 的会话是与项目目录关联、持续写入本地的对话记录。它包含：

  • 用户消息；
  • Claude 回复；
  • 工具调用与结果；
  • 上下文压缩摘要；
  • 检查点；
  • 会话名称、模型等状态。

它不是 Git 分支，也不是工作目录快照。恢复会话会恢复对话状态，但磁盘上的代码仍以当前实际文件为准。

默认转录位于：

1
~/.claude/projects/<project>/<session-id>.jsonl

这是 Claude Code 内部格式，不应依赖其未公开字段编写长期脚本。面向人工阅读使用 /export，面向程序调用使用 claude -p --output-format json 或 Agent SDK。

2. 命名、恢复与切换会话

2.1 为工作流命名

启动时：

1
claude --name task-idempotency

会话中：

1
/rename task-idempotency

命名应表达工作流而不是当天日期：

1
2
3
task-idempotency
pagination-fix
release-2.4-audit

避免：

1
2
3
test
new
session-1

命名会话可直接恢复：

1
claude --resume task-idempotency

2.2 --continue 与 --resume

1
claude --continue

恢复当前目录最近一次会话，适合只有一个活跃任务时使用。

1
claude --resume

打开选择器。常用操作：

按键 作用
↑、↓ 选择会话
Space 预览
Ctrl+R 重命名选中会话
Ctrl+W 扩展到当前仓库所有工作树
Ctrl+A 扩展到本机所有项目
Ctrl+B 按当前 Git 分支筛选
/ 或直接输入 搜索

会话内运行 /resume 可以切换到另一个会话。

2.3 恢复会带回什么

官方当前文档说明，恢复通常包括：

  • 完整对话与工具结果；
  • 原模型，但受命令行覆盖、组织允许列表、模型退役和第三方提供商解析影响；
  • 启动时选择的自定义 Agent；
  • 部分权限模式；
  • 活跃 Goal 和未过期定时任务。

不会自动恢复所有启动参数。例如原会话依赖：

1
2
3
4
5
--mcp-config
--settings
--plugin-dir
--fallback-model
--add-dir

恢复时需要重新传入。普通设置文件会在新进程启动时重新读取。

Plan 与 bypassPermissions 不会因历史会话被静默恢复为原状态；高风险模式必须重新显式启用。

2.4 不要在两个终端同时写同一会话

如果两个终端恢复相同 session ID 且不分支，消息可能交错进入同一转录。需要并行尝试时应分支会话或创建独立会话，而不是同时操作同一个历史记录。

3. 分支会话

3.1 会话内 /branch

1
/branch alternative-idempotency-schema

它复制当前对话到新的 session ID，并切换到新分支会话；原会话保持不变。适合在相同分析基础上尝试不同方案。

会话分支不是 Git 分支。磁盘上的文件不会自动复制。如果两个分支会话仍指向同一工作目录，它们可能编辑同一批文件。

3.2 命令行 fork

1
claude --continue --fork-session

或：

1
claude --resume task-idempotency --fork-session

新进程从历史对话分叉，但使用启动命令所在目录。需要文件隔离时应配合 Git worktree。

3.3 分支与摘要的区别

  • /branch：保留原会话，复制历史后走另一条路线；
  • /rewind 恢复：回退当前会话状态；
  • /rewind 摘要：压缩部分历史，不修改文件；
  • /compact：压缩整个会话历史；
  • /clear：开启干净上下文，旧会话仍保存在历史。

4. 上下文窗口

4.1 查看当前组成

1
/context

主要占用可能来自：

  • 系统提示与内置工具；
  • CLAUDE.md 与 Rules；
  • Skill 描述和已加载正文；
  • MCP 工具；
  • 文件内容；
  • 命令输出；
  • 对话消息；
  • 子代理返回结果。

上下文不是越多越好。超长日志、无关文件和已否决方案会分散注意力。

4.2 /clear

1
/clear

用于无关任务之间。它清空当前上下文，但先前对话仍保存为可恢复会话。会话命名可保留，而自动生成标题可能变化。

示例：

1
2
完成 pagination-fix 后，不要在同一上下文继续设计发布流程。
运行 /clear，或者新建 release-2.4 会话。

4.3 /compact

1
/compact 保留幂等性需求、已确认方案、修改文件、失败测试和下一步

适合一个长期任务内部。自动压缩接近上下文限制时会触发，但主动提供摘要重点更可控。

如果看到自动压缩反复填满上下文的 thrashing 错误，应：

  1. 不再整体读取超大文件；
  2. 只读需要的函数或行范围；
  3. 用 /compact 丢弃大输出；
  4. 把高输出调查交给子代理；
  5. 不需要旧历史时使用 /clear。

4.4 定点摘要

运行 /rewind 后可以：

  • Summarize from here：保留早期消息，把选中点之后压缩；
  • Summarize up to here：压缩早期消息，保留近期细节。

例如，早期需求已稳定、近期调试细节重要时，选择 Summarize up to here；某段旁支调查无价值时，选择 Summarize from here。

4.5 /btw

1
/btw 这个数据库驱动默认事务隔离级别是什么？

答案不会进入主对话历史。需要把答案用于实现时，应将经核实的结论重新写入主对话或规格。

5. 检查点与恢复

5.1 自动跟踪

Claude Code 在每条用户提示前建立检查点，并跟踪 Claude 文件编辑工具产生的变化。当前官方文档说明，一个会话保留最近 100 个检查点的文件快照，并随会话清理策略删除。

打开：

1
/rewind

或在输入为空时双击 Esc。

5.2 可选恢复方式

  • Restore code and conversation；
  • Restore conversation；
  • Restore code；
  • Summarize from here；
  • Summarize up to here。

只恢复对话但保留代码，适合让 Claude 用新思路解释现有差异；只恢复代码但保留对话，适合撤销实现并继续讨论。

5.3 无法保证恢复的变化

检查点不跟踪或不完整跟踪：

  • Bash 命令造成的删除、移动和复制；
  • 外部编辑器或其他进程修改；
  • 其他并发会话修改；
  • 多数子代理产生的文件变化；
  • 符号链接和硬链接目标；
  • Git 历史与远程状态。

例如：

1
2
3
rm file.txt
mv old.txt new.txt
git reset --hard

不能假定 /rewind 可以还原。

5.4 检查点不是版本控制

1
2
检查点：当前会话中的快速撤销
Git：长期、可审查、可协作的历史

在高风险改动前应先建立 Git 基线：

1
2
3
git status --short
git branch --show-current
git log -1 --oneline

不要使用未提交的大量本地修改作为多个 Claude 会话的共同起点。

6. Claude Code 与 Git

6.1 开始任务前

1
2
git status --short --branch
git diff

确认：

  • 当前分支正确；
  • 工作区中哪些变化属于用户已有工作；
  • 没有意外生成物；
  • 可以安全创建工作树或任务分支。

提示 Claude：

1
2
3
先查看 git status 和 diff。
现有未提交修改属于我，不要覆盖、删除或顺手格式化。
如果与本任务文件重叠，先说明冲突。

6.2 实施期间

每个阶段后检查：

1
2
git diff --stat
git diff

让 Claude 总结：

1
2
按文件说明当前差异，区分功能修改、测试、迁移和意外变化。
暂时不要暂存或提交。

6.3 提交前

1
2
git diff --check
git status --short

然后明确授权：

1
2
3
只暂存本任务的四个文件。
展示 staged diff 摘要，运行最终验证后创建提交。
不要 push。

不要把“创建提交”与“推送远程”混为一谈。Push、创建 Pull Request、部署和发布会改变外部状态，应单独明确。

7. 使用 --worktree 隔离并行会话

7.1 为什么需要 worktree

Git worktree 为同一仓库创建独立工作目录和分支，共享 Git 对象和远程信息。多个会话分别在不同目录工作时，不会直接覆盖彼此文件。

1
2
3
4
5
task-board/                         主工作区
└── .claude/worktrees/
    ├── task-idempotency/           独立文件与分支
    ├── pagination-fix/             独立文件与分支
    └── idempotency-review/         独立文件与分支

7.2 创建

从仓库根目录：

1
claude --worktree task-idempotency --name task-idempotency

另一个终端：

1
claude --worktree pagination-fix --name pagination-fix

默认路径：

1
.claude/worktrees/<name>/

默认分支：

1
worktree-<name>

建议将目录加入 .gitignore：

1
.claude/worktrees/

交互式 --worktree 要求仓库已通过工作区信任检查。不要使用 -p 跳过信任后在陌生仓库直接运行高权限任务。

7.3 新工作树需要初始化环境

工作树只检出被跟踪文件，不自动包含：

  • node_modules；
  • .env；
  • 本地证书；
  • 未跟踪测试数据；
  • 构建缓存。

在工作树中执行：

1
2
npm ci
npm test

具体命令以项目为准。

7.4 .worktreeinclude

项目根可创建 .worktreeinclude，使用 gitignore 语法复制“同时被 Git 忽略”的文件：

1
2
.env.test
config/local-test.json

只有匹配且被忽略的文件才会复制。不要把生产凭据或长期 Secret 复制到每个代理工作树。更安全的做法是提供最小权限测试配置、临时凭据或 Secret 管理器注入。

7.5 基准分支

默认 worktree.baseRef 为 "fresh"，从远程默认分支建立干净工作树。需要基于当前本地 HEAD 时：

1
2
3
4
5
{
  "worktree": {
    "baseRef": "head"
  }
}
  • fresh：适合独立任务和从最新主线开始；
  • head：适合让隔离子代理继续处理当前未推送提交。

该设置不能直接写任意分支名。需要特定已有分支时，使用 Git 原生命令创建工作树。

7.6 从 Pull Request 创建

1
claude --worktree "#1234"

Shell 中应引用 #1234，避免把 # 当作注释。也可使用完整 GitHub Pull Request URL。

7.7 退出与清理

交互会话退出时，Claude Code 会检查工作树：

  • 干净且无需要保留工作时可以自动清理；
  • 有未提交文件、新提交或命名会话时会提示保留或删除。

删除会丢失其中未保存工作。执行前检查：

1
2
git -C .claude/worktrees/task-idempotency status --short
git -C .claude/worktrees/task-idempotency log --oneline --decorate -5

非交互 -p 没有清理对话，需要手动：

1
2
git worktree list
git worktree remove .claude/worktrees/task-idempotency

不要对有未提交工作或未合并提交的目录使用强制删除。

8. 手动管理 Git worktree

需要自定义目录或已有分支时：

1
2
3
4
5
6
7
# 新分支
git worktree add ../task-board-idempotency -b feature/task-idempotency

# 已有分支
git worktree add ../task-board-pagination fix/pagination

git worktree list

进入后启动：

1
2
cd ../task-board-idempotency
claude --name task-idempotency

完成并确认可删除：

1
git worktree remove ../task-board-idempotency

9. 并行方式的选择

方式 谁协调 上下文 文件隔离 适用场景
后台 Bash 用户 无新代理 无 长时间构建或服务器
子代理 主会话 独立，返回摘要 可选 worktree 调查、审查、单项任务
多个手动 CLI + worktree 用户 每个会话独立 是 独立功能、实验
Agent view 用户派发并监控 每个后台会话独立 自动 worktree 多个独立任务
Agent teams Claude Lead 每个 teammate 独立 默认无 需要互相通信的复杂协作
/batch Claude Skill 多个子代理 worktree 5—30 个可拆分任务

并行会增加 token、API 限额、机器资源和协调成本。只有可独立执行的任务才适合并行。

10. 子代理与工作树

子代理适合读取大量文件后只返回结论。要求隔离修改：

1
2
3
使用 worktree 隔离的子代理修复分页测试。
完成后返回分支、修改文件、提交和测试结果。
不要修改主工作区。

自定义 Agent 可固定：

1
2
3
4
5
6
7
---
name: refactorer
description: 在隔离工作树中完成机械重构
isolation: worktree
---

执行指定重构，运行测试并报告结果。

第五篇将展开子代理配置。

11. Agent view

Agent view 是官方当前的 Research preview，用于从一个终端界面派发和监控后台会话：

1
claude agents

也可以使用：

1
claude --background "修复分页缺陷并运行测试"

后台会话通常使用独立工作树，适合用户自己协调多个互不依赖任务。检查具体子命令和可用性：

1
claude agents --help

Research preview 的命令和行为可能快速变化，自动化脚本不应在未锁定版本和回归测试的情况下依赖其界面细节。

12. Agent teams

12.1 实验性状态

Agent teams 当前是实验功能，默认关闭。启用：

1
2
3
4
5
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启用后重新启动会话。

12.2 适用场景

  • 多角度代码审查；
  • 多个可独立模块；
  • 使用竞争假设调查故障；
  • 前端、后端和测试分别拥有清晰文件边界；
  • Teammate 之间需要直接交换结论。

不适合：

  • 严格顺序任务；
  • 多人修改同一文件；
  • 很小的改动；
  • 预算受限的常规任务；
  • 需要可靠恢复整个团队的长期流程。

12.3 启动示例

1
2
3
4
5
6
7
8
为幂等性功能创建一个 Agent team：
- security-reviewer：检查请求头信任边界和数据泄露；
- concurrency-reviewer：检查并发、事务和唯一约束；
- test-reviewer：检查测试矩阵和稳定性。

三者只读审查，不修改文件。
每人报告可复现缺陷，互相挑战结论。
全部完成后由 Lead 合并、去重并按严重度输出。

官方建议多数场景从 3—5 个 Teammate 开始。数量越多，token 和协调成本越高。

12.4 文件冲突

Agent teams 默认不为每个 Teammate 创建隔离工作树。若允许修改，必须按文件或模块划分所有权：

1
2
3
teammate-a：只修改 src/routes/ 与对应测试
teammate-b：只修改 src/repositories/ 与迁移
teammate-c：只读审查，不修改

无法清晰分区时，使用单会话、子代理 worktree 或手动多个 worktree。

12.5 权限与限制

  • Teammate 初始继承 Lead 的权限设置；
  • Teammate 不能代表用户批准权限；
  • 权限提示会回到 Lead；
  • 每个 Teammate 有独立上下文，不继承 Lead 完整历史；
  • in-process Teammate 当前无法可靠随 /resume 恢复；
  • 一个会话只有一个 Team；
  • 不支持嵌套 Team；
  • Lead 身份固定；
  • 实验性任务状态和关闭行为可能存在限制。

因此，Agent teams 更适合可重新运行的研究与审查，不应把未提交的重要唯一状态只保存在 Teammate 对话中。

13. 并行质量策略

13.1 Writer / Reviewer

工作树 A：

1
按规格实现 Idempotency-Key，并完成测试。

工作树 B：

1
2
只读审查 feature/task-idempotency 相对 main 的差异。
根据 SPEC.md 检查正确性、并发和兼容性。

Reviewer 不继承 Writer 的完整推理，只根据规格和结果判断，可以降低确认偏差。

13.2 测试与实现分离

  • 会话 A 编写能表达需求的失败测试；
  • 会话 B 在另一工作树实现；
  • 人工审查测试是否只验证外部行为；
  • 合并后运行完整检查。

13.3 竞争假设

故障原因不明时：

1
2
3
4
5
6
7
建立三个只读调查：
1. 数据库事务假设；
2. HTTP 重试假设；
3. 客户端重复提交假设。

每个调查必须提供能证伪自身假设的证据。
最后比较结果，不要在第一个看似合理的原因处停止。

14. 故障恢复

14.1 命令卡住

1
Ctrl+C

必要时关闭终端，随后：

1
claude --resume

会话已持续保存，通常无需重新描述全部背景。

14.2 工作树环境缺失

1
2
3
cd .claude/worktrees/<name>
npm ci
npm test

不要从主工作区直接引用可变的 node_modules 或构建结果来掩盖初始化问题。

14.3 会话指向已删除工作树

恢复时如果原工作树不存在，Claude Code 可能回到启动目录。第一步检查：

1
2
pwd
git status --short --branch

确认目录和分支后再继续编辑。

14.4 并行修改冲突

停止相关会话，确定每个会话的文件和提交：

1
2
git worktree list
git log --oneline --all --decorate --graph

由用户选择合并顺序。不要让多个 Agent 在同一文件上继续“自动解决”而不先确定哪一版是权威来源。

15. 推荐日常流程

1
2
3
4
5
6
7
8
9
10
11
1. git status 确认基线
2. 为任务创建命名会话
3. 复杂任务使用 Plan
4. 并行编辑使用 worktree
5. 调查使用子代理
6. 每阶段运行最小验证
7. /context 监控上下文
8. 无关任务使用 /clear
9. git diff 审查实际文件
10. 明确授权后提交、Push 或创建 PR
11. 确认工作树无重要工作后清理

下一篇将介绍 Claude Code 的扩展体系：把重复提示做成 Skill，把高输出工作交给自定义子代理，用 Hook 确定性执行检查，通过 MCP 连接外部工具，并使用插件打包和分发这些能力。

参考资料