finishing-a-development-branch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Finishing a Development Branch

开发分支收尾

Overview

概述

Guide completion of development work by presenting clear options and handling chosen workflow.

Core principle: Verify tests -> Present options -> Execute choice -> Clean up.

Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."

本指南通过提供清晰选项并处理所选工作流，指导你完成开发工作收尾。

核心原则： 验证测试 -> 展示选项 -> 执行选择 -> 清理

启动时声明： "我正在使用开发分支收尾技能来完成这项工作。"

The Process

流程

Step 1: Verify Tests

步骤1：验证测试

Before presenting options, verify tests pass:

bash

undefined

在展示选项前，先验证测试全部通过：

bash

undefined

Run project's test suite

npm test / cargo test / pytest / go test ./...


**If tests fail:**

Tests failing (<N> failures). Must fix before completing:

[Show failures]

Cannot proceed with merge/PR until tests pass.


Stop. Don't proceed to Step 2.

**If tests pass:** Continue to Step 2.

npm test / cargo test / pytest / go test ./...


**如果测试失败：**

测试未通过（<N>个失败项），必须先修复才能完成收尾：

[展示失败内容]

测试通过前无法继续合并/PR操作。


停止操作，不要进入步骤2。

**如果测试通过：** 继续步骤2。

Step 2: Determine Base Branch

步骤2：确定基础分支

bash

undefined

bash

undefined

Try common base branches

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null


Or ask: "This branch split from main - is that correct?"

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null


或者询问："这个分支是从main切出来的，对吗？"

Step 3: Present Options

步骤3：展示选项

Present exactly these 4 options:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

Don't add explanation - keep options concise.

严格展示以下4个选项：

实现已完成，你想要执行什么操作？

1. 本地合并回<base-branch>
2. 推送并创建Pull Request
3. 保留分支现状（我后续自行处理）
4. 丢弃本次工作

选哪个？

不要添加解释，保持选项简洁。

Step 4: Execute Choice

步骤4：执行选择

Option 1: Merge Locally

选项1：本地合并

bash

undefined

bash

undefined

Switch to base branch

git checkout <base-branch>

Pull latest

git pull

Merge feature branch

git merge <feature-branch>

Verify tests on merged result

If tests pass

git branch -d <feature-branch>


Then: Cleanup worktree (Step 5)

git branch -d <feature-branch>


然后：执行工作树清理（步骤5）

Option 2: Push and Create PR

选项2：推送并创建PR

bash

undefined

bash

undefined

Push branch

git push -u origin <feature-branch>

Create PR

gh pr create --title "<title>" --body "$(cat <<'EOF'

Summary

<2-3 bullets of what changed>

Test Plan

<verification steps> EOF )"


Then: Cleanup worktree (Step 5)

<verification steps> EOF )"


然后：执行工作树清理（步骤5）

Option 3: Keep As-Is

选项3：保留现状

Report: "Keeping branch <name>. Worktree preserved at <path>."

Don't cleanup worktree.

报告："保留分支<name>，工作树保存在<path>。"

不要清理工作树。

Option 4: Discard

选项4：丢弃

Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for exact confirmation.

If confirmed:

bash

git checkout <base-branch>
git branch -D <feature-branch>

Then: Cleanup worktree (Step 5)

首先确认：

该操作将永久删除：
- 分支<name>
- 所有提交：<commit-list>
- <path>下的工作树

输入'discard'确认。

等待用户输入准确的确认内容。

如果确认通过：

bash

git checkout <base-branch>
git branch -D <feature-branch>

然后：执行工作树清理（步骤5）

Step 5: Cleanup Worktree

步骤5：清理工作树

For Options 1, 2, 4:

Check if in worktree:

bash

git worktree list | grep $(git branch --show-current)

If yes:

bash

git worktree remove <worktree-path>

For Option 3: Keep worktree.

针对选项1、2、4：

检查是否在工作树中：

bash

git worktree list | grep $(git branch --show-current)

如果是：

bash

git worktree remove <worktree-path>

针对选项3： 保留工作树。

Quick Reference

快速参考

Option	Merge	Push	Keep Worktree	Cleanup Branch
1. Merge locally	Yes	-	-	Yes
2. Create PR	-	Yes	Yes	-
3. Keep as-is	-	-	Yes	-
4. Discard	-	-	-	Yes (force)

选项	合并	推送	保留工作树	清理分支
1. 本地合并	是	-	-	是
2. 创建PR	-	是	是	-
3. 保留现状	-	-	是	-
4. 丢弃	-	-	-	是（强制）

Common Mistakes

常见错误

Skipping test verification

Problem: Merge broken code, create failing PR
Fix: Always verify tests before offering options

Open-ended questions

Problem: "What should I do next?" -> ambiguous
Fix: Present exactly 4 structured options

Automatic worktree cleanup

Problem: Remove worktree when might need it (Option 2, 3)
Fix: Only cleanup for Options 1 and 4

No confirmation for discard

Problem: Accidentally delete work
Fix: Require typed "discard" confirmation

跳过测试验证

问题： 合入损坏代码，创建无法通过的PR
修复： 提供选项前始终先验证测试

开放式问题

问题： "我接下来该做什么？" -> 语义模糊
修复： 严格提供4个结构化选项

自动清理工作树

问题： 在可能还需要工作树的时候删除（选项2、3）
修复： 仅针对选项1和4执行清理

丢弃操作未确认

问题： 意外删除工作内容
修复： 要求输入"discard"确认

Red Flags

红色警示

Never:

Proceed with failing tests
Merge without verifying tests on result
Delete work without confirmation
Force-push without explicit request

Always:

Verify tests before offering options
Present exactly 4 options
Get typed confirmation for Option 4
Clean up worktree for Options 1 & 4 only

绝对禁止：

测试未通过时继续操作
未验证合并结果测试就合并
未确认就删除工作内容
无明确请求时强制推送

必须做到：

提供选项前验证测试通过
严格提供4个选项
选项4需要获取输入确认
仅对选项1和4清理工作树

Integration

集成

Called by:

subagent-driven-development (Step 7) - After all tasks complete
executing-plans (Step 5) - After all batches complete

Pairs with:

using-git-worktrees - Cleans up worktree created by that skill

调用方：

subagent-driven-development（步骤7）- 所有任务完成后
executing-plans（步骤5）- 所有批次完成后

搭配使用：

using-git-worktrees - 清理该技能创建的工作树

Iron Laws

铁则

ALWAYS run the full test suite and verify it passes before offering any merge/PR option — presenting merge options with failing tests leads to broken main branches and failed CI pipelines.
NEVER force-push to main/master or squash commits without explicit user request — these operations rewrite history and can permanently destroy teammates' work.
ALWAYS present exactly the 4 structured options (merge, PR, keep, discard) — open-ended "what next?" questions cause confusion and missed cleanup steps.
NEVER delete a branch or discard work without typed confirmation from the user — accidental deletion of uncommitted work is irreversible.
ALWAYS clean up the worktree for Options 1 and 4 but preserve it for Options 2 and 3 — orphaned worktrees accumulate and confuse future git operations.

ALWAYS 在提供任何合并/PR选项前运行完整测试套件并验证通过——测试未通过时提供合并选项会导致main分支损坏、CI流水线失败。
NEVER 在无用户明确请求时强制推送到main/master或压缩提交——这些操作会重写历史，可能永久丢失队友的工作内容。
ALWAYS 严格提供4个结构化选项（合并、PR、保留、丢弃）——开放式的"接下来做什么？"问题会造成混乱，遗漏清理步骤。
NEVER 在无用户输入确认的情况下删除分支或丢弃工作——意外删除未提交的工作无法恢复。
ALWAYS 对选项1和4清理工作树，对选项2和3保留工作树——孤立的工作树会累积，干扰后续git操作。

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Correct Approach
Skipping test verification before merge	Broken code lands on main; CI fails after the fact	Always run test suite first; gate options on passing tests
Presenting open-ended completion questions	Developer doesn't know available paths; worktrees left orphaned	Present exactly 4 numbered options with clear labels
Deleting branch without confirmation	Developer loses in-progress work permanently	Require typed "discard" confirmation for Option 4
Cleaning up worktree for Option 2 (PR)	Kills local context before PR review is complete	Only remove worktree for Options 1 and 4
Merging directly without pulling latest base	Merge conflicts or stale base; CI detects drift	`git pull` on base branch before `git merge`

反模式	失败原因	正确做法
合并前跳过测试验证	损坏代码进入main；后续CI失败	始终先运行测试套件；选项展示以测试通过为前提
提供开放式收尾问题	开发者不知道可用路径；工作树被孤立	严格提供4个带清晰标签的编号选项
未确认就删除分支	开发者永久丢失进行中的工作	选项4要求输入"discard"确认
为选项2（PR）清理工作树	PR评审完成前就销毁本地上下文	仅对选项1和4删除工作树
未拉取最新基础分支就直接合并	合并冲突或基础分支过时；CI检测到偏移	`git pull` 基础分支后再执行 `git merge`

Memory Protocol (MANDATORY)

内存协议（强制要求）

Before starting: Read

.claude/context/memory/learnings.md

After completing:

New pattern ->
```
.claude/context/memory/learnings.md
```
Issue found ->
```
.claude/context/memory/issues.md
```
Decision made ->
```
.claude/context/memory/decisions.md
```

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

启动前： 读取

.claude/context/memory/learnings.md

完成后：

新模式 ->
```
.claude/context/memory/learnings.md
```
发现问题 ->
```
.claude/context/memory/issues.md
```
做出决策 ->
```
.claude/context/memory/decisions.md
```

假设存在中断：如果没有记录在内存中，就等于没有发生。