---
title: "Worktree 协同规则"
description: "多 Agent worktree 隔离；共享 .agent + .agent-runtime + graphify-out 基线；备份策略。"
type: rule
scope: governance
applicable_to: ["worktree-isolation", "parallel-development", "shared-agent-state"]
module: rules-worktree-collaboration
module_path: ".agent/rules/worktree-collaboration.md"
status: stable
owner: governance
last_verified: "2026-08-31"
sources: []
linked_decisions: ["D-OKF-001"]
---

# Worktree 协同规则

当多个 Agent 需要并行推进同一个大项目时，可以使用 Git worktree 隔离工作区。worktree 只负责文件系统隔离；任务状态、handoff、锁和合并顺序仍由 `.agent/` 协调。

## 1. 适用场景

适合使用 worktree：

- 多个任务修改不同模块或不同目录。
- 一个 mission 需要多个实现分支并行探索。
- 需要让不同 Agent 在独立工作区运行测试、启动服务或保留本地状态。
- 需要降低并行开发时同一工作区的文件冲突。

不适合使用 worktree：

- 任务共享同一核心文件、公共类型、数据库迁移或接口契约。
- 架构方案尚未确认。
- 需要独占设备、远程机器、许可证或数据库迁移窗口。
- 只是单文件小修，不值得创建新工作区。

## 2. Worktree Identity

每个 worktree 必须有可恢复身份：

- `worktree_path`：绝对路径或项目相对路径
- `branch`：对应 Git 分支
- `base_branch`：从哪个分支创建
- `base_commit`：创建时的基线提交
- `task_id` / `mission_id`
- `agent_id` 与角色
- `owned_files`：该 worktree 允许写入的文件或目录范围

这些信息必须记录到 Agent Registry 或 handoff JSON 中。

### 目录布局

不得把任务 worktree 与其他无关项目平铺在同一目录。默认采用“每个主仓库一个同级容器”：

```text
<repo-parent>/
  <repo>/
  <repo>-worktrees/
    <mission-or-task-id>[-slug]/
```

例如 `/Projects/AI-Apps/AI-Workbench` 对应 `/Projects/AI-Apps/AI-Workbench-worktrees/M007`。

约束：

- 主仓库本身不得放入 worktree 容器。
- 子目录名不重复仓库名。
- 优先使用稳定的 Mission/Task ID；仅在需要区分并发 attempt 时追加短小写 slug。
- 仓库策略或 `CORTEX_WORKTREE_ROOT` 可以覆盖容器根目录；写入状态前必须解析为绝对路径。
- 只有项目明确配置时才允许使用仓库内部 `.worktrees/`，并且必须加入 Git ignore，同时排除 IDE watcher 和索引器。
- 不得使用 Finder、`mv` 或复制工具移动已登记 worktree；完成 clean/活动进程审计后使用 `git worktree move`。
- 移动后必须更新持久化旧路径的 WorkspaceIdentity、Run、Session、Queue、lock、handoff 和 Dashboard 投影，并验证 `git worktree list --porcelain`。

## 3. 共享 Agent 状态与 Graphify 基线

多个 worktree 必须共享主 worktree 的 `.agent`、`.agent-runtime` 状态目录与 `graphify-out` 基线，避免 task-progress、locks、handoffs、artifacts、dashboard、Coordination Task/Lease 和图谱事实分裂。

推荐方式是在子 worktree 中使用符号链接：

```bash
# 先审计并保留已有状态；不得直接删除子 worktree 的 .agent 或 .agent-runtime。
mv <child-worktree>/.agent <primary-worktree>/.dev/worktree-agent-backups/<child>-agent-<timestamp>
ln -s <primary-worktree>/.agent <child-worktree>/.agent
mv <child-worktree>/.agent-runtime <primary-worktree>/.dev/worktree-agent-backups/<child>-agent-runtime-<timestamp>
ln -s <primary-worktree>/.agent-runtime <child-worktree>/.agent-runtime
ln -s <primary-worktree>/graphify-out <child-worktree>/graphify-out
```

说明：

- 不推荐硬链接目录；多数文件系统不支持目录硬链接，且容易破坏目录一致性。
- 不要在每个 worktree 复制一份 `.agent` 后各自写入。
- 若子 worktree 不存在对应目录，跳过该 `mv`；先核验链接目标和备份目录，再建立链接。
- 所有 worktree 应共享同一套 `.agent/locks/`、`.agent/handoffs/`、`.agent/artifacts/` 和 `.agent/metrics/agent-dashboard.html`。
- `.agent-runtime` 必须与 `.agent` 同源共享；不得让 `task` 写入旧布局而让 `lease` 或 `agent launch` 读取新布局。
- Graphify 仅共享主分支基线；每次查询后必须用 `git diff <base>...HEAD` 复核当前 worktree 增量，不能把共享图谱当作分支最新事实。
- 如果确实需要隔离实验状态，必须在 handoff 或 coordination report 中明确说明该 worktree 不参与共享状态。

## 4. 锁与写入边界

- 开始写代码前必须获取 `task:<id>` 或 `file:<path>` Progress Lock。
- 不同 worktree 仍然可能修改同一文件；worktree 不能替代锁。
- `owned_files` 之外的改动必须先在 handoff 或 coordination report 中说明原因。
- 如果锁冲突，停止写入并交给 coordinator 输出恢复方案。

## 5. Handoff 要求

跨 worktree handoff 必须记录：

- 来源 worktree 和目标 worktree
- 当前分支、`HEAD` commit、base commit
- 未提交改动摘要：`git status --short`
- 已提交但未合并的 commit 列表
- 已持有或应释放的 lock scope
- Artifact Bus state 和相关验证结果
- 下一步应该在原 worktree 继续，还是切到目标 worktree 继续

handoff 不复制大段 diff；使用路径、commit 和 artifact 引用。

## 6. 状态同步

多 worktree 协同必须遵循：

1. 每个 worktree 的任务状态写入 `.agent/artifacts/<task-id>/` 或 mission milestone。
2. `/handoff` 用于跨 Agent 或跨 worktree 转移上下文。
3. `/sync-plans` 只同步任务计划状态，不代表代码已经合并。
4. 合并前必须检查 registry、locks、handoff 和 git 状态是否一致。
5. 合并后运行 `/update-refs`；若影响开发者文档，运行 `/publish-docs`。

## 7. 及时提交与主线验证

- 每个 worktree 完成一个可验证任务后，应立即运行 `/ship <task-id>` 或 `/commit`，不要长期保留大批未提交改动。
- worktree 内的验证只能证明该分支局部可用；合并后必须在目标主线 worktree 再跑一次关键验证。
- 合并前，源 worktree 应满足：工作区干净、提交信息清晰、验证命令已记录、handoff/Artifact Bus 已更新。
- 合并后，目标 worktree 应满足：功能验证通过、`git diff --check` 通过、任务计划已同步、锁已释放或转移。
- 如果合并后验证失败，优先在合并目标 worktree 修复；若需要回到源 worktree，必须创建 handoff 说明失败证据和恢复路径。

## 8. 合并顺序

推荐合并顺序：

1. 契约、类型、公共接口
2. 后端或核心逻辑
3. UI / 集成层
4. 测试、验证和文档

如果多个 worktree 都修改同一契约，必须先暂停实现任务，回到 `/arch-design` 或 `/plan` 重新拆分。