Claude Code Worktree 隔离的协作陷阱

首次记录：2026-05-12 来源：B 站直播弹幕插件项目 patch3 / P0.5 / patch4 / patch5 反复遇到状态：规律已确立（5 次实测全部复现），可放心当作默认假设

现象

Claude Code 完成一次 patch 后报告 “git status clean、commit 已推 main”，但跳蛛先生在主仓库目录跑 git status 时看到：

Claude Code（在 Cowork mode 的 harness 里）执行任务时默认启用 git worktree 隔离模式——它在 .claude/worktrees/<branch>/ 创建一个独立工作树工作、commit、push 到 main 分支。

坑在哪：

Claude Code 的完成报告里”git status clean”是真的（worktree 视角），但没有可执行性（主工作树没同步）。

不要要求 Claude Code “不用 worktree”——这是 harness 行为，无法通过 prompt 禁止。

改约定：完成报告 §“已知 leftover” 必须写一行：

请跳蛛先生跑 git checkout HEAD -- . 同步主工作树。

把这个动作从”异常补救”升级为”预期工作流的一部分”。

cd <项目根>
git checkout HEAD -- .   # 把 tracked 文件强制覆盖到 HEAD
git worktree prune       # 清掉过期 worktree 标记

这三行不会动 untracked 文件（如 untracked 的 icon.ico / 临时 PNG 等），安全。

不要相信 Claude Code 完成报告里”git status clean”那一句。验收清单加一条：

cd <主工作树路径> && git status --short

如果有 M 文件 → 不是 Cowork 的活，告诉跳蛛先生跑 §2 那三行就行。

git show HEAD:<关键文件路径> | head -50
git log --oneline -5

确认 commit 在 main 分支顶部、内容是预期的。只要 commit 对，exe 也是好的（Claude Code 在 worktree 里 build 用的是 worktree 的完整文件 → bundle 内容正确）。

试过两次：

patch3 交接文档明令禁止 worktree → Claude Code 还是用了
P0.5 文档加强禁止 + 完工前 verify 主工作树 → Claude Code 自己自检时显示 “git status clean”（基于 worktree），实际主工作树仍坏

根因：worktree 是 Claude Code harness 在 Cowork mode 下的进程隔离机制，不通过 prompt 控制。

与其对抗，不如接受。

这个陷阱还会同时产生：

资源文件路径混乱 —— out/dist/ 是输出目录，Claude Code 在 worktree 里 build 但 output 配置写到主工作树的相对路径（out/dist），所以 exe 实际写到了主工作树，是好的
.claude/worktrees/ 可能因为文件锁删不掉 —— 重启电脑后再删；不删也不影响，git 已经 prune

类型/协作工具链