worktree-coordination

工作树协调技能

CC 2.1.47 工作树修复： Claude Code 2.1.47 修复了三个关键的工作树问题：工作树中无法发现技能和 Agent、后台任务在工作树中失败，以及 Windows 工作树会话匹配问题。现在，工作树已成为一等公民，无需任何变通方案。

Agent Teams（CC 2.1.33+）： 设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 后，原生 Agent Teams 会提供内置的队友生命周期管理、点对点消息传递和共享任务列表。此技能中的自定义文件锁和协调注册表已被 Teams 的原生协调功能取代。仅在非 Teams 工作树场景中使用此技能（例如，多个彼此独立且不共享团队的 Claude Code 会话）。

原生工作树支持（CC 2.1.49）

CC 2.1.49 通过 EnterWorktree 工具和 --worktree (-w) CLI 标志新增了原生工作树创建功能：

# CLI flag — creates worktree and switches session into it
claude --worktree          # auto-named worktree
claude -w my-feature       # named worktree

# Tool — available to agents and skills
EnterWorktree(name="my-feature")  # creates .claude/worktrees/my-feature/

关键行为：

• 工作树会创建在 .claude/worktrees/ 中，并基于 HEAD 创建一个新分支
• 会话退出时，系统会提示用户保留或移除工作树
• 工作树中可完整发现技能、Agent 和钩子（已在 CC 2.1.47 中修复）

何时使用原生功能，何时使用此技能： 对单会话隔离（快速功能分支），使用 EnterWorktree。对于需要多个 Claude 实例进行文件锁定和共享决策的多会话场景，使用此技能的协调注册表。

工作树生命周期钩子（CC 2.1.50）

CC 2.1.50 新增了 WorktreeCreate 和 WorktreeRemove 钩子事件，可实现自动化生命周期管理：

• WorktreeCreate：通过 EnterWorktree 或 --worktree 标志创建工作树时触发。可用于自动注册、复制配置。
• WorktreeRemove：清理工作树时触发。可用于清理锁、移除注册表条目。

这些钩子是生命周期管理的首选方案，可替代文件监视变通方案。

Agent 隔离（CC 2.1.50）

现在，Agent 可以在 frontmatter 中声明 isolation: worktree，以便自动在隔离的工作树中运行：

isolation: worktree  # Agent gets its own worktree automatically

对于会修改文件的 Agent，建议使用此方式，而非手动调用 EnterWorktree。

命令

/worktree-status

显示所有活跃 Claude Code 实例的状态。

用法： /worktree-status [--json] [--clean]

操作：

1. 运行 cc-worktree-status，查看所有活跃实例
2. 检查过期实例（心跳间隔超过 5 分钟）
3. 查看所有实例中的文件锁

输出包括：

• 实例 ID 和分支
• 当前任务（如已设置）
• 健康状态（ACTIVE/STALE）
• 各实例锁定的文件

/worktree-claim

为此实例显式锁定一个文件。

用法： /worktree-claim src/auth/login.ts

操作：

1. 检查文件是否已锁定
2. 如果被另一个实例锁定，显示持有者
3. 如果可用，则获取锁

/worktree-release

释放文件锁。

用法： /worktree-release src/auth/login.ts

/worktree-sync

同步共享上下文并检查冲突。

用法： /worktree-sync [--check-conflicts] [--pull-decisions]

操作：

1. --check-conflicts：针对其他活跃分支运行 merge-tree
2. --pull-decisions：显示其他实例最近做出的架构决策

/worktree-decision

记录所有实例均可见的架构决策。

用法： /worktree-decision "Using Passport.js for OAuth" --rationale "Better middleware support"

自动行为

文件锁检查（PreToolUse 钩子）

在执行任何 Write 或 Edit 操作之前：

1. 检查文件是否被另一个实例锁定
2. 如果已锁定 → 阻止操作，并显示锁持有者的详细信息
3. 如果未锁定 → 获取锁并继续

心跳（生命周期钩子）

每隔 30 秒（需 CC 2.1.47+ 才能确保在工作树中可靠执行）：

1. 更新此实例的心跳时间戳
2. 清理过期实例（心跳间隔超过 5 分钟）
3. 释放孤立的锁

清理（停止钩子）

Claude Code 退出时（要在 worktree 中可靠执行，需使用 CC 2.1.47+）：

1. 释放此实例持有的所有文件锁
2. 从协调注册表中注销

文件锁状态

┌─────────────────────────────────────────────────────────┐
│  FILE: src/auth/oauth.ts                                │
├─────────────────────────────────────────────────────────┤
│  Status: LOCKED                                         │
│  Holder: cc-auth-a1b2c3                                 │
│  Branch: feature/user-authentication                    │
│  Task:   Implementing OAuth2 login flow                 │
│  Since:  2 minutes ago                                  │
├─────────────────────────────────────────────────────────┤
│  Action: Wait for release or use /worktree-release     │
└─────────────────────────────────────────────────────────┘

注册表架构

位于 .claude/coordination/registry.json：

{
  "instances": {
    "cc-auth-a1b2c3": {
      "worktree": "/Users/dev/worktrees/feature-auth",
      "branch": "feature/user-authentication",
      "task": "Implementing OAuth2",
      "files_locked": ["src/auth/oauth.ts"],
      "started": "-01-08T14:30:00Z",
      "last_heartbeat": "-01-08T14:45:32Z"
    }
  },
  "file_locks": {
    "src/auth/oauth.ts": {
      "instance_id": "cc-auth-a1b2c3",
      "acquired_at": "-01-08T14:35:00Z",
      "reason": "edit"
    }
  },
  "decisions_log": [
    {
      "id": "dec-001",
      "instance_id": "cc-auth-a1b2c3",
      "decision": "Use Passport.js for OAuth",
      "rationale": "Better middleware support",
      "timestamp": "-01-08T14:40:00Z"
    }
  ]
}

CLI 命令

位于 bin/：

# Create new coordinated worktree
cc-worktree-new <feature-name> [--base <branch>]

# Check status of all worktrees
cc-worktree-status [--json] [--clean]

# Sync context and check conflicts
cc-worktree-sync [--check-conflicts] [--pull-decisions]

最佳实践

1. 每个 worktree 一个任务 - 每个 Claude Code 实例都应专注于一个功能/任务
2. 尽早认领文件 - 开始处理共享文件前，使用 /worktree-claim
3. 记录决策 - 对会影响其他实例的选择，使用 /worktree-decision
4. 检查冲突 - 提交前运行 cc-worktree-sync --check-conflicts
5. 清理 - 正常退出 Claude Code 以释放锁（Ctrl+C 或 /exit）

故障排除

“文件已被另一个实例锁定”

1. 检查持有者：/worktree-status
2. 如果实例已过期：cc-worktree-status --clean
3. 如果锁由有效实例持有：与其他实例协调，或处理其他文件

“实例未注册”

心跳钩子会在首次使用工具时自动注册。如果问题仍然存在：

1. 确认你运行的是 CC 2.1.47+（worktree 中的后台任务需要此修复）
2. 检查 .claude-local/instance-id.txt 是否存在
3. 验证 .claude/coordination/ 是否正确创建了符号链接

平台支持（CC 2.1.47+）

平台	Worktree 状态	说明
macOS	完全支持	所有功能均可原生运行
Linux	完全支持	所有功能均可原生运行
Windows	完全支持	CC 2.1.47 修复了盘符大小写导致的会话匹配问题

CC 2.1.47 中改进 worktree 支持的修复：

• 现在可以从 worktree 正确发现技能和 Agent（之前只能从主检出目录发现）
• 后台任务（Task 工具）现在可以从 worktree 成功完成
• Windows worktree 会话匹配现在可处理盘符大小写差异

相关技能

• ork:git-workflow - 在每个协调的 worktree 中使用的 Git 工作流模式
• ork:commit - 在每个 worktree 中按规范格式创建提交
• stacked-prs - 管理可能跨越多个 worktree 的依赖 PR
• ork:architecture-decision-record - 记录通过 /worktree-decision 共享的决策

关键决策

决策	选择	理由
锁粒度	文件级	在防止冲突与并行工作的灵活性之间取得平衡
过期检测	心跳超时 5 min	时间足以应对正常暂停，同时又能快速清理
注册表位置	.claude/coordination/	通过符号链接在 worktree 之间共享，并纳入版本控制
锁获取	在 Write/Edit 时自动获取	无需手动操作即可防止意外冲突
决策共享	集中式日志	所有实例都能实时查看架构决策

能力详情

status-check

关键词： worktree、状态、实例、活动、谁 解决的问题：

• 如何查看所有活动的 Claude Code 实例
• 检查哪些文件已锁定
• 查找过期实例

file-locking

关键词： 锁定、认领、释放、冲突、阻塞 解决的问题：

• 如何防止实例之间的文件冲突
• 编辑前认领文件
• 完成后释放锁

decision-sync

关键词： 决策、同步、共享、协调 解决的问题：

• 在多个实例之间共享架构决策
• 查看其他实例做出的决策
• 协调不同 worktree 之间的处理方式

conflict-prevention

关键词： 冲突、合并、重叠、碰撞 解决的问题：

• 提交前检查合并冲突
• 避免工作重叠
• 协调并行开发