Claude Code 自动清理 worktree 机制解析与 git worktree lock 防护方案

核心背景与技术痛点

Claude Code 提供 `--worktree` 模式，允许开发者在独立的 Git worktree 中运行会话，避免干扰主工作目录。然而，当使用 `claude --worktree feature-x` 创建会话，进行代码调研、尝试性修改后执行 `/exit` 退出时，一个令人困扰的现象出现了：worktree 及其关联分支被悄然删除，且没有任何确认提示。许多开发者误以为自己的操作“足够干净”就能保留 worktree，结果却丢失了已经建立的上下文环境。

官方文档明确指出这是设计特性：无未提交更改且会话未命名时，worktree 和分支会被自动移除；命名会话则会弹出“Keep/Remove”选择框。但文档并未提供全局禁用此行为的配置选项。这意味着所有“只读不写”或“改完又回退”的临时调研场景，都面临 worktree 被静默清理的风险。用户社区中已出现多个相关 issue（如 #27753、#46444、#58432），均被标记为“预期行为”后关闭，反映出该设计在工程实践中的争议。

架构设计与实现机制

Claude Code 的清理逻辑隐藏在打包后的 JavaScript 源码中。通过反编译可以还原其判定流程：在 `/exit` 时，Claude Code 会依次检查两个 Git 状态指标。首先执行 `git status --porcelain`，检测是否存在未暂存的修改或未追踪文件；其次通过 `git rev-list --count <session-start-HEAD>..HEAD` 计算自会话开始以来的新增提交数。根据这两个指标的组合，行为分为三类：若两者均为零且会话未命名，则静默删除；若均为零但会话已命名，则弹出 Keep/Remove 对话框；若任一指标非零，无论是否命名均弹出对话框。

问题的根源在于第三类场景（零变更、零提交、未命名）——这恰恰是“调研后无改动”或“改动后回退”的典型用例。更关键的是，Claude Code 自身使用了 `git worktree lock` 来管理会话锁。启动会话时，它会以固定格式写入锁原因：`claude session <name> (pid <PID> start <timestamp>)`。退出时，代码通过正则 `/^claude (?:agent|session) .{1,255} \( pid (\d{1,10})(?: start (.{1,255}))? \)$/` 验证锁是否属于自己。若锁原因不匹配该模式（例如自定义文本），则认定“被其他进程锁定”，跳过清理。这是 git 层面提供的安全网——官方文档亦说明“sweep 永远不会释放你自己设置的锁”。

实测性能与工程价值

在测试仓库中，可以精确复现静默删除现象。执行 `claude --worktree wt-clean` 进入空 worktree，立即 `/exit`，终端仅闪过 `Cleaning up worktree (no pending changes)…` 消息，随后 worktree 目录和对应分支便消失。`git worktree list` 显示只剩下主仓库的 worktree。这一过程耗时不足一秒，几乎没有挽回机会。

防护方案基于上述锁机制：在会话运行期间，打开另一个终端（或通过 `!` 在 Claude Code 内部执行 shell 命令），先执行 `git worktree unlock .claude/worktrees/<name>` 解除 Claude Code 自身的锁，再执行 `git worktree lock --reason "pinned by ryan" .claude/worktrees/<name>` 用自定义原因重新锁定。注意必须先 unlock 再 lock，否则因原锁已存在会报错。重新锁定后，`/exit` 时锁原因不匹配正则，Claude Code 会跳过删除操作。验证显示 worktree 依然存在于列表中且状态为 `locked`，后续再次 `claude --worktree wt-lock` 可正常复用。

对于追求自动化的工作流，可以在项目的 `.claude/hooks/` 目录下创建 `SessionStart` hook 脚本（如 `pin-worktree.sh`），利用 `git rev-parse --git-dir` 和 `--git-common-dir` 判断当前是否在 linked worktree 中（排除主仓库），然后执行 unlock 后 lock 操作。这样每次会话启动时自动加锁，退出时自动免删，无需人工干预。

行业启示与未来演进

该问题的本质是 AI 辅助编码工具在设计“自动清理”功能时，对用户心智模型和实际工作流的理解偏差。开发者在使用 `--worktree` 时，往往将 worktree 视为独立的开发容器，即使没有留下 git 痕迹，其承载的调研环境、终端历史、聊天上下文仍有保留价值。Claude Code 以“未改动”为唯一判定标准，忽略了 worktree 作为环境容器的存在意义。

从工程角度看，Claude Code 的锁机制为社区提供了灵活的防御接口。虽然官方未提供配置开关，但通过利用 git 原生能力，用户实现了等价的效果。这启发我们：优秀的工具设计应当在“自动化便利”与“用户掌控感”之间留出自定义空间。未来版本若能引入类似 `--keep-worktree` 的显式标志，或在配置文件中增加 `worktreeCleanupPolicy` 选项，将从根本上解决此痛点。同时，社区提出的 `WorktreeRemove` hook 提案也值得关注，它允许用户在清理前执行自定义检查，进一步增强安全性。

对于所有深度使用 Claude Code 的团队，建议将 worktree 锁定脚本纳入项目初始化模板，作为标准实践。这不仅保护了临时工作区，也避免因意外丢失分支而引发的协作混乱。技术细节上的小改进，往往能带来整个团队开发效率的显著提升。