worktree

工作树

默认使用 linked-worktree 隔离。 多个会话通常会并行运行。设置约需 30 秒，可避免耗费数小时解决合并问题。

有效工作区定义

• 适用于重要工作或自主工作：通过 Skill(worktree) create 创建的 linked checkout（通常位于 .worktrees/<name>）
• 默认不适用：位于仓库根目录的主 checkout
• 允许的例外情况：交互式、单 Agent 的小改动，可在主 checkout 中进行，但这必须是有意的选择

所有操作都使用 noodle worktree——它会确保 CWD 安全、顺序正确、处理 stash/rebase，并重新安装依赖。

命令

预检

noodle worktree list

显示所有工作树及其合并状态。在会话开始时运行，以发现崩溃会话遗留的过期工作树。

创建

noodle worktree create <name>

在 .worktrees/<name> 创建工作树和分支，创建 .claude/settings.local.json 的符号链接，自动检测包管理器并安装依赖。

在工作树中运行命令

noodle worktree exec <name> <command...>

通过 cmd.Dir 在工作树中运行命令。父 shell 的 CWD 永远不会改变——这是运行构建、测试或任何需要以工作树为 CWD 的工具时的安全方式。

# Examples
noodle worktree exec my-feature go test ./...
noodle worktree exec my-feature go build ./...

对于 Git 操作，也可以使用 git -C，无需 exec：

git -C <project-root>/.worktrees/<name> status
git -C <project-root>/.worktrees/<name> add -A
git -C <project-root>/.worktrees/<name> commit -m "message"

读取和编辑文件时直接使用绝对路径——无需 exec。

合并

noodle worktree merge <name>
noodle worktree merge <name> --into <branch>

单条命令依次执行：CWD 安全检查 -> 暂存工作树产生的杂项改动 -> rebase 到目标分支 -> 合并 -> 移除工作树 -> 删除分支 -> 清理 -> 重新安装依赖。如果 CWD 位于工作树内，或者根目录 checkout 不在目标分支上，则拒绝运行。

默认情况下，目标为集成分支，并从 origin/HEAD 自动检测（检测失败时回退到 main）。使用 --into 可合并到任意分支——运行命令时，根目录 checkout 必须位于该分支上。

如果没有可合并的提交，命令会提前退出，并保留工作树和分支，以便你决定继续工作还是运行清理。

合并操作通过锁文件（.worktrees/.merge-lock）串行执行。如果另一个合并正在进行，命令会以较短的间隔重试（默认超时：5 分钟），之后自动继续。系统会自动检测并清理崩溃进程留下的过期锁。

清理已合并或补丁等效的工作树

noodle worktree prune

自动清理安全的工作树：

• 没有领先于集成分支的提交，或仅包含补丁等效的提交
• 工作树干净（没有未提交的更改）
• 移除已不是真正工作树的过期 .worktrees/<name> 目录

不合并直接清理

noodle worktree cleanup <name>

如果存在尚未合并的提交，会发出警告。使用 --force 丢弃这些提交。

关键安全规则

绝不要 cd 进入 .worktrees/——如果移除工作树时 shell 的 CWD 位于其中，shell 将永久退出（退出代码 1，无法恢复，会话结束）。以下情况均适用：

• 在 Bash 工具调用中直接执行 cd /path/to/worktree && ...
• 任何会将更改 CWD 作为副作用的命令

Bash 工具会维护一个持久 shell——一次调用中的 cd 会影响之后的所有调用。在该路径上执行后续的 rm -rf 或 git worktree remove 会立即终止 shell。

请始终改用以下方式之一：

1. noodle worktree exec <name> <cmd>——设计上可确保 CWD 安全
2. 子 shell：(cd /path && cmd)——子 shell 退出时会恢复 CWD
3. 绝对路径：go build /path/to/pkg/...
4. 工具标志：git -C <path>、go -C <path>

并行 Agent 团队

1. 负责人为每位队友创建一个工作树：noodle worktree create phase-1
2. 以 mode: "acceptEdits" 启动每位队友——工作树是相互隔离的临时空间
3. 每位队友在自己的分支上提交
4. 负责人逐一合并：noodle worktree merge phase-1

子 Agent 层级结构：在自己的工作树（分支 lead-work）中工作的主 Agent 可以启动拥有各自工作树的子 Agent。子 Agent 会合并回主 Agent 的分支，而不是 main：

# Root checkout must be on the target branch
git checkout lead-work
noodle worktree merge sub-work --into lead-work

基础性更改：如果后续阶段需要以第 1 阶段的工作为基础，请先在 main 上完成并提交，然后再创建并行工作树。分支从创建时所在的提交开始。

不适用的情况：顺序任务、只读研究，以及没有并发风险的单 Agent 工作。

约定

• 目录：项目根目录下的 .worktrees/（已加入 gitignore）
• 命名：.worktrees/<branch-name>
• 分支是临时的——完成后合并回 main 并删除
• Brain vault 是共享状态——绝不要为其创建分支。队友应将结果发回给负责人。

过期工作树处理

使用 noodle worktree list 检查状态，然后：

1. 已合并（显示“可安全清理”） -> noodle worktree cleanup <name>
2. 未合并且有提交 -> 向用户报告，由用户决定合并还是丢弃
3. 没有提交 -> 崩溃会话遗留文件 -> noodle worktree cleanup <name>