create-branch

create-branch

适用场景

当需要为功能规格创建或复用工作上下文时使用本技能。目标是确定并返回：

• BRANCH_NAME
• FEATURE_DIR
• SPEC_FILE

本技能处理两类问题：

• 是否需要创建、切换或复用 Git 分支
• 是否需要创建、复用或推导 changes/... 功能目录

---

输入

从用户指令与上下文中解析两个驱动量；未出现则视为未指定：

输入	含义	视为已指定
BRANCH_NAME	Git 分支名	显式给出；或「在 xxx 分支」「使用当前分支」等可解析为单一分支名
FEATURE_DIR	功能目录，位于仓库 changes/ 下	显式路径 changes/foo、仅目录名 foo（补全为 changes/foo）、或等价表述

若两者都未指定，可根据 description 推导一个建议名，用于后续询问或派生目录名；这只是技能内部推导，不是脚本参数。若最终采用“基于描述建议”的命名方式，除非名称中已包含业务前缀编号，否则最终建议名应补一个可用编号前缀。

---

执行顺序

严格按以下顺序执行，不要跳步：

1. 解析用户是否显式给出了 BRANCH_NAME、FEATURE_DIR。
2. 先规范化 FEATURE_DIR：
   • 若是绝对路径，直接使用。
   • 若是 changes/foo，直接视为功能目录。
   • 若只是目录名 foo，先补全为 changes/foo 再继续。
3. 只有在完成规范化后，才允许检查目录是否存在。
4. 若目标分支和目标目录都已存在，并且当前场景是复用，则直接复用。
5. 只要涉及创建分支、创建目录、或初始化缺失的 spec.md，必须走脚本。

---

禁止事项

• 不要在规范化前直接检查裸目录名，例如不要先执行 ls test_01/ 再判断它是不是 changes/test_01。
• 不要在执行流里手工用 ls changes/* | grep ... | sort ... | tail ... 这类方式扫描编号目录。
• 不要在技能侧手工创建目录、手工补 spec.md，然后再把状态“补齐”给脚本。
• 不要在“应复用”的场景里再次创建同名目录或同名分支。

---

生成建议名

本节规则只用于技能内部生成建议名，可用于建议分支名、建议目录名，或在“新建分支（基于描述）”场景下推导 BRANCH_NAME 的核心标识；不是 create-new-feature 脚本的输入参数规则。

• 若模式为“复用已有分支”或“复用当前分支”：
  • 不再生成建议名，也不创建新分支，仅输出正确的 BRANCH_NAME。
• 若模式为“新建分支（显式命名）”：
  • 直接使用用户显式给出的名称作为建议名，不做任何改写。
• 若模式为“新建分支（基于描述）”：
  • 默认从功能描述中提取 2–4 个英文关键词，生成动-名词结构建议名核心，如 thread-table-aging、add-user-auth。
  • 保留 OAuth2、API、JWT 等技术缩写的语义，不要在推导阶段丢失这些关键词。
• 若描述中包含形如 RDC:项目-xxxx 或 BUG:项目-xxxx 的编号前缀：
  • 提取该编号标识作为建议名核心，前缀 必须包含 RDC: 或 BUG:，不得丢弃。
  • 一旦存在这种编号信息，后续真正创建分支时，必须以该编号作为前缀或核心标识，例如 RDC:xGW7-13063413-session-delete，不得替换或省略编号。
• 若描述中不包含任何编号：
  • 先提取基于描述的英文建议名核心，例如 thread-table-aging。
  • 在最终生成建议分支名或建议目录名时，应补一个可用编号前缀，例如 001-thread-table-aging。
  • 该编号属于技能层的命名决策结果，不应通过临时 shell 拼接流程在执行中边扫边算。
• 若用户在“指定分支名为 ...”中显式给出完整名称：
  • 仍按“显式命名”规则，直接使用用户给出的完整名称作为建议名，包括其中是否带编号前缀，技能不做改写。

补充说明：

• 上述“建议名”可分为“建议名核心”和“最终名称”两层：若无业务前缀编号，则最终名称通常应在建议名核心前补通用编号；若已有 RDC: / BUG: 前缀，则该前缀即为核心标识，无需再额外补通用编号。
• 上述“建议名”是语义层的中间结果，可用于分支、目录或两者共同命名；真正落盘到脚本时，脚本仍只接受 BRANCH_NAME 与 FEATURE_DIR。
• 若最终需要由 BRANCH_NAME 推导目录名，可在调用脚本前再做一次目录安全清洗。

---

决策流程

先判断当前工作区是否为 Git 仓库，例如执行 git rev-parse --is-inside-work-tree。之后按 BRANCH_NAME × FEATURE_DIR 是否指定走分支。

A. Git 仓库

	已指定 FEATURE_DIR	未指定 FEATURE_DIR
已指定 BRANCH_NAME	G1：若分支与目录都已存在则直接复用；只要任一项缺失，就必须调用脚本创建缺失项，并确保 spec.md 存在	G2：若分支已存在则直接复用；若目录缺失，则先根据 BRANCH_NAME 推导目录名，再调用脚本创建目录；若分支缺失，同样必须通过脚本创建；确保 spec.md 存在
未指定 BRANCH_NAME	G3：若目录已存在则直接复用；若目录不存在则不要手工创建，先按「询问 A」明确分支策略，再通过脚本创建所需目录/分支	G4：若能从 description 推导建议名，则先生成最终建议名称；无业务前缀时应补编号；一旦决定新建，必须通过脚本创建建议目录与分支，然后再进入后续流程

B. 非 Git 仓库

	已指定 FEATURE_DIR	未指定 FEATURE_DIR
已指定 BRANCH_NAME	N1：提示当前非 Git，BRANCH_NAME 仅作逻辑名；若目录已存在则直接复用；若目录缺失则必须通过脚本创建并初始化 spec.md	N2：提示当前非 Git；若未给目录，则可由 BRANCH_NAME 推导目录名；目录创建必须通过脚本完成
未指定 BRANCH_NAME	N3：若目录已存在则直接复用；若目录缺失则必须通过脚本创建；确保 spec.md 存在	N4：若能从 description 推导建议名，则先生成最终建议名称；无业务前缀时应补编号；目录创建必须通过脚本完成

非 Git 场景下仅维护磁盘上的 changes/<dir>/ 与 spec.md；不执行 Git 分支操作。

---

脚本调用

仓库中的 create-new-feature 是一个双参数直通脚本，只接受：

• BRANCH_NAME
• FEATURE_DIR

使用原则：

• 如果目标 BRANCH_NAME 已存在，且目标 FEATURE_DIR 已存在，并且当前场景只是“复用”，则直接复用，不需要调用脚本。
• 只要涉及创建分支、创建目录、或初始化缺失的 spec.md，都必须调用脚本，不允许技能侧手工创建后再补状态。
• 脚本不会自动生成描述型建议名，也不会自动分配编号；若上层已决定采用“基于描述建议”的命名方式，应先在上层完成“建议名核心 + 编号/业务前缀”的组装，再将最终的 BRANCH_NAME / FEATURE_DIR 传给脚本。
• 目录存在性检查必须针对规范化后的 FEATURE_DIR 进行，而不是针对原始输入文本直接检查。

脚本职责：

• 自动定位 REPO_ROOT
• 在 Git 仓库中复用本地分支、跟踪远端分支，或新建分支
• 解析 FEATURE_DIR：支持绝对路径、changes/foo、或仅目录名 foo
• 若仅给 BRANCH_NAME，则按分支名最后一段清洗后推导目录名
• 创建或复用 FEATURE_DIR
• 初始化 spec.md，若已存在则不覆盖
• 输出 BRANCH_NAME、SPEC_FILE、FEATURE_DIR

调用方式

环境	命令
Linux / macOS / Git Bash	bash ./.infra/scripts/bash/create-new-feature.sh --json --branch-name "<BRANCH_NAME>" --feature-dir "<DIR_NAME>"
Windows（PowerShell）	pwsh ./.infra/scripts/powershell/create-new-feature.ps1 -Json -BranchName "<BRANCH_NAME>" -FeatureDir "<DIR_NAME>"

说明：

• 两个参数至少提供一个。
• 在仓库内调用时，FEATURE_DIR 优先传目录名本身，例如 001-gsu-session-delete-handle；脚本会自动补到 changes/...。
• 仅提供 BRANCH_NAME 时，脚本会自动推导目录名。
• 仅提供 FEATURE_DIR 时，脚本只创建或复用目录与 spec.md，不会执行 Git 分支操作。
• 脚本不再处理 short_name、编号分支、--number 等旧入口。

解析输出

• BRANCH_NAME
• SPEC_FILE
• FEATURE_DIR
• change_file：与 SPEC_FILE 同义，仅为兼容旧调用方保留
• HAS_GIT

---

询问模板

询问 A（Git，无 BRANCH_NAME，已有或刚建 FEATURE_DIR）：

已关联功能目录 <FEATURE_DIR>，请选择分支操作：
  A. 复用已有分支（请说明分支名，或“使用当前分支”）
  B. 新建特性分支（建议名：<建议 BRANCH_NAME>）

询问 B（Git，两者均未指定，已生成目录或建议名）：

已准备功能目录 <FEATURE_DIR>，请选择分支操作：
  A. 复用某个已有分支（请说明分支名）
  B. 新建特性分支（建议名：<建议 BRANCH_NAME>）

---

输出

变量	说明
BRANCH_NAME	最终采用的分支名；非 Git 时可仅作为逻辑名
FEATURE_DIR	功能目录绝对路径
SPEC_FILE	$FEATURE_DIR/spec.md 绝对路径

将以上三个值统一传给调用方技能，例如 specify。