用途
Worktree Coordination 用于协调多个 Claude 实例跨 worktree 进行并行开发。当多个 Claude Code 会话同时工作时，该技能通过文件锁、心跳检测、协调注册表和决策日志来防止文件冲突，并共享架构决策。
主要能力
- 文件锁定：在 Write 或 Edit 操作前自动检查文件是否被其他实例锁定，若已锁定则阻止操作并显示持有者信息；若未锁定则自动获取锁并继续。
- 状态查看：通过 /worktree-status 查看所有活跃 Claude Code 实例的状态，包括实例 ID、分支、当前任务、健康状态（ACTIVE/STALE）以及各实例锁定的文件。
- 显式锁定与释放：通过 /worktree-claim 显式锁定文件，通过 /worktree-release 释放锁。
- 同步与冲突检查：通过 /worktree-sync 同步共享上下文，支持 --check-conflicts 运行 merge-tree 检查冲突，--pull-decisions 查看其他实例的近期架构决策。
- 决策日志：通过 /worktree-decision 记录对所有实例可见的架构决策，包含决策内容和理由。
- 心跳与清理：每 30 秒更新实例心跳时间戳，清理超过 5 分钟无心跳的过期实例并释放孤儿锁；Claude Code 退出时释放所有文件锁并从协调注册表注销。
使用方式
该技能提供以下命令：
/worktree-status [--json] [--clean]：显示所有活跃实例状态，检查过期实例，查看文件锁。/worktree-claim <file>：显式锁定文件。/worktree-release <file>：释放文件锁。/worktree-sync [--check-conflicts] [--pull-decisions]：同步共享上下文并检查冲突。/worktree-decision "<decision>" --rationale "<reason>"：记录架构决策。
CLI 命令位于 bin/ 目录：
# 创建新的协调 worktree
cc-worktree-new <feature-name> [--base <branch>]
# 检查所有 worktree 状态
cc-worktree-status [--json] [--clean]
# 同步上下文并检查冲突
cc-worktree-sync [--check-conflicts] [--pull-decisions]
协调注册表位于 .claude/coordination/registry.json，包含实例信息、文件锁和决策日志。
适用场景
- 多个独立 Claude Code 会话需要并行开发且没有共享团队时。
- 需要防止多个实例同时编辑同一文件导致冲突时。
- 需要在多个 worktree 之间共享架构决策时。
- 需要在提交前检查合并冲突时。
限制与注意事项
- 当设置
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1时，原生 Agent Teams 提供内置的队友生命周期管理、点对点消息和共享任务列表，本技能的自定义文件锁和协调注册表被 Teams 原生协调取代。此时仅应在非 Teams 的 worktree 场景中使用本技能。 - 心跳和退出清理的可靠执行需要 Claude Code 2.1.47+。
- 文件锁粒度为文件级。
- 过期检测超时为 5 分钟无心跳。
- 平台支持：macOS、Linux、Windows 均完全支持（CC 2.1.47+ 修复了 Windows 驱动器盘符大小写导致的会话匹配问题）。
- 建议每个 worktree 只处理一个任务，尽早声明文件，记录影响其他实例的决策，提交前运行冲突检查，并通过 Ctrl+C 或 /exit 正常退出以释放锁。