workflow-reference

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Epic/Sprint Development Workflow Reference

Epic/Sprint开发工作流参考

Procedural reference for multi-phase feature development using git worktrees, GitHub issues with sub-issues, and phased PR delivery.

本指南介绍如何使用git worktrees、带子任务的GitHub issues以及分阶段PR交付来进行多阶段功能开发的流程。

Branch Strategy Decision Tree

分支策略决策树

Determine the integration branch and branching model:

Integration branch detection:
- If
```
develop
```
  branch exists (local or remote): integration branch =
```
develop
```
- Otherwise: integration branch = default branch (
```
main
```
  or
```
master
```
  )
Epic branch:
- Named:
```
feature/issue-{N}-epic-{short-name}
```
- Created from: integration branch
- Purpose: collects all phase PRs before final merge to integration
Phase branches:
- Named:
```
feature/issue-{N}-phase{X}-{short-name}
```
- Created from: epic branch
- Merged to: epic branch (squash merge)
Single-phase shortcut:
- If only one phase, skip the epic branch layer
- Create feature branch directly from integration branch
- Merge directly to integration branch

确定集成分支和分支模型：

集成分支检测：
- 如果存在
```
develop
```
  分支（本地或远程）：集成分支 =
```
develop
```
- 否则：集成分支 = 默认分支（
```
main
```
  或
```
master
```
  ）
Epic分支：
- 命名格式：
```
feature/issue-{N}-epic-{short-name}
```
- 从集成分支创建
- 用途：在最终合并到集成分支之前，收集所有阶段的PR
阶段分支：
- 命名格式：
```
feature/issue-{N}-phase{X}-{short-name}
```
- 从Epic分支创建
- 合并到：Epic分支（squash merge）
单阶段快捷方式：
- 如果只有一个阶段，跳过Epic分支层
- 直接从集成分支创建功能分支
- 直接合并到集成分支

State File Format

状态文件格式

Persistent state stored in

.claude/epic.local.md

(gitignored via

.claude/*.local.md

yaml

---
epic_issue: 132
epic_title: "Feature: Community Dashboard"
integration_branch: develop
epic_branch: feature/issue-132-epic-dashboard
worktree_base: "../epic-dashboard"
phases:
  - number: 1
    title: "Backend metrics collection"
    issue: 133
    branch: "feature/issue-133-phase1-metrics"
    status: complete       # pending | in_progress | complete
    pr: 135
  - number: 2
    title: "Dashboard frontend"
    issue: 134
    branch: "feature/issue-134-phase2-frontend"
    status: pending
    pr: null
current_phase: 2
created_at: "2026-02-02T12:00:00Z"
---

持久化状态存储在

.claude/epic.local.md

中（通过

.claude/*.local.md

加入git忽略）：

yaml

---
epic_issue: 132
epic_title: "Feature: Community Dashboard"
integration_branch: develop
epic_branch: feature/issue-132-epic-dashboard
worktree_base: "../epic-dashboard"
phases:
  - number: 1
    title: "Backend metrics collection"
    issue: 133
    branch: "feature/issue-133-phase1-metrics"
    status: complete       # pending | in_progress | complete
    pr: 135
  - number: 2
    title: "Dashboard frontend"
    issue: 134
    branch: "feature/issue-134-phase2-frontend"
    status: pending
    pr: null
current_phase: 2
created_at: "2026-02-02T12:00:00Z"
---

Notes

Running notes about the epic, decisions made, blockers encountered.


Status transitions: `pending` -> `in_progress` -> `complete`

Running notes about the epic, decisions made, blockers encountered.


状态流转：`pending` -> `in_progress` -> `complete`

Git Worktree Operations

Git Worktree操作

All worktree paths use absolute paths (Bash calls do not persist

cd

Create epic worktree:

bash

REPO_ROOT=$(git rev-parse --show-toplevel)
PARENT=$(dirname "$REPO_ROOT")
git worktree add "$PARENT/epic-{short-name}" -b feature/issue-{N}-epic-{short-name} {integration_branch}

Create phase worktree from epic branch:

bash

git worktree add "$PARENT/{short-name}-phase{X}" -b feature/issue-{N}-phase{X}-{short-name} feature/issue-{EPIC}-epic-{epic-name}

Clean up worktree after merge:

bash

git worktree remove "$PARENT/{worktree-name}"
git branch -d feature/issue-{N}-phase{X}-{short-name}

Handle existing worktree: Before creating, check:

bash

git worktree list | grep -q "{branch-name}" && echo "EXISTS" || echo "NEW"

所有工作树路径使用绝对路径（Bash调用不会保留

cd

状态）。

创建Epic工作树：

bash

REPO_ROOT=$(git rev-parse --show-toplevel)
PARENT=$(dirname "$REPO_ROOT")
git worktree add "$PARENT/epic-{short-name}" -b feature/issue-{N}-epic-{short-name} {integration_branch}

从Epic分支创建阶段工作树：

bash

git worktree add "$PARENT/{short-name}-phase{X}" -b feature/issue-{N}-phase{X}-{short-name} feature/issue-{EPIC}-epic-{epic-name}

合并后清理工作树：

bash

git worktree remove "$PARENT/{worktree-name}"
git branch -d feature/issue-{N}-phase{X}-{short-name}

处理已存在的工作树： 创建前检查：

bash

git worktree list | grep -q "{branch-name}" && echo "EXISTS" || echo "NEW"

GitHub Operations

GitHub操作

Create epic issue:

bash

gh issue create --title "Epic: {description}" --label "feature" --body "{body with phase breakdown}"

Create phase sub-issue and link:

bash

PHASE_ISSUE=$(gh issue create --title "Phase {X}: {title}" --label "feature" --body "Part of #{epic_issue}" | grep -o '[0-9]*$')
gh sub-issue add {epic_issue} --sub-issue-number $PHASE_ISSUE

Create PR to epic branch:

bash

gh pr create --base {epic_branch} --title "Phase {X}: {title}" --body "Closes #{phase_issue}\n\nPart of epic #{epic_issue}"

Squash merge:

bash

gh pr merge --squash --delete-branch

Create final PR (epic to integration):

bash

gh pr create --base {integration_branch} --title "{epic_title}" --body "Closes #{epic_issue}\n\n## Phases completed\n{list}"

创建Epic Issue：

bash

gh issue create --title "Epic: {description}" --label "feature" --body "{body with phase breakdown}"

创建阶段子Issue并关联：

bash

PHASE_ISSUE=$(gh issue create --title "Phase {X}: {title}" --label "feature" --body "Part of #{epic_issue}" | grep -o '[0-9]*$')
gh sub-issue add {epic_issue} --sub-issue-number $PHASE_ISSUE

创建合并到Epic分支的PR：

bash

gh pr create --base {epic_branch} --title "Phase {X}: {title}" --body "Closes #{phase_issue}\n\nPart of epic #{epic_issue}"

Squash合并：

bash

gh pr merge --squash --delete-branch

创建最终PR（从Epic分支到集成分支）：

bash

gh pr create --base {integration_branch} --title "{epic_title}" --body "Closes #{epic_issue}\n\n## Phases completed\n{list}"

Confirmation Points

确认节点

Confirm (pause and ask):

Epic plan: before creating issues and branches, present the full plan
Implementation plan: after
```
/plan
```
mode produces the plan, wait for approval
Critical review findings: if
```
/review-pr
```
finds critical issues, present them
Final epic merge: before merging epic branch to integration

Auto-proceed (no confirmation):

Repository detection
Branch and worktree creation (after plan confirmed)
Issue and sub-issue creation (after plan confirmed)
State file updates
Running tests
Non-critical review findings (just summarize)
Worktree cleanup after merge
PR creation

需要确认（暂停并询问）：

Epic计划：在创建Issue和分支之前，展示完整计划
实施计划：
```
/plan
```
模式生成计划后，等待批准
关键评审结果：如果
```
/review-pr
```
发现关键问题，展示问题
最终Epic合并：在将Epic分支合并到集成分支之前

自动执行（无需确认）：

仓库检测
分支和工作树创建（计划确认后）
Issue和子Issue创建（计划确认后）
状态文件更新
运行测试
非关键评审结果（仅总结）
合并后清理工作树
创建PR

Variation Handling

变体处理

No develop branch

无develop分支

Auto-detected. Use

main

(or

master

) as integration branch. All other workflow steps are identical.

自动检测。使用

main

（或

master

）作为集成分支。其他所有工作流步骤保持不变。

Single-phase feature

单阶段功能

When the user describes only one phase or says "just one phase":

Skip epic worktree creation
Create feature branch directly from integration branch:
```
feature/issue-{N}-{short-name}
```
Create single issue (no sub-issues needed)
PR targets integration branch directly

当用户描述仅一个阶段或说“只需一个阶段”时：

跳过Epic工作树创建
直接从集成分支创建功能分支：
```
feature/issue-{N}-{short-name}
```
创建单个Issue（无需子Issue）
PR直接指向集成分支

Resume interrupted epic

恢复中断的Epic

When invoked with

--resume

Read
```
.claude/epic.local.md
```
Find the first phase with status !=
```
complete
```
Check if its worktree exists; if so, switch to it
If worktree does not exist, create it
Continue from where the phase left off

使用

--resume

参数调用时：

读取
```
.claude/epic.local.md
```
找到第一个状态不等于
```
complete
```
的阶段
检查其工作树是否存在；如果存在，切换到该工作树
如果工作树不存在，创建它
从该阶段中断的位置继续

Next phase

下一阶段

When invoked with

--next-phase

Read state, find next
```
pending
```
phase
Mark it
```
in_progress
```
, create worktree, begin execution

使用

--next-phase

参数调用时：

读取状态，找到下一个
```
pending
```
阶段
将其标记为
```
in_progress
```
，创建工作树，开始执行

Finalize

完成收尾

When invoked with

--finalize

Skip to Phase 3 (final PR from epic branch to integration)

使用

--finalize

参数调用时：

直接跳转到阶段3（从Epic分支到集成分支的最终PR）

Integration with Other Skills/Commands

与其他技能/命令集成

/plan
or EnterPlanMode: Invoke at the start of each phase for implementation planning
/review-pr
or /pr-review-toolkit:review-pr
: Invoke before merging each phase PR and the final epic PR
/feature-dev
: Optionally invoke within a phase for complex implementation (user decides)
TodoWrite: Track all phases and steps throughout

/plan
或 EnterPlanMode：在每个阶段开始时调用，用于实施规划
/review-pr
或 /pr-review-toolkit:review-pr
：在合并每个阶段PR和最终Epic PR之前调用
/feature-dev
：在阶段内遇到复杂实现时可选择调用（由用户决定）
TodoWrite：全程跟踪所有阶段和步骤

Naming Conventions

命名规范

Keep names short and lowercase with hyphens:

Epic:

epic-{2-3 word slug}

(e.g.,

epic-dashboard-metrics

)

Phase:

phase{N}-{2-3 word slug}

(e.g.,

phase1-backend-metrics

)

Worktree dirs: same as branch slug without
```
feature/issue-N-
```
prefix

名称保持简短，使用小写字母加连字符：

Epic：
```
epic-{2-3词slug}
```
（例如：
```
epic-dashboard-metrics
```
）

阶段：

phase{N}-{2-3词slug}

（例如：

phase1-backend-metrics

）

工作树目录：与分支slug相同，去掉
```
feature/issue-N-
```
前缀