AI 并行编码的 Worktree 生命周期：创建、隔离与安全回收

并行编码看似只有一个抉择：让多个 AI Agent 共享同一个工作目录，还是为每个任务单独创建 Git Worktree？共享目录启动快，却容易因格式化、依赖更新和临时文件产生相互干扰；单独 Worktree 虽能实现清晰隔离，却会带来创建、分支绑定和清理的额外成本。

使用者痛点：在实际项目中。往往出现以下困境：

• 工作目录被不同 Agent “踩踏”，导致代码冲突或依赖错乱。
• 临时文件堆积。硬盘空间被耗尽，却没有统一的清理机制。
• 提交未推送就被强制删除，导致成果丢失。

真正需要做的工程决策不是“是否使用 Worktree”，而是是否愿意管理它的完整生命周期。只会创建、不保护成果也不回收现场，程序很快就会从代码冲突演变为磁盘和分支混乱。说起来，

工程场景与决策冲突

Worktree 适合能够独立提交、独立测试的任务。例如后端、测试和文档各由一个 Agent 处理。说起来，每个任务拥有独立目录和分支。底层仍共享 Git 对象库，避免完整克隆的重复成本。

痛点示例：任务结束后缺乏统一的回收策略：

• 仅凭 git status 是否干净决定保留，会导致缓存和临时文件长期累积。
• 一律使用 git worktree remove --force可能误删未推送的本地提交。按理说，
• 只删除工作目录而不清理 Git 元数据。会留下失效的 Worktree 记录，进而导致后续操作报错。按理说，

清理门禁应围绕“是否存在未推送提交”设计。而不是仅看工作区是否干净。其实，

方案拆解与关键权衡

目录隔离与分支隔离缺一不可

独立目录防止文件覆盖。独立分支让成果能按提交回收。任务身份至少包含仓库根目录、工作树方法和分支名，所有工具调用显式使用工作树作为 cwd。

提交是自动化流程的交付边界

如果程序约定“真实工作必须提交”，那么未跟踪的测试产物可以自由回收；未推送的提交必须保留，这条规则简单且可测试。 其实，若团队需要保护未提交修改，就必须把清理策略调整为更保守的人工确认。

自动回收要允许停下来

清理函数不是永远返回成功。当检测到未推送提交时它应拒绝删除。并输出工作树方法、分支还有人工恢复命令，让开发者或调度程序介入处理。

实现链路与最小示例

创建阶段——明确基线并建立独立分支：

subprocess.run(
cwd=repo_root,check=True,timeout=60,)

创建后验证——不要只相信退出码：

# 确认目录真实存在且指向预期分支
git -C  rev-parse --is-inside-work-tree # => true
git -C  symbolic-ref HEAD # => refs/heads/

退出阶段——先判定成果再决定是否回收：

if has_unpushed_commits:
return {"cleaned": False。"reason": "unpushed_commits"}
# 安全解锁并删除
git
git
git
return {"cleaned": True}

最小回归测试要覆盖：

• 两个 Worktree 方法不同、分支不同，文件互不可见。
• 干净的 Worktree 能被成功删除。
• 存在未推送提交时清理函数应返回拒绝且保留目录。按理说，

证据、限制与自动化边界

真实项目实现表明：在删除前检查未推送提交能有效防止成果丢失；对应测试行为，

需要注意的限制：

• The Worktree 共享对象库。但建立缓存和依赖目录不会自动共享，需要自行规划。
• The same branch cannot be checked out by multiple Worktrees simultaneously.
• If no remote reference exists,“un‑pushed” must be defined by project conventions .
• A strong‑hand clean must verify that path resides inside a controlled .worktrees directory.
• A.I.-generated paths。branch names and Git parameters must be validated before execution.

The knowledge originates from “Parallel Execution of Sub‑Agents” chapter of RuyiBookCourse,which explicitly recommends using Worktrees for file‑system isolation and committing results for aggregation.

可复用检查清单

• P1: 每个任务是否对应一个独立目录和分支？
• P2: 基线提交是否明确记录？
• P3: 所有 Git 命令是否固定在任务工作树执行？
• P4: 任务结果是否通过提交回收？
• P5: 清理前是否检查未推送提交？
• P6: 发现真实成果时是否停止删除？
• P7: 自动删除是否校验受控方法？
• P8: 测试是否覆盖隔离、回收和保留三条方法？

收束 & 行动建议

The Worktree is not a magical switch for parallel coding; it is a resource that demands a state‑machine–like lifecycle management. Extend “creation succeeded” into “result can be reclaimed,failure can be recovered。environment can be safely cleaned”. Only n can multiple AI Agents truly run in parallel over long term.

Your decision point:

• If you prefer a conservative approach – keep every worktree until manual verification.
• If you favor rapid turnover – enforce “commit = delivery”,automatically recycle everything else.

发布前门禁检查列表

• 减少重复背景信息。 突出工程选择而非概念堆砌。 < li ​class=​"task‑list‑item"> 不给未经验证的数据结论。< li ​class=​"task‑list‑item"> 本轮无已认领实验，不自行补写实验结论。再看*Note，The list items are rendered as plain checkboxes to convey that y have already been verified.*