Agent Worktree（Agent 工作树）

Agent 工作树（Agent Worktree） 是在多 AI Agent（智能体）并行工作时，为每个 Agent 分配独立的 Git worktree、分支或临时工作目录，使它们的文件修改在物理工作区层面隔离。

它解决的是并行 Agent 的最低层冲突：两个 Agent 同时改同一个文件、互相覆盖、把彼此的中间状态当作事实基础。隔离工作树后，每个 Agent 都在自己的目录里探索、实现和验证，最终由人或上层编排器合并、取舍。

为什么需要工作树

超过一个 Agent 同时运行时，文件就开始冲突——和两个工程师没有沟通就提交到同一行代码没什么两样。Loop Engineering（循环工程）常常会把任务 fan-out 给多个子智能体：一个修 CI，一个分诊 Issue，一个探索重构方案。如果它们共享同一个工作目录，冲突会变成常态：

文件被另一个 Agent 改到一半，当前 Agent 读到不稳定状态
两个 Agent 分别通过了测试，但合并后失败
一个 Agent 覆盖另一个 Agent 的修改，导致验证结论失效

Git worktree 的解法：同一个 repo 历史，多个独立工作目录，各自签出不同分支。一个 Agent 的编辑在物理文件系统上就触碰不到另一个 Agent 的 checkout。

flowchart LR
    R[("Repo\n（共享历史）")]
    R -->|"main branch"| M["./main\n✓ main"]
    R -->|"feature-a branch"| A["./feature-a\n✓ feature-a"]
    R -->|"feature-b branch"| B["./feature-b\n✓ feature-b"]

工作树把冲突提前隔离，让每个候选方案都有独立的提交历史和验证记录。

工具实现

Codex CLI

Codex 内置 worktree 支持——多个线程可以同时操作同一个 repo 而不互相干扰，无需用户手动配置。

Claude Code

Claude Code 通过两层机制暴露 worktree 隔离：

会话级：-w / --worktree [name] flag 为整个 session 创建一个新的 git worktree，配合 --tmux 可同时开启独立终端面板。

claude --worktree feature-auth

Subagent 级：在 subagent 定义文件（.claude/agents/<name>.md）的 frontmatter 里设置 isolation: worktree，该 subagent 每次运行都会获得一个从默认分支切出的独立 worktree，而非 parent session 的 HEAD。任务结束后若无修改，worktree 自动清理。Claude 在通过 Agent 工具调用 subagent 时也可以显式传入 isolation: "worktree" 参数。

---
name: feature-implementor
description: 并行实现 feature，每次在独立 worktree 里运行
isolation: worktree
---

两者差异：Codex 把 worktree 作为并发线程的默认基础设施；Claude Code 把它作为可选的显式隔离层，可在 session 级或 subagent 级分别声明。

它解决不了什么

Agent Worktree 只解决机械层面的文件冲突，解决不了人工审查的上限。能同时开几个 Agent，不取决于工具能创建几个 worktree，而取决于你能认真审查几个结果。

工作树拿走了机械冲突，但你仍然是上限。并行数应受人工审查、测试耗时、回滚风险约束——否则工作树只是把冲突从文件系统推迟到 PR 队列。