mcpField
G
git-worktrees

git-worktrees

github.com/lvlup-sw开发22216 次安装2 天前更新
代码仓库

关于 git-worktrees

git-worktrees 是用于创建和管理隔离 Git worktree 的 Skill，适合并行开发任务及子 Agent 工作。它涵盖目录安全检查、基线测试、工作区验证和合并后清理，并说明了集成分支的串行合并流程。

主要功能

  1. 01按约定选择并验证 worktree 目录
  2. 02创建独立分支和 worktree
  3. 03设置环境并运行基线测试
  4. 04修改文件前验证 worktree 状态
  5. 05合并后清理 worktree 与分支

适用场景

  1. 01为可并行任务分配隔离工作区
  2. 02为子 Agent 准备并验证开发环境
  3. 03在合并后移除工作区并整理引用
  4. 04通过串行流程合并共享集成分支

MCP 相关

该 Skill 使用 Exarchos MCP 的编排操作验证 worktree 和基线测试，并在集成合并流程中使用 serialize_merge。它没有描述向 MCP 客户端提供服务的功能。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lvlup-sw/exarchos --skill git-worktrees

安装后在 Claude Code 中输入/git-worktrees确认已加载。

附带文件references/commands-reference.md

详细介绍

Git Worktrees 技能

概述

创建和管理隔离的 git worktree，以支持并行开发任务。

触发条件

在以下情况下激活此技能：

  • 多个任务可以并行执行
  • 用户使用 delegate 分配可并行处理的任务
  • 需要为子 Agent 提供隔离环境
  • 用户明确要求设置 worktree

Worktree 目录位置

优先顺序：

  1. .worktrees/ —— 如果目录已存在且已加入 gitignore
  2. worktrees/ —— 如果目录已存在且已加入 gitignore
  3. 检查 CLAUDE.md 中的项目约定
  4. 如果不明确，询问用户

安全检查（必需）：

# Verify directory is gitignored before creating
git check-ignore -q .worktrees && echo "Safe" || echo "NOT GITIGNORED"

如果目录未加入 gitignore，请将其添加到 .gitignore：

.worktrees/

Worktree 生命周期

1. 创建 Worktree
# Create feature branch
git branch feature/task-name main

# Create worktree
git worktree add .worktrees/task-name feature/task-name

# Verify creation
git worktree list

命名约定： .worktrees/<task-id>-<brief-name>

  • 示例：.worktrees/001-user-auth
  • 示例：.worktrees/002-api-endpoints
2. 设置环境

完整的环境设置表和各项目类型对应的脚本，请参阅 references/commands-reference.md。

3. 基线验证

运行基线测试，确保 worktree 已就绪：

exarchos_orchestrate({
  action: "verify_worktree_baseline",
  worktreePath: ".worktrees/task-name"
})

该脚本会自动检测项目类型（Node.js、.NET、Rust），并运行相应的测试命令。

如果 passed: true： 基线测试通过，worktree 已准备就绪，可以开始实现。 如果 passed: false： 基线测试失败或项目类型未知，请先调查再继续。

如果基线测试失败：

  1. 检查主分支的测试是否失败
  2. 向用户报告问题
  3. 不要继续实现
4. 在 Worktree 中工作

子 Agent 在 worktree 目录中工作：

  • 与其他任务完全隔离
  • 提交会进入功能分支
  • 可以独立运行测试
5. 合并后清理
# After PR merged, remove worktree
git worktree remove .worktrees/task-name

# Optionally delete branch
git branch -d feature/task-name

# Prune stale worktree refs
git worktree prune

并行 Worktree 管理

并行创建 worktree 的示例、跟踪格式以及完整的命令参考表，请参阅 references/commands-reference.md。

Worktree 验证

为什么要验证？

子 Agent 在进行更改前必须确认自己位于 worktree 中。在主项目根目录中工作会导致：

  • 并行任务之间发生合并冲突
  • 意外更改共享状态
  • 构建或测试相互干扰
Worktree 验证

在修改任何文件之前，运行 worktree 验证脚本：

exarchos_orchestrate({
  action: "verify_worktree"
})

如需检查指定路径而非当前目录：

exarchos_orchestrate({
  action: "verify_worktree",
  cwd: "/path/to/.worktrees/task-name"
})

如果 passed: true： 位于有效的 worktree 中，可以继续实现。 如果 passed: false： 不在 worktree 中，立即停止，不要修改文件。

子 Agent 指令

在所有实现者提示词中加入：

## CRITICAL: Worktree Verification (MANDATORY)

Before making ANY file changes, run:

    exarchos_orchestrate({ action: "verify_worktree" })

If `passed: false`: STOP and report error.
DO NOT proceed with any modifications outside a worktree.

反模式

不要这样做应该这样做
在已跟踪的目录中创建 worktree使用已加入 gitignore 的 .worktrees/
跳过基线测试验证始终先确认测试通过
留下过期的 worktree合并后进行清理
忘记安装依赖项在每个 worktree 中运行项目设置
混合不同 worktree 中的工作每个 worktree 只处理一个任务

与委派功能集成

委派技能启动并行任务时：

  1. 为每个并行任务组创建 worktree
  2. 设置环境
  3. 验证基线测试
  4. 将 worktree 路径传给子 Agent 并启动任务
  5. 跟踪进度
  6. 按依赖顺序合并分支
  7. 清理 worktree

等待合并的交接

子 Agent 在其工作树中完成任务后，工作流的 HSM 会从 delegate 转换为 feature/merge-pending。由于集成分支是共享的——合并同级工作树可能会发生竞争——serialize_merge 是集成合并路径：它会持有针对每个 integrationRef 的单写者租约，然后组合使用 merge_orchestrate，通过本地 git merge 将工作树的分支合入集成分支，并记录恢复点 SHA——完整的交接协议请参见 @skills/merge-orchestrator/SKILL.md。不要为此集成合并直接调用原始 merge_orchestrate（存在有效的其他租约时，它会安全失败）；原始 merge_orchestrate 适用于非集成合并，或重新提交原始租约的崩溃恢复调用方。

合并报告 phase: 'completed' 后，再执行工作树清理（上文的第 7 步）。

这与合成阶段的远程 PR 合并（merge_pr）并不相同。serialize_merge / merge_orchestrate 操作主工作树中的本地引用；集成分支就绪、可以创建供人工审核的 PR 后，merge_pr 会调用 VCS 提供商。

完成标准

工作树设置：

  • 目录已加入 gitignore
  • 工作树已成功创建
  • 环境依赖已安装
  • 基线测试通过
  • 已准备好供子 Agent 使用

工作树清理：

  • 功能分支已合并到 main
  • 工作树已移除
  • 分支已删除（如果已合并）
  • 陈旧引用已清理

评论

支持 Markdown