基于 spec-kit 的 Git 特性分支命名校验实战以 react-spring 仓库的 speckit-git-validate 为例【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring导读在基于 spec-kit 工作流的仓库中每个功能开发都应从规范的特性分支开始并由自动化 skill 校验分支命名是否符合约定。本文以 react-spring 仓库内.claude/skills/speckit-git-validate/SKILL.md为骨架完整讲解特性分支命名的两种合法模式顺序号与时间戳、与specs/目录的关联映射逻辑、Git 缺失时的优雅降级方案并结合仓库内specs/001-migrate-to-pnpm、specs/002-vitest-browser-migration、specs/003-remix-to-react-router-7三个真实特性目录验证这套规则的落地方式。读完本文你将能独立实现或审计同类 Git 分支命名校验逻辑并理解 spec-kit 中「分支即规格」的工程约束。一、skill 定位Validate Feature Branch 校验什么SKILL.md 定义了一个名为speckit-git-validate的 Claude skill其职责一句话概括为Validate that the current Git branch follows the expected feature branch naming conventions校验当前 Git 分支是否符合预期的特性分支命名约定。它属于 spec-kit 项目结构中的标准 git 命令族元数据source: git:commands/speckit.git.validate.md并且声明了兼容性前提要求仓库具备 spec-kit 项目结构即存在.specify/目录。在 react-spring 仓库中这一前提是成立的——仓库根目录下确有 .specify/feature.json内容为{feature_directory: specs/003-remix-to-react-router-7}、.specify/integration.json 等 spec-kit 配置文件且所有特性规格统一存放在specs/目录下。二、前置条件先探测 Git 是否可用skill 要求在执行任何校验逻辑之前先确认运行环境里是否存在可用的 Git 仓库使用的探测命令是git rev-parse --is-inside-work-tree 2/dev/null该命令的输出语义如下输出true当前目录位于一个 Git 工作树内可以继续分支名校验输出非true例如报错被2/dev/null吞掉、输出为空Git 不可用或当前不在仓库内此时不应硬性中断而应输出警告并跳过校验[specify] Warning: Git repository not detected; skipped branch validation这一设计体现了 skill 的「非阻塞」哲学分支名校验属于开发流程的辅助性约束绝不能因为环境缺失而阻断用户的工作流。三、核心校验规则两种合法分支命名模式在确认 Git 可用后第一步是读取当前分支名git rev-parse --abbrev-ref HEAD随后将分支名与下面两个正则模式之一进行匹配命中任意一种即视为特性分支模式正则示例顺序号Sequential^[0-9]{3,}-001-feature-name、042-fix-bug、1000-big-feature时间戳Timestamp^[0-9]{8}-[0-9]{6}-20260319-143022-feature-name对两种模式逐一拆解顺序号模式以至少 3 位数字开头{3,}表示 3 位或以上后跟一个连字符。数字部分没有上限因此1000-big-feature合法42-fix只有 2 位数字则非法。数字前缀通常与specs/下特性目录的序号一一对应。时间戳模式以YYYYMMDD-HHMMSS形式的时间戳开头再跟连字符和描述性名称。20260319-143022-feature-name即表示 2026-03-19 14:30:22 创建的特性分支。在 react-spring 仓库中顺序号模式是实际采用的约定specs/下的三个特性目录001-migrate-to-pnpm、002-vitest-browser-migration、003-remix-to-react-router-7恰好分别对应形如001-migrate-to-pnpm、002-vitest-browser-migration、003-remix-to-react-router-7的特性分支名。从各 plan.md 头部如**Branch**: 003-remix-to-react-router-7可以印证分支名与specs/目录名完全一致这正是 skill 中「分支即规格」约定的仓库级实证。四、执行流程分支校验与规格目录关联校验逻辑分为两个分支走向下面是完整的决策流程。4.1 命中特性分支命名若当前分支匹配上述任一模式输出✓ On feature branch: branch-name随后进一步校验该分支是否拥有对应的 spec 目录查找规则如下顺序号分支在specs/下查找specs/prefix-*其中prefix取分支名的数字部分。例如分支001-migrate-to-pnpm会去匹配specs/001-*命中specs/001-migrate-to-pnpm/时间戳分支同样查找specs/prefix-*但prefix取YYYYMMDD-HHMMSS部分。查找后的输出分两种情况✓ Spec directory found: path # 规格目录存在 ⚠ No spec directory found for prefix prefix # 规格目录缺失第二种情况本质上是流程纪律提示开发者开出了特性分支却没有对应的规格文档此时 skill 给出警告而非报错提醒补写规格。react-spring 仓库中三个顺序号特性均有对应目录且目录内包含spec.md、plan.md、tasks.md、research.md、data-model.md、checklists/requirements.md、contracts/等完整的 spec-kit 产物形成了「分支 → 规格 → 计划 → 任务」的完整闭环。4.2 未命中特性分支命名若当前分支名既不匹配顺序号也不匹配时间戳输出两行提示✗ Not on a feature branch. Current branch: branch-name Feature branches should be named like: 001-feature-name or 20260319-143022-feature-name这一分支对应两类常见场景在主干/集成分支上开发例如 react-spring 仓库当前所在的next分支运行git rev-parse --abbrev-ref HEAD返回next它不属于任何特性命名模式会被判定为非特性分支分支名拼写不符合约定缺少数字前缀、连字符位置错误等。提示信息会直接给出合法命名范例引导开发者重命名或基于特性分支重新开发。五、优雅降级Git 不可用时的环境变量兜底即使 Git 不可用或当前不在 Git 仓库中校验逻辑也不直接放弃而是提供基于环境变量的兜底校验检查SPECIFY_FEATURE环境变量是否已设置已设置直接将该变量的值作为候选分支名套用顺序号/时间戳模式进行校验未设置跳过校验并输出警告。这一机制使得在无法访问 Git 元数据的环境例如某些 CI 沙箱、容器化执行环境中依然可以通过SPECIFY_FEATURE001-migrate-to-pnpm这样的显式注入来完成分支命名约束的校验保证规范的一致性不因环境差异而丢失。六、从源码结构看校验与 spec-kit 流程的衔接从仓库结构可以推断speckit-git-validate并非孤立存在而是 spec-kit 命令族的一环。.claude/skills/ 目录下还有speckit-specify、speckit-plan、speckit-tasks、speckit-implement、speckit-git-feature、speckit-git-commit、speckit-checklist等 skill构成「规格化 → 计划 → 任务拆解 → 实现 → 提交」的完整流水线而.specify/integration.json中installed_integrations: [claude]表明该仓库通过 spec-kit 的 Claude 集成自动挂载这些 skill。校验逻辑在整个流水线中的位置大致如下speckit-git-initialize / speckit-git-feature # 初始化 创建特性分支 ↓ speckit-git-validate # 校验分支命名 规格目录存在性 ↓ speckit-specify → speckit-plan → speckit-tasks # 产出 specs/prefix 下的规格产物 ↓ speckit-implement → speckit-git-commit # 实现与规范提交从 plan.md 可以看到这套流程的真实产物分支001-migrate-to-pnpm对应specs/001-migrate-to-pnpm/内含以## Constitution Check开头的宪法合规检查评估分层架构、目标无关核心、测试优先等五项原则、## Quality Gates质量门禁、## Project Structure结构说明等章节——这些正是「分支合法 规格目录存在」之后才可能产出的内容。七、实战自查清单将本文所述的校验逻辑提炼为可复用的操作清单供读者在接入同类规范时直接对照环境探测先执行git rev-parse --is-inside-work-tree 2/dev/null非true则输出警告并跳过不阻断流程取分支名git rev-parse --abbrev-ref HEAD模式匹配用^[0-9]{3,}-与^[0-9]{8}-[0-9]{6}-依次匹配命中即为特性分支规格映射顺序号取数字前缀、时间戳取YYYYMMDD-HHMMSS前缀在specs/prefix-*下查找对应目录存在输出✓ Spec directory found缺失输出⚠ No spec directory found for prefix prefix非特性分支提示输出✗ Not on a feature branch并给出两种合法命名示例兜底降级Git 不可用时回退读取SPECIFY_FEATURE环境变量仍不可用则跳过并警告。结语speckit-git-validate展示了一个小而完整的分支治理模式用两个正则表达式约束分支命名、用specs/prefix-*关联规格目录、用环境变量兜底应对环境缺失全程只告警不阻断。react-spring 仓库中specs/001-migrate-to-pnpm、specs/002-vitest-browser-migration、specs/003-remix-to-react-router-7三个完整特性目录证明了这套约定的可落地性——命名规范不再是口头约定而是可自动化校验、可追溯、可审计的工程纪律。【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考