git-worktree-agent-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 issue	Reading code or researching (no changes)
Working on a feature or fix	Quick single-line edit (typo, config value)
Processing multiple issues in parallel	Interactive debugging session
Delegating work to subagents	Already 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

Single issue

单个问题修复

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

你的任务

{specific tasks}
Run tests to verify changes
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.

{具体任务}
运行测试验证变更
暂存所有变更并创建提交，提交信息格式如下： {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

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

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

Prune stale references

清理过期引用

git worktree prune

Delete local branch (after PR merge)

合并PR后删除本地分支

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）

Create worktrees for each task
Dispatch subagents with worktree paths
Verify results in each worktree
Push branches and create PRs sequentially
Clean up worktrees

为每个任务创建Worktree
向子Agent分发Worktree路径
验证每个Worktree的工作成果
按顺序推送分支并创建PR
清理Worktree

Subagent

子Agent

Work only in the assigned worktree
Implement the assigned task
Run tests
Create a single, focused commit
Report completion

仅在分配的Worktree内工作
完成分配的开发任务
运行测试
创建单个聚焦的提交
报告任务完成状态

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优化操作

Context	Command
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

快速参考

Operation	Command
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>`

git-worktree-agent-workflow

Original

Translation

Git Worktree Agent Workflow

Git Worktree Agent Workflow

When to Use This Skill

何时使用该工作流

Core Principles

核心原则

Context

上下文信息

Execution

执行步骤

Step 1: Ensure clean main

步骤1：确保主分支干净

Step 2: Create worktree

步骤2：创建Worktree

Ensure worktrees directory exists (gitignored)

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

Single issue

单个问题修复

Feature work

功能开发

Step 3: Implement in the worktree

步骤3：在Worktree中进行开发

Edit files in the worktree

在Worktree中编辑文件

Run tests in the worktree

在Worktree中运行测试

Your task

你的任务

Step 4: Verify before integration

步骤4：集成前验证

Check each worktree has a clean, focused commit

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

Run tests in the worktree

在Worktree中运行测试

Step 5: Push and create PR

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

Push

推送分支

Create PR

创建PR

Step 6: Clean up

步骤6：清理工作环境

Remove worktrees

删除Worktree

Prune stale references

清理过期引用

Delete local branch (after PR merge)

合并PR后删除本地分支

Remove empty worktrees directory

删除空的worktrees目录

Orchestrator vs Subagent Roles

协调Agent与子Agent的角色划分

Orchestrator (main agent)

协调Agent（主Agent）

Subagent

子Agent

Dependency Installation

依赖安装

Install dependencies in the worktree

在Worktree中安装依赖

Example Flow

示例流程

Agentic Optimizations

Agent优化操作

Quick Reference

快速参考

Related Skills

相关工作流