{"id":"19fa2be9-8eaf-4e75-a1f9-c0886b2ac700","shortId":"TLxHkC","kind":"skill","title":"finishing-a-development-branch","tagline":"当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾","description":"# 完成开发分支\n\n## 概述\n\n通过提供清晰的选项并执行所选工作流来引导开发工作的收尾。\n\n**核心原则：** 验证测试 → 检测环境 → 展示选项 → 执行选择 → 清理。\n\n**开始时宣布：** \"我正在使用 finishing-a-development-branch 技能来完成这项工作。\"\n\n## 流程\n\n### 步骤 1：验证测试\n\n**在展示选项之前，验证测试通过：**\n\n```bash\n# 运行项目的测试套件\nnpm test / cargo test / pytest / go test ./...\n```\n\n**如果测试失败：**\n\n```\n测试失败（<N> 个失败）。必须先修复才能继续：\n\n[显示失败信息]\n\n在测试通过之前无法进行合并/PR。\n```\n\n停止。不要继续到步骤 2。\n\n**如果测试通过：** 继续步骤 2。\n\n### 步骤 2：检测环境\n\n**在展示选项之前，先确定工作区状态：**\n\n```bash\nGIT_DIR=$(cd \"$(git rev-parse --git-dir)\" 2>/dev/null && pwd -P)\nGIT_COMMON=$(cd \"$(git rev-parse --git-common-dir)\" 2>/dev/null && pwd -P)\n```\n\n这决定了展示哪种菜单、以及清理方式：\n\n| 状态 | 菜单 | 清理 |\n|------|------|------|\n| `GIT_DIR == GIT_COMMON`（普通仓库） | 标准 4 个选项 | 无 worktree 可清理 |\n| `GIT_DIR != GIT_COMMON`，命名分支 | 标准 4 个选项 | 按来源判断（见步骤 6） |\n| `GIT_DIR != GIT_COMMON`，分离 HEAD | 收敛 3 个选项（无合并） | 无清理（由外部管理） |\n\n### 步骤 3：确定基础分支\n\n```bash\n# 尝试常见的基础分支\ngit merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null\n```\n\n或者询问：\"这个分支是从 main 分出来的——对吗？\"\n\n### 步骤 4：展示选项\n\n**普通仓库和命名分支 worktree —— 准确展示以下 4 个选项：**\n\n```\n实现已完成。你想怎么做？\n\n1. 在本地合并回 <base-branch>\n2. 推送并创建 Pull Request\n3. 保持分支现状（我稍后处理）\n4. 丢弃这项工作\n\n选哪个？\n```\n\n**分离 HEAD —— 准确展示以下 3 个选项：**\n\n```\n实现已完成。你在分离 HEAD 上（由外部管理的工作区）。\n\n1. 作为新分支推送并创建 Pull Request\n2. 保持现状（我稍后处理）\n3. 丢弃这项工作\n\n选哪个？\n```\n\n**不要添加解释** —— 保持选项简洁。\n\n### 步骤 5：执行选择\n\n#### 选项 1：本地合并\n\n```bash\n# 切到主仓库根目录，保证 CWD 安全\nMAIN_ROOT=$(git -C \"$(git rev-parse --git-common-dir)/..\" rev-parse --show-toplevel)\ncd \"$MAIN_ROOT\"\n\n# 先合并 —— 在删除任何东西之前先验证合并成功\ngit checkout <base-branch>\ngit pull\ngit merge <feature-branch>\n\n# 在合并结果上验证测试\n<test command>\n\n# 合并成功之后再：清理 worktree（步骤 6），然后删除分支\n```\n\n然后：清理 worktree（步骤 6），再删除分支：\n\n```bash\ngit branch -d <feature-branch>\n```\n\n#### 选项 2：推送并创建 PR\n\n```bash\n# 推送分支\ngit push -u origin <feature-branch>\n\n# 创建 PR\ngh pr create --title \"<title>\" --body \"$(cat <<'EOF'\n## 摘要\n<2-3 条变更要点>\n\n## 测试计划\n- [ ] <验证步骤>\nEOF\n)\"\n```\n\n**不要清理 worktree** —— 用户在 PR 反馈迭代时还需要它存活。\n\n#### 选项 3：保持现状\n\n报告：\"保留分支 <name>。工作树保留在 <path>。\"\n\n**不要清理工作树。**\n\n#### 选项 4：丢弃\n\n**先确认：**\n\n```\n这将永久删除：\n- 分支 <name>\n- 所有提交：<commit-list>\n- 工作树 <path>\n\n输入 'discard' 确认。\n```\n\n等待精确的确认。\n\n确认后：\n\n```bash\nMAIN_ROOT=$(git -C \"$(git rev-parse --git-common-dir)/..\" rev-parse --show-toplevel)\ncd \"$MAIN_ROOT\"\n```\n\n然后：清理 worktree（步骤 6），再强制删除分支：\n\n```bash\ngit branch -D <feature-branch>\n```\n\n### 步骤 6：清理工作区\n\n**只对选项 1 和 4 执行。** 选项 2 和 3 始终保留 worktree。\n\n```bash\nGIT_DIR=$(cd \"$(git rev-parse --git-dir)\" 2>/dev/null && pwd -P)\nGIT_COMMON=$(cd \"$(git rev-parse --git-common-dir)\" 2>/dev/null && pwd -P)\nWORKTREE_PATH=$(git rev-parse --show-toplevel)\n```\n\n**如果 `GIT_DIR == GIT_COMMON`：** 普通仓库，无 worktree 可清理。结束。\n\n**如果 worktree 路径在 `.worktrees/`、`worktrees/` 或 `~/.config/superpowers/worktrees/` 之下：** 这是 Superpowers 创建的 worktree —— 我们负责清理。\n\n```bash\nMAIN_ROOT=$(git -C \"$(git rev-parse --git-common-dir)/..\" rev-parse --show-toplevel)\ncd \"$MAIN_ROOT\"\ngit worktree remove \"$WORKTREE_PATH\"\ngit worktree prune  # 自愈：清理任何过期的注册记录\n```\n\n**否则：** 这个工作区由宿主环境（harness）管理。**不要**移除它。如果你的平台提供了工作区退出工具，用它。否则原样保留工作区。\n\n## 快速参考\n\n| 选项 | 合并 | 推送 | 保留工作树 | 清理分支 |\n|------|------|------|-----------|---------|\n| 1. 本地合并 | ✓ | - | - | ✓ |\n| 2. 创建 PR | - | ✓ | ✓ | - |\n| 3. 保持现状 | - | - | ✓ | - |\n| 4. 丢弃 | - | - | - | ✓（强制） |\n\n## 常见错误\n\n**跳过测试验证**\n\n- **问题：** 合并损坏的代码、创建失败的 PR\n- **修复：** 在提供选项前始终验证测试\n\n**开放式问题**\n\n- **问题：** \"接下来该做什么？\" → 含糊不清\n- **修复：** 准确展示 4 个结构化选项（分离 HEAD 时是 3 个）\n\n**为选项 2 清理 worktree**\n\n- **问题：** 删掉用户 PR 迭代还需要的 worktree\n- **修复：** 只在选项 1 和 4 时清理\n\n**先删分支再删 worktree**\n\n- **问题：** `git branch -d` 失败，因为 worktree 还引用着该分支\n- **修复：** 先合并，再删 worktree，最后删分支\n\n**在 worktree 内部跑 `git worktree remove`**\n\n- **问题：** 当 CWD 在被删除的 worktree 内时，命令静默失败\n- **修复：** 跑 `git worktree remove` 前先 `cd` 到主仓库根目录\n\n**清理 harness 拥有的 worktree**\n\n- **问题：** 移除 harness 创建的 worktree 会造成幻影状态\n- **修复：** 只清理 `.worktrees/`、`worktrees/` 或 `~/.config/superpowers/worktrees/` 下的 worktree\n\n**丢弃时不确认**\n\n- **问题：** 意外删除工作成果\n- **修复：** 要求输入 'discard' 确认\n\n## 红线\n\n**绝不：**\n\n- 在测试失败时继续\n- 合并前不验证合并结果上的测试\n- 不确认就删除工作成果\n- 未经明确请求就强制推送\n- 在确认合并成功之前移除 worktree\n- 清理不是你创建的 worktree（按来源判断）\n- 在 worktree 内部跑 `git worktree remove`\n\n**始终：**\n\n- 在提供选项前验证测试\n- 展示菜单前检测环境\n- 准确展示 4 个选项（分离 HEAD 时是 3 个）\n- 选项 4 要求输入确认\n- 只在选项 1 和 4 时清理 worktree\n- 移除 worktree 前 `cd` 到主仓库根目录\n- 移除后跑 `git worktree prune`\n\n## 集成\n\n**被以下技能调用：**\n\n- **subagent-driven-development**（步骤 7）- 所有任务完成后\n- **executing-plans**（步骤 5）- 所有批次完成后\n\n**配合使用：**\n\n- **using-git-worktrees** - 清理由该技能创建的工作树","tags":["finishing","development","branch","superpowers","jnmetacode","agent-skills","agentic-coding","ai-coding","chinese","claude-code","code-review","cursor"],"capabilities":["skill","source-jnmetacode","skill-finishing-a-development-branch","topic-agent-skills","topic-agentic-coding","topic-ai-coding","topic-chinese","topic-claude-code","topic-code-review","topic-cursor","topic-gemini-cli","topic-kiro","topic-mcp","topic-npm-package","topic-prompt-engineering"],"categories":["superpowers-zh"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/jnMetaCode/superpowers-zh/finishing-a-development-branch","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add jnMetaCode/superpowers-zh","source_repo":"https://github.com/jnMetaCode/superpowers-zh","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 3384 github stars · SKILL.md body (4,353 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:52:48.187Z","embedding":null,"createdAt":"2026-04-18T21:55:56.594Z","updatedAt":"2026-05-18T18:52:48.187Z","lastSeenAt":"2026-05-18T18:52:48.187Z","tsv":"'-3':279 '/.config/superpowers/worktrees':410,561 '/dev/null':74,89,143,151,367,382 '/pr':50 '1':31,167,189,205,345,464,506,603 '2':53,56,58,73,88,142,150,169,193,259,278,350,366,381,466,496 '3':126,132,173,182,196,290,352,469,493,597 '4':103,114,158,163,176,297,347,471,488,508,592,600,605 '5':202,630 '6':118,246,252,335,342 '7':624 'base':139,147 'bash':35,62,134,207,254,262,309,337,355,417 'bodi':274 'branch':5,27,256,339,514 'c':215,313,421 'cargo':39 'cat':275 'cd':65,79,230,328,358,372,436,544,611 'checkout':236 'common':78,86,100,111,122,222,320,371,379,398,428 'creat':272 'cwd':210,533 'd':257,340,515 'develop':4,26,622 'dir':64,72,87,98,109,120,223,321,357,365,380,396,429 'discard':305,569 'driven':621 'eof':276,283 'execut':627 'executing-plan':626 'finish':2,24 'finishing-a-development-branch':1,23 'gh':270 'git':63,66,71,77,80,85,97,99,108,110,119,121,136,144,214,216,221,235,237,239,255,264,312,314,319,338,356,359,364,370,373,378,387,395,397,420,422,427,439,444,513,528,540,585,614,635 'git-common-dir':84,220,318,377,426 'git-dir':70,363 'go':42 'har':451,547,552 'head':124,140,148,180,186,491,595 'main':141,154,212,231,310,329,418,437 'master':149 'merg':138,146,240 'merge-bas':137,145 'npm':37 'origin':267 'p':76,91,369,384 'pars':69,83,219,226,317,324,362,376,390,425,432 'path':386,443 'plan':628 'pr':10,261,269,271,287,468,479,501 'prune':446,616 'pull':171,191,238 'push':265 'pwd':75,90,368,383 'pytest':41 'remov':441,530,542,587 'request':172,192 'rev':68,82,218,225,316,323,361,375,389,424,431 'rev-pars':67,81,217,224,315,322,360,374,388,423,430 'root':213,232,311,330,419,438 'show':228,326,392,434 'show-toplevel':227,325,391,433 'skill' 'skill-finishing-a-development-branch' 'source-jnmetacode' 'subag':620 'subagent-driven-develop':619 'superpow':413 'test':38,40,43 'titl':273 'topic-agent-skills' 'topic-agentic-coding' 'topic-ai-coding' 'topic-chinese' 'topic-claude-code' 'topic-code-review' 'topic-cursor' 'topic-gemini-cli' 'topic-kiro' 'topic-mcp' 'topic-npm-package' 'topic-prompt-engineering' 'toplevel':229,327,393,435 'u':266 'use':634 'using-git-worktre':633 'worktre':106,161,244,250,285,333,354,385,401,405,407,408,415,440,442,445,498,503,511,518,523,526,529,535,541,549,554,558,559,563,578,580,583,586,607,609,615,636 '上':187 '下的':562 '不确认就删除工作成果':575 '不要':453 '不要添加解释':199 '不要清理':284 '不要清理工作树':295 '不要继续到步骤':52 '丢弃':298,472 '丢弃时不确认':564 '丢弃这项工作':177,197 '个':494,598 '个失败':46 '个结构化选项':489 '个选项':104,115,127,164,183,593 '为选项':495 '之下':411 '以及清理方式':93 '会造成幻影状态':555 '作为新分支推送并创建':190 '你在分离':185 '你想怎么做':166 '保持分支现状':174 '保持现状':194,291,470 '保持选项简洁':200 '保留分支':293 '保留工作树':462 '保证':209 '修复':480,486,504,520,538,556,567 '停止':51 '先删分支再删':510 '先合并':233,521 '先确定工作区状态':61 '先确认':299 '内时':536 '内部跑':527,584 '再删':522 '再删除分支':253 '再强制删除分支':336 '准确展示':487,591 '准确展示以下':162,181 '分出来的':155 '分支':301 '分离':123,179,490,594 '切到主仓库根目录':208 '创建':268,467 '创建失败的':478 '创建的':414,553 '删掉用户':500 '到主仓库根目录':545,612 '前':610 '前先':543 '反馈迭代时还需要它存活':288 '只在选项':505,602 '只对选项':344 '只清理':557 '可清理':107,402 '合并':460 '合并前不验证合并结果上的测试':574 '合并成功之后再':242 '合并损坏的代码':477 '否则':449 '否则原样保留工作区':457 '含糊不清':485 '命令静默失败':537 '命名分支':112 '和':346,351,507,604 '因为':517 '在':525,582 '在删除任何东西之前先验证合并成功':234 '在合并结果上验证测试':241 '在展示选项之前':33,60 '在提供选项前始终验证测试':481 '在提供选项前验证测试':589 '在本地合并回':168 '在测试失败时继续':573 '在测试通过之前无法进行合并':49 '在确认合并成功之前移除':577 '在被删除的':534 '失败':516 '如果':394,404 '如果你的平台提供了工作区退出工具':455 '如果测试失败':44 '如果测试通过':54 '始终':588 '始终保留':353 '安全':211 '完成开发分支':12 '实现已完成':165,184 '对吗':156 '尝试常见的基础分支':135 '展示菜单前检测环境':590 '展示选项':18,159 '工作树':303 '工作树保留在':294 '常见错误':474 '开始时宣布':21 '开放式问题':482 '强制':473 '当':532 '当实现完成':6 '必须先修复才能继续':47 '快速参考':458 '意外删除工作成果':566 '我们负责清理':416 '我正在使用':22 '我稍后处理':175,195 '或':409,560 '或清理等结构化选项来引导开发工作的收尾':11 '或者询问':152 '所有任务完成后':625 '所有批次完成后':631 '所有提交':302 '所有测试通过':7 '执行':348 '执行选择':19,203 '技能来完成这项工作':28 '报告':292 '拥有的':548 '按来源判断':116,581 '接下来该做什么':484 '推送':461 '推送分支':263 '推送并创建':170,260 '摘要':277 '收敛':125 '无':105,400 '无合并':128 '无清理':129 '时是':492,596 '时清理':509,606 '显示失败信息':48 '普通仓库':101,399 '普通仓库和命名分支':160 '最后删分支':524 '未经明确请求就强制推送':576 '本地合并':206,465 '条变更要点':280 '标准':102,113 '核心原则':15 '检测环境':17,59 '概述':13 '步骤':30,57,131,157,201,245,251,334,341,623,629 '流程':29 '测试失败':45 '测试计划':281 '清理':20,96,243,249,332,497,546 '清理不是你创建的':579 '清理任何过期的注册记录':448 '清理分支':463 '清理工作区':343 '清理由该技能创建的工作树':637 '然后':248,331 '然后删除分支':247 '状态':94 '用它':456 '用户在':286 '由外部管理':130 '由外部管理的工作区':188 '确定基础分支':133 '确认':306,570 '确认后':308 '移除':551,608 '移除后跑':613 '移除它':454 '等待精确的确认':307 '管理':452 '红线':571 '结束':403 '绝不':572 '继续步骤':55 '自愈':447 '菜单':95 '被以下技能调用':618 '要求输入':568 '要求输入确认':601 '见步骤':117 '跑':539 '路径在':406 '跳过测试验证':475 '输入':304 '运行项目的测试套件':36 '还引用着该分支':519 '这个分支是从':153 '这个工作区由宿主环境':450 '这决定了展示哪种菜单':92 '这将永久删除':300 '这是':412 '迭代还需要的':502 '选哪个':178,198 '选项':204,258,289,296,349,459,599 '通过提供合并':9 '通过提供清晰的选项并执行所选工作流来引导开发工作的收尾':14 '配合使用':632 '问题':476,483,499,512,531,550,565 '集成':617 '需要决定如何集成工作时使用':8 '验证步骤':282 '验证测试':16,32 '验证测试通过':34","prices":[{"id":"fb5bfbd3-25cb-4f79-8f5a-2b266763109a","listingId":"19fa2be9-8eaf-4e75-a1f9-c0886b2ac700","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"jnMetaCode","category":"superpowers-zh","install_from":"skills.sh"},"createdAt":"2026-04-18T21:55:56.594Z"}],"sources":[{"listingId":"19fa2be9-8eaf-4e75-a1f9-c0886b2ac700","source":"github","sourceId":"jnMetaCode/superpowers-zh/finishing-a-development-branch","sourceUrl":"https://github.com/jnMetaCode/superpowers-zh/tree/main/skills/finishing-a-development-branch","isPrimary":false,"firstSeenAt":"2026-04-18T21:55:56.594Z","lastSeenAt":"2026-05-18T18:52:48.187Z"}],"details":{"listingId":"19fa2be9-8eaf-4e75-a1f9-c0886b2ac700","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"jnMetaCode","slug":"finishing-a-development-branch","github":{"repo":"jnMetaCode/superpowers-zh","stars":3384,"topics":["agent-skills","agentic-coding","ai-coding","chinese","claude-code","code-review","cursor","gemini-cli","kiro","mcp","npm-package","prompt-engineering","skills","superpowers","tdd","trae"],"license":"mit","html_url":"https://github.com/jnMetaCode/superpowers-zh","pushed_at":"2026-05-18T16:40:33Z","description":"🦸 AI 编程超能力 · 中文增强版 — superpowers（116k+ ⭐）完整汉化 + 6 个中国原创 skills，让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI 等 16 款 AI 编程工具真正会干活","skill_md_sha":"55e7bd8dbbff04f820542f26d101eed94740f76d","skill_md_path":"skills/finishing-a-development-branch/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/jnMetaCode/superpowers-zh/tree/main/skills/finishing-a-development-branch"},"layout":"multi","source":"github","category":"superpowers-zh","frontmatter":{"name":"finishing-a-development-branch","description":"当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾"},"skills_sh_url":"https://skills.sh/jnMetaCode/superpowers-zh/finishing-a-development-branch"},"updatedAt":"2026-05-18T18:52:48.187Z"}}