Back to Details

git-worktree-agent-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Worktree Agent Workflow

Git Worktree Agent Workflow

Start every implementation in an isolated worktree. Each task gets its own directory, its own branch, and produces one focused PR.
所有开发工作都从隔离的Worktree开始。每个任务都有独立的目录、独立的分支，并生成一个目标明确的PR。

When to Use This Skill

何时使用该工作流

Use this skill when...Use standard workflow instead when...
Starting implementation on any issueReading code or researching (no changes)
Working on a feature or fixQuick single-line edit (typo, config value)
Processing multiple issues in parallelInteractive debugging session
Delegating work to subagentsAlready inside a worktree
适合使用该工作流的场景适合使用标准工作流的场景
启动任意问题的开发工作仅阅读代码或进行调研（无代码变更）
进行功能开发或Bug修复快速单行修改（如拼写错误、配置值调整）
并行处理多个任务交互式调试会话
将工作委派给子Agent已处于Worktree目录中

Core Principles

核心原则

  • Isolation by default: Every implementation task starts in a worktree
  • Clean main: The main working directory stays on 
    main
    , always clean
  • Atomic PRs: One worktree = one branch = one PR = one purpose
  • Parallel-ready: Multiple worktrees can be active simultaneously
  • Shared 
    .git
    : Worktrees share the repository database — no cloning overhead
  • 默认隔离：所有开发任务都从Worktree开始
  • 干净的主分支：主工作目录始终停留在
    main
    分支，保持干净状态
  • 原子化PR：一个Worktree对应一个分支、一个PR、一个目标
  • 支持并行：可同时激活多个Worktree
  • 共享.git目录：Worktree共享仓库数据库——无需重复克隆，无额外开销

Context

上下文信息

  • Current branch: !
    git branch --show-current 2>/dev/null
  • Worktrees: !
    git worktree list --porcelain 2>/dev/null
  • Uncommitted changes: !
    git status --porcelain 2>/dev/null
  • Default branch: !
    git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null
  • 当前分支: !
    git branch --show-current 2>/dev/null
  • Worktree列表: !
    git worktree list --porcelain 2>/dev/null
  • 未提交变更: !
    git status --porcelain 2>/dev/null
  • 默认分支: !
    git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null

Execution

执行步骤

Step 1: Ensure clean main

步骤1：确保主分支干净

Fetch latest and confirm the main working directory is clean.
bash
git fetch origin --prune
git status --porcelain
If uncommitted changes exist, stash them before proceeding.
拉取最新代码并确认主工作目录无未提交变更。
bash
git fetch origin --prune
git status --porcelain
如果存在未提交变更，请先暂存后再继续。

Step 2: Create worktree

步骤2：创建Worktree

Create an isolated working directory for the task.
bash
undefined
为任务创建隔离的工作目录。
bash
undefined

Ensure worktrees directory exists (gitignored)

确保worktrees目录存在（已加入.gitignore）

mkdir -p worktrees
mkdir -p worktrees

Single issue

单个问题修复

git worktree add ./worktrees/issue-47 -b wt/issue-47 origin/main
git worktree add ./worktrees/issue-47 -b wt/issue-47 origin/main

Feature work

功能开发

git worktree add ./worktrees/feat-auth -b wt/feat-auth origin/main

**Naming conventions**:

| Task type | Worktree path | Branch name |
|-----------|---------------|-------------|
| Issue | `./worktrees/issue-{N}` | `wt/issue-{N}` |
| Feature | `./worktrees/feat-{name}` | `wt/feat-{name}` |
| Fix | `./worktrees/fix-{name}` | `wt/fix-{name}` |

**Why `./worktrees/`**: Inside the project directory so agents already have file permissions. The `/worktrees/` entry in `.gitignore` prevents tracking worktree contents.
git worktree add ./worktrees/feat-auth -b wt/feat-auth origin/main

**命名规范**:

| 任务类型 | Worktree路径 | 分支名称 |
|-----------|---------------|-------------|
| 问题修复 | `./worktrees/issue-{N}` | `wt/issue-{N}` |
| 功能开发 | `./worktrees/feat-{name}` | `wt/feat-{name}` |
| Bug修复 | `./worktrees/fix-{name}` | `wt/fix-{name}` |

**为什么选择`./worktrees/`**：位于项目目录内，Agent已拥有文件权限。`.gitignore`中的`/worktrees/`条目可避免追踪Worktree内容。

Step 3: Implement in the worktree

步骤3：在Worktree中进行开发

All work happens inside the worktree directory.
Single agent — work directly:
bash
undefined
所有工作都在Worktree目录内完成。
单个Agent —— 直接工作:
bash
undefined

Edit files in the worktree

在Worktree中编辑文件

Run tests in the worktree

在Worktree中运行测试

cd ./worktrees/issue-47 && npm test

**Subagent** — pass the absolute path:
You are working in the worktree at: {repo_root}/worktrees/issue-{N}
Issue #{N}: {issue title}
{issue description}
cd ./worktrees/issue-47 && npm test

**子Agent** —— 传递绝对路径:
你当前的工作目录为Worktree：{repo_root}/worktrees/issue-{N}
问题 #{N}: {issue title}
{issue description}

Your task

你的任务

  1. {specific tasks}
  2. Run tests to verify changes
  3. Stage all changes and create a commit with message: {commit type}({scope}): {description}
    Fixes #{N}
Work ONLY within {repo_root}/worktrees/issue-{N}

**Multiple issues in parallel** — create one worktree per issue, launch agents simultaneously:
```bash
mkdir -p worktrees
git worktree add ./worktrees/issue-47 -b wt/issue-47 origin/main
git worktree add ./worktrees/issue-49 -b wt/issue-49 origin/main
git worktree add ./worktrees/issue-50 -b wt/issue-50 origin/main
Then dispatch agents in parallel — each receives its own worktree path. Agents run simultaneously because each has an isolated directory with no file conflicts.
  1. {具体任务}
  2. 运行测试验证变更
  3. 暂存所有变更并创建提交，提交信息格式如下： {commit type}({scope}): {description}
    Fixes #{N}
仅允许在{repo_root}/worktrees/issue-{N}目录内工作

**多任务并行处理** —— 为每个任务创建一个Worktree，同时启动多个Agent:
```bash
mkdir -p worktrees
git worktree add ./worktrees/issue-47 -b wt/issue-47 origin/main
git worktree add ./worktrees/issue-49 -b wt/issue-49 origin/main
git worktree add ./worktrees/issue-50 -b wt/issue-50 origin/main
然后并行分发Agent —— 每个Agent会收到对应的Worktree路径。由于每个Agent都有独立目录，不存在文件冲突，可同时运行。

Step 4: Verify before integration

步骤4：集成前验证

bash
undefined
bash
undefined

Check each worktree has a clean, focused commit

检查每个Worktree是否有清晰的提交记录

git -C ./worktrees/issue-47 log --oneline origin/main..HEAD git -C ./worktrees/issue-47 diff --stat origin/main
git -C ./worktrees/issue-47 log --oneline origin/main..HEAD git -C ./worktrees/issue-47 diff --stat origin/main

Run tests in the worktree

在Worktree中运行测试

cd ./worktrees/issue-47 && npm test

**Verification checklist**:
- [ ] Commit references the correct issue number
- [ ] Tests pass in the worktree
- [ ] Changes are focused on the single task
- [ ] No unrelated modifications
cd ./worktrees/issue-47 && npm test

**验证清单**:
- [ ] 提交信息关联正确的问题编号
- [ ] Worktree内测试通过
- [ ] 变更仅聚焦于当前任务
- [ ] 无无关修改

Step 5: Push and create PR

步骤5：推送分支并创建PR

Push the worktree branch and create a PR. Handle PRs sequentially to maintain clean history.
bash
undefined
推送Worktree分支并创建PR。按顺序处理PR以保持提交历史清晰。
bash
undefined

Push

推送分支

git -C ./worktrees/issue-47 push -u origin wt/issue-47
git -C ./worktrees/issue-47 push -u origin wt/issue-47

Create PR

创建PR

gh pr create --head wt/issue-47 --base main
--title "fix(scope): description"
--body "Fixes #47"
undefined
gh pr create --head wt/issue-47 --base main
--title "fix(scope): description"
--body "Fixes #47"
undefined

Step 6: Clean up

步骤6：清理工作环境

Remove worktrees after PRs are created (or merged).
bash
undefined
PR创建完成（或合并后）删除Worktree。
bash
undefined

Remove worktrees

删除Worktree

git worktree remove ./worktrees/issue-47
git worktree remove ./worktrees/issue-47

Prune stale references

清理过期引用

git worktree prune
git worktree prune

Delete local branch (after PR merge)

合并PR后删除本地分支

git branch -D wt/issue-47
git branch -D wt/issue-47

Remove empty worktrees directory

删除空的worktrees目录

rmdir worktrees 2>/dev/null || true
undefined
rmdir worktrees 2>/dev/null || true
undefined

Orchestrator vs Subagent Roles

协调Agent与子Agent的角色划分

Orchestrator (main agent)

协调Agent（主Agent）

  1. Create worktrees for each task
  2. Dispatch subagents with worktree paths
  3. Verify results in each worktree
  4. Push branches and create PRs sequentially
  5. Clean up worktrees
  1. 为每个任务创建Worktree
  2. 向子Agent分发Worktree路径
  3. 验证每个Worktree的工作成果
  4. 按顺序推送分支并创建PR
  5. 清理Worktree

Subagent

子Agent

  1. Work only in the assigned worktree
  2. Implement the assigned task
  3. Run tests
  4. Create a single, focused commit
  5. Report completion
  1. 仅在分配的Worktree内工作
  2. 完成分配的开发任务
  3. 运行测试
  4. 创建单个聚焦的提交
  5. 报告任务完成状态

Dependency Installation

依赖安装

Each worktree is a separate directory tree. If the project uses 
node_modules
, 
vendor
, or similar:
bash
undefined
每个Worktree都是独立的目录树。如果项目使用
node_modules
、
vendor
等依赖目录：
bash
undefined

Install dependencies in the worktree

在Worktree中安装依赖

cd ./worktrees/issue-47 && npm install

Shared lockfiles ensure consistent versions across worktrees.
cd ./worktrees/issue-47 && npm install

共享的锁文件可确保所有Worktree使用一致的依赖版本。

Example Flow

示例流程

Orchestrator (main repo, on main branch)
    |
    +--- Step 1: git fetch, confirm clean
    |
    +--- Step 2: Create worktrees
    |         +-- ./worktrees/issue-47
    |         +-- ./worktrees/issue-49
    |
    +--- Step 3: Launch agents IN PARALLEL
    |         |
    |         +---> Agent 1 -> ./worktrees/issue-47
    |         |         +-- Implements, tests, commits
    |         |
    |         +---> Agent 2 -> ./worktrees/issue-49
    |                   +-- Implements, tests, commits
    |
    +--- Step 4: Verify each worktree
    |
    +--- Step 5: Push + create PRs (sequential)
    |
    +--- Step 6: Cleanup
协调Agent（主仓库，位于main分支）
    |
    +--- 步骤1: 拉取最新代码，确认主目录干净
    |
    +--- 步骤2: 创建Worktree
    |         +-- ./worktrees/issue-47
    |         +-- ./worktrees/issue-49
    |
    +--- 步骤3: 并行启动子Agent
    |         |
    |         +---> Agent 1 -> ./worktrees/issue-47
    |         |         +-- 开发、测试、提交
    |         |
    |         +---> Agent 2 -> ./worktrees/issue-49
    |                   +-- 开发、测试、提交
    |
    +--- 步骤4: 验证每个Worktree的成果
    |
    +--- 步骤5: 推送分支并创建PR（按顺序）
    |
    +--- 步骤6: 清理环境

Agentic Optimizations

Agent优化操作

ContextCommand
List worktrees
git worktree list --porcelain
Create worktree
git worktree add ./worktrees/issue-N -b wt/issue-N origin/main
Remove worktree
git worktree remove ./worktrees/issue-N
Check worktree status
git -C ./worktrees/issue-N status --porcelain
Worktree log
git -C ./worktrees/issue-N log --oneline origin/main..HEAD
Worktree diff
git -C ./worktrees/issue-N diff --stat origin/main
Push worktree branch
git -C ./worktrees/issue-N push -u origin wt/issue-N
Run tests in worktree
cd ./worktrees/issue-N && npm test
Prune stale
git worktree prune
场景命令
列出所有Worktree
git worktree list --porcelain
创建Worktree
git worktree add ./worktrees/issue-N -b wt/issue-N origin/main
删除Worktree
git worktree remove ./worktrees/issue-N
检查Worktree状态
git -C ./worktrees/issue-N status --porcelain
查看Worktree提交日志
git -C ./worktrees/issue-N log --oneline origin/main..HEAD
查看Worktree差异
git -C ./worktrees/issue-N diff --stat origin/main
推送Worktree分支
git -C ./worktrees/issue-N push -u origin wt/issue-N
在Worktree中运行测试
cd ./worktrees/issue-N && npm test
清理过期引用
git worktree prune

Quick Reference

快速参考

OperationCommand
Add worktree
git worktree add <path> -b <branch> <start-point>
List worktrees
git worktree list
Remove worktree
git worktree remove <path>
Prune stale
git worktree prune
Lock worktree
git worktree lock <path>
Unlock worktree
git worktree unlock <path>
Move worktree
git worktree move <path> <new-path>
操作命令
添加Worktree
git worktree add <path> -b <branch> <start-point>
列出Worktree
git worktree list
删除Worktree
git worktree remove <path>
清理过期引用
git worktree prune
锁定Worktree
git worktree lock <path>
解锁Worktree
git worktree unlock <path>
移动Worktree
git worktree move <path> <new-path>

Related Skills

相关工作流

  • git-branch-pr-workflow - Standard branch workflows
  • git-rebase-patterns - Advanced rebase techniques
  • multi-agent-workflows - General agent orchestration
  • git-branch-pr-workflow - 标准分支工作流
  • git-rebase-patterns - 高级变基技巧
  • multi-agent-workflows - 通用Agent协调工作流