Git Worktree 多 Agent 协作与多项目切换指南

适用范围：

通用 Git 仓库中的并行开发

NoxInfluencer drafts/ 这类 PM + AI 协作工作区

本文是教程，不会自动改动你的工作区。文中的命令均为示例，请在真正执行前结合当前仓库状态确认。

1. 先说结论

如果你的工作方式里同时存在以下任意两项，git worktree 基本就是推荐解：

多个 agent 同时干活
多个功能并行推进
多个原型或研究方向来回切换
主目录已经有未提交改动，不想反复 checkout
希望保留多个任务的独立运行现场

一句话理解：

git worktree = 给同一个 Git 仓库挂出多个独立工作目录，每个目录固定对应一个 branch。

它解决的不是“多仓库”问题，而是“同一个仓库里如何安全并行工作”的问题。

2. 为什么不用传统的 `git checkout`

传统工作方式只有一个目录，切任务通常这样做：

在当前目录做任务 A
git checkout feature/b
开始做任务 B
再切回任务 A

这种方式在单人、单任务、目录干净时还可以忍受，但一旦进入 AI 协作或多项目并行，就会出现几个典型问题：

未提交改动阻止切分支
一个 agent 切走了另一个 agent 的目录状态
不同任务的临时文件、依赖和构建结果混在一起
主目录越来越脏，最后谁都不敢切 branch

worktree 的核心优势是把“切 branch”变成“切目录”：

以后切任务不是：

git checkout feature/x

而是：

cd .worktrees/feature-x

这就是它在多 agent 场景下特别稳的原因。

3. 核心概念：仓库、branch、worktree 到底是什么关系

建议把这三个概念分开理解：

Repository / 仓库：提交历史和对象数据库
Branch / 分支：仓库中的一条开发线
Worktree / 工作树：某个分支在磁盘上的一个独立工作目录

可以想象成下面这样：

一个仓库 drafts
├── 主工作区 drafts/                 -> main
├── worktree A .worktrees/demo-a/    -> feat/demo-a
└── worktree B .worktrees/research-b/ -> research/b

重点：

一个仓库可以有多个 worktree
每个 worktree 通常对应一个 branch
同一个 branch 不能同时被两个 worktree 检出

最后这一条非常重要。Git 故意限制它，是为了避免你在两个目录里同时修改同一条分支，造成混乱。

4. `git worktree` 适合什么，不适合什么

适合

同一仓库里的多个并行任务
多 agent 协作
功能开发、文档编写、原型实验并行
需要长时间保留多个上下文
想把主目录留作统筹和 review 入口

不适合

两个完全不同的 Git 仓库
只是偶尔切一次分支，且目录长期干净
任务非常短、没有并行需求
团队没有清晰的目录/分支命名规范

如果是两个完全不同的仓库，例如：

drafts/
pm-dashboard/

那不是 worktree 替代关系。正确做法是：

每个仓库自己有自己的主目录
每个仓库内部再独立使用 worktree

5. 最小心智模型

你只要先记住下面四条，就已经够开始用了：

一个 agent 一个 worktree
一个任务一个 branch
主目录只做统筹，不做具体开发
切换任务靠 cd，不是频繁 checkout

如果你把这四条长期执行下来，协作稳定性会明显提高。

6. 基础命令教程

下面是最常用的一组命令。

6.1 查看当前有哪些 worktree

git worktree list

示例输出：

/Users/you/project                    63b44ca [main]
/Users/you/project/.worktrees/feat-a  91e2fd1 [feat/a]
/Users/you/project/.worktrees/feat-b  33bc0a7 [feat/b]

含义：

第一行是主工作区
后面每一行是一个额外 worktree
方括号里是该目录当前检出的 branch

6.2 新建一个 worktree，并同时创建新分支

git worktree add .worktrees/demo-builder -b feat/demo-builder

这条命令一次做了三件事：

创建目录 .worktrees/demo-builder
新建 branch feat/demo-builder
让这个目录直接检出到该分支

6.3 基于已有 branch 创建 worktree

git worktree add .worktrees/release-check release/7.6

适合已有远程或本地分支，只想把它挂成独立目录来操作。

6.4 进入某个 worktree

cd .worktrees/demo-builder
git branch --show-current

建议养成习惯：每次进入新的 worktree，先确认当前分支。

6.5 删除不再需要的 worktree

git worktree remove .worktrees/demo-builder

注意：

如果目录内有未提交改动，Git 可能拒绝删除
先确认是否已提交、合并或不再需要

6.6 删除分支

git branch -d feat/demo-builder

如果该分支还没合并，Git 会拒绝。那通常是提醒你先确认分支内容是否真的可以删除。

6.7 清理失效记录

git worktree prune

用途：

清除已经不存在但仍被 Git 记录着的 worktree 元数据

这是周期性清理命令，不需要天天跑，但长期使用 worktree 后很有必要。

7. 常见命令组合

新任务：从零开工

git worktree add .worktrees/feature-x -b feat/feature-x
cd .worktrees/feature-x
git status

读取已有分支并单独检查

git worktree add .worktrees/review-760 release/7.6.0
cd .worktrees/review-760
git log --oneline --decorate -5

任务完成后清理

git worktree remove .worktrees/feature-x
git branch -d feat/feature-x
git worktree prune

8. 推荐目录策略

worktree 放哪里，通常有两种选择。

方案 A：项目内 `.worktrees/`

目录示意：

repo/
├── .worktrees/
│   ├── demo-builder/
│   ├── research-init/
│   └── proto-lab/
└── ...

优点：

离项目最近，最直观
看到仓库就能看到所有并行任务
非常适合个人和小团队协作

缺点：

必须被 .gitignore 忽略

方案 B：仓库外全局目录

目录示意：

~/.config/superpowers/worktrees/<project-name>/<branch-name>/

优点：

仓库根目录更干净
多个项目可以统一管理

缺点：

路径长
平时进入目录不够直观

默认建议

对大多数 PM + AI 协作工作区，优先建议 项目内 .worktrees/。

原因很简单：

更容易管理
更容易解释给其他 agent
更适合“一个仓库一眼看清所有并行任务”的工作方式

9. 为什么 `.worktrees/` 一定要加入 `.gitignore`

如果你把 worktree 建在仓库内，而没有忽略它，典型后果是：

git status 里出现大量 worktree 子目录内容
容易误把 worktree 里的文件当作普通仓库内容提交
主工作区状态被污染

标准认知是：

项目内的 .worktrees/ 本质上是工作目录基础设施，不是仓库内容本身。

所以它应该被忽略，例如：

.worktrees/

注意：本文只解释原则，不代表你现在就该立刻改当前仓库。

10. 多 Agent 协作的标准模型

这是本文最关键的一部分。

10.1 最推荐的角色分工

主控 agent / 主工作区

职责：

看全局状态
审查变更
统一合并
维护主分支稳定
负责文档、计划、任务拆分

限制：

执行 agent / 独立 worktree

职责：

负责一个明确任务
只在自己的 branch 上工作
自己提交、自己验证

限制：

不要碰其他 agent 的目录
不要在同一个 worktree 里顺手做多个无关任务

10.2 四条强规则

一个 agent 一个 worktree
一个任务一个 branch
一个 worktree 不承载多个无关目标
主目录不做具体实现

只要违反其中任意一条，后面大概率会乱。

10.3 为什么不能多个 agent 共用一个目录

共用目录会直接失去 worktree 的意义：

目录上下文不再稳定
提交边界不清楚
谁改了什么难以复盘
一个 agent 的未提交改动会影响另一个 agent

换句话说：

多 agent 协作的最小隔离单位，不是 branch，而是 worktree 目录。

11. 多项目切换怎么理解

“多个项目切换”要先分成两种情况。

情况 A：同一个仓库中的多个项目方向

例如在 drafts/ 里同时处理：

原型 A
调研 B
文档 C

这仍然是同一仓库，所以可以直接用 worktree：

git worktree add .worktrees/proto-a -b proto/a
git worktree add .worktrees/research-b -b research/b
git worktree add .worktrees/docs-c -b docs/c

这时切换项目的方式是：

cd .worktrees/proto-a
cd .worktrees/research-b
cd .worktrees/docs-c

不是：

git checkout proto/a
git checkout research/b

情况 B：完全不同的仓库

例如：

drafts/
pm-dashboard/

这里不能用一个仓库的 worktree 去管理另一个仓库。正确组织方式是：

pm-workspace/
├── drafts/
│   └── .worktrees/
└── pm-dashboard/
    └── .worktrees/

也就是说：

每个仓库自己管理自己的 worktree
仓库之间靠目录切换，不靠 worktree 互相映射

12. 命名规范建议

命名越清晰，协作越稳。

12.1 Branch 命名

推荐使用任务类型前缀：

feat/<task>
fix/<task>
docs/<task>
research/<task>
proto/<task>
chore/<task>

例子：

feat/demo-builder
docs/worktree-guide
research/twitter-search
proto/monitor-flow-v1

12.2 Worktree 目录命名

目录名建议和任务名保持一致，不要把完整 branch 名连斜杠直接搬过来。

12.3 Agent 任务命名

如果一个大任务拆给多个 agent，可以在 branch 中体现子任务边界：

feat/monitor-a
feat/monitor-b
feat/monitor-c

目录对应：

.worktrees/monitor-a
.worktrees/monitor-b
.worktrees/monitor-c

13. 标准 SOP：从开任务到收尾

下面给出一套可长期复用的标准流程。

Step 1：主目录确认状态

在主目录先看整体情况：

git status --short --branch
git worktree list

目的：

确认当前主分支状态
看是否已有同名或相关 worktree

Step 2：决定任务边界

创建 worktree 之前，先把任务边界说清楚：

这是功能任务、文档任务还是研究任务
是否需要独立 branch
是否会和其他任务相互影响

经验规则：

只要任务会持续超过半天，或需要 agent 独立工作，就值得单独开 worktree

Step 3：创建 worktree

git worktree add .worktrees/<task-name> -b <branch-name>

例如：

git worktree add .worktrees/demo-builder -b feat/demo-builder

Step 4：进入目录并做基线检查

cd .worktrees/demo-builder
git branch --show-current
git status

如果这是代码型任务，还建议补一轮依赖/测试检查，例如：

npm install
npm test

或者：

pnpm install
pnpm build

目的：

确保这个 worktree 作为独立工作区可正常工作
把“原本就坏掉”和“新改坏了”区分开

Step 5：让 agent 在该目录内独立完成任务

执行阶段只遵循一条原则：

不要跨目录做事。

也就是：

在 .worktrees/demo-builder 做的事，不要顺手回主目录继续改
在 .worktrees/research-init 做的事，不要顺手改 .worktrees/demo-builder

Step 6：提交

在各自 worktree 中独立提交：

git add .
git commit -m "feat: implement demo builder flow"

Step 7：回主目录统一 review 和合并

切回主目录，做总控检查：

cd /path/to/repo
git log --oneline --graph --decorate --all
git diff main...feat/demo-builder

然后再决定 merge。

Step 8：清理

任务确认合并完成后：

git worktree remove .worktrees/demo-builder
git branch -d feat/demo-builder
git worktree prune

这一步不要省略。不清理，几周后目录会变成垃圾堆。

14. 一个完整的多 Agent 示例

假设你要同时推进三件事：

任务 A：整理 demo 构建流程
任务 B：写调研项目初始化规范
任务 C：实验一个原型交互

标准组织方式：

git worktree add .worktrees/demo-builder -b feat/demo-builder
git worktree add .worktrees/research-init -b docs/research-init-guide
git worktree add .worktrees/proto-lab -b proto/proto-lab

得到的目录结构：

drafts/                         -> main
.worktrees/demo-builder         -> feat/demo-builder
.worktrees/research-init        -> docs/research-init-guide
.worktrees/proto-lab            -> proto/proto-lab

协作方式：

主控 agent 留在 drafts/
Agent A 只进入 .worktrees/demo-builder
Agent B 只进入 .worktrees/research-init
Agent C 只进入 .worktrees/proto-lab

切换时只做目录切换：

cd .worktrees/demo-builder
cd .worktrees/research-init
cd .worktrees/proto-lab

不要互相 checkout 对方的分支。

15. Nox `drafts/` 工作区的推荐落地方式

下面这一节专门针对你当前这类 PM 工作区。

15.1 推荐定位

在 drafts/ 里，建议这样分工：

主目录 drafts/
- 用于时间轴、计划、路线图、总控 review
- 不作为具体功能实现的主战场
.worktrees/
- 用于每个独立任务的执行目录
- 文档、调研、原型、脚本都可以独立出去

15.2 适合单独开 worktree 的任务类型

01_Product_Specs/ 下的大功能规格编写
02_Research_Analysis/ 下的专题调研
06_Prototypes/ 下的 demo 或交互实验
.agents/skills/ 下的 skill 重构
跨多目录的结构性改动

15.3 推荐命名风格

适合 Nox 的 branch 示例：

docs/git-worktree-guide
research/tarsight-gap-analysis
feat/nox-demo-builder
proto/cool-hello-world-v3
chore/skill-refactor-poe-bd-tracker

对应目录示例：

.worktrees/git-worktree-guide
.worktrees/tarsight-gap-analysis
.worktrees/nox-demo-builder
.worktrees/cool-hello-world-v3
.worktrees/poe-bd-tracker

15.4 为什么这对 `drafts/` 特别有用

因为这个仓库天然有几类工作同时存在：

文档
调研
原型
自动化脚本
agent skill

这些工作彼此有关联，但节奏不同、目录不同、持续时间也不同。用单一主目录硬扛，最后通常会变成：

git status 很长
不敢轻易切 branch
一个任务还没收尾，另一个任务又开始了

worktree 刚好适合把这些并行流分开。

16. 实战中的判断规则

不是每个任务都必须开 worktree，但你可以用下面这组规则快速判断。

建议开 worktree 的情况

任务会持续超过半天
会有第二个 agent 介入
任务改动跨多个目录
当前主目录本身就不干净
你需要保留当前任务现场，晚点继续

可以不单独开 worktree 的情况

只是几分钟的小修正
当前目录干净
不需要并行
不需要保留独立上下文

如果你犹豫，经验上宁可多开一个 worktree，也不要把主目录继续弄脏。

17. 常见坑

坑 1：主目录继续做具体开发

结果：

主目录越来越脏
worktree 变成摆设

改法：

坑 2：一个 worktree 里顺手做多个任务

结果：

commit 边界不清楚
review 成本升高
agent 职责混乱

改法：

一个 worktree 只承载一个明确目标

坑 3：忘了忽略 `.worktrees/`

结果：

git status 污染
容易误提交

坑 4：合并后不清理

结果：

.worktrees/
  a-temp/
  b-temp2/
  final/
  final2/
  final-final/

改法：

合并后及时 remove
定期 prune

坑 5：把 `worktree` 当成“多个独立仓库”

结果：

对 Git 行为产生误解

要点：

它们共享同一个仓库历史
只是多个工作目录，不是多个仓库副本

18. FAQ

Q1：同一个 branch 能不能挂两个 worktree？

不能。Git 会阻止你这么做。

Q2：删除 worktree 前里面有未提交改动怎么办？

先处理改动，再删目录。一般有三种路：

提交
合并后删除
明确确认不需要，再手动清理

不要在没判断清楚的情况下直接强删。

Q3：不同 worktree 会共享 `node_modules` 吗？

通常不会。每个 worktree 是独立目录，大多数本地依赖和构建输出都按目录存在。

这意味着：

隔离性更强
但也可能需要各自安装依赖

Q4：远程分支怎么配合使用？

worktree 不影响正常的 git fetch、git push、git pull。
它改变的是本地目录组织方式，不改变 Git 基础协作模型。

Q5：什么时候应该优先清理旧 worktree？

以下任一情况出现就该清理：

任务已 merge
实验方案已废弃
超过一周没有再进入
目录名字你自己都看不懂了

19. 一套可以直接照抄的命令模板

以下命令仅作为模板，不代表你现在就该执行。

初始化一组并行任务

# 查看现状
git status --short --branch
git worktree list

# 为 3 个任务创建独立工作区
git worktree add .worktrees/demo-builder -b feat/demo-builder
git worktree add .worktrees/research-init -b docs/research-init-guide
git worktree add .worktrees/proto-lab -b proto/proto-lab

分别进入各自目录

cd .worktrees/demo-builder
git branch --show-current

cd ../research-init
git branch --show-current

cd ../proto-lab
git branch --show-current

收尾清理

git worktree remove .worktrees/demo-builder
git branch -d feat/demo-builder

git worktree remove .worktrees/research-init
git branch -d docs/research-init-guide

git worktree remove .worktrees/proto-lab
git branch -d proto/proto-lab

git worktree prune

20. 最后的推荐实践

如果你想把这件事真的用顺，建议长期坚持下面这套默认规则：

默认把主目录当作“控制台”，不是“施工现场”
默认一个任务一个 worktree
默认一个 agent 一个 worktree
默认切换任务用 cd
默认合并后立刻清理

把这几条变成习惯后，git worktree 就不再只是一个 Git 小技巧，而会变成你做多 agent 协作和多项目切换的基础设施。

21. 一句话速记版

主目录做统筹，任务目录做实现；一个 agent 一个 worktree，一个任务一个 branch；切换靠 cd，不要靠来回 checkout。