Spec Kit 分支管理规范

📋 概述

本文档定义了Spec Kit的自动化分支管理流程，旨在防止分支累积，确保开发流程清洁高效。

🎯 设计原则

1. 一个功能一个分支

每个/specify命令创建独立的功能分支
分支命名格式：001-功能名, 002-功能名
避免在同一分支中混合多个功能

2. 完成后立即合并

功能完成后立即合并到main分支
合并后删除功能分支
避免长期存在的功能分支

3. 智能检查防护

创建新分支前检查现有分支状态
多分支存在时提示清理
提供自动化清理工具

🔧 自动化工具

核心脚本

`manage-branches.sh`

主要的分支管理脚本，提供以下功能：

# 查看分支状态
./manage-branches.sh --status

# 交互式分支清理
./manage-branches.sh --cleanup

# 自动合并当前分支
./manage-branches.sh --merge

# 新功能创建前检查
./manage-branches.sh --check

`spec-branch` (便捷工具)

简化的命令行界面：

# 查看状态
spec-branch status

# 清理分支
spec-branch clean

# 合并当前分支
spec-branch merge

# 检查分支状态
spec-branch check

集成的创建流程

create-new-feature.sh已集成分支检查：

# 正常创建（包含分支检查）
./create-new-feature.sh "新功能描述"

# 跳过分支检查（紧急情况）
./create-new-feature.sh --skip-check "新功能描述"

🚀 使用流程

日常开发工作流

1. 创建新功能前

# 检查分支状态
spec-branch check

# 如果有多分支，先清理
spec-branch clean

2. 功能开发中

专注当前分支开发
定期提交代码
避免切换到其他功能分支

3. 功能完成后

# 自动合并当前分支到main
spec-branch merge

# 或手动合并流程
git add .
git commit -m "完成功能实现"
git checkout main
git merge <feature-branch>
git branch -d <feature-branch>

分支状态管理

分支状态分析

脚本会分析以下信息：

Spec目录: 是否存在specs目录
代码实现: src目录中的变更文件数
提交数量: 相对main分支的提交数

清理策略

# 查看详细状态
spec-branch status

# 交互式清理（推荐）
spec-branch clean

交互式清理提供选项：

保留分支 - 继续开发
删除分支 - 丢弃变更（谨慎！）
合并到main - 完成功能
跳过 - 稍后处理

⚠️ 最佳实践

DO ✅

每次创建新功能前运行分支检查
功能完成后立即合并
使用便捷工具简化操作
定期运行 spec-branch status 检查状态

DON'T ❌

不要同时开发多个功能分支
不要长期保留已完成的分支
不要跳过分支检查（除非紧急）
不要在main分支直接开发

紧急情况处理

强制创建分支

# 跳过检查创建紧急分支
./create-new-feature.sh --skip-check "紧急修复"

批量清理

# 查看所有分支
git branch -v

# 删除已合并的分支
git branch --merged main | grep -v main | xargs git branch -d

# 强制删除未合并分支（谨慎！）
git branch -D <branch-name>

🔧 配置和自定义

环境变量

SKIP_BRANCH_CHECK=true - 全局跳过分支检查
MAIN_BRANCH=develop - 自定义主分支名称

自定义检查规则

修改manage-branches.sh中的检查逻辑：

# 修改最大允许分支数
MAX_BRANCHES=2

# 修改警告阈值
WARN_THRESHOLD=1

📊 监控和报告

分支健康度检查

# 定期运行分支状态检查
spec-branch status

# 查看分支历史
git branch -v
git log --oneline --graph --all

指标追踪

平均分支生命周期
分支合并频率
未完成分支数量

🔄 版本控制集成

Git Hooks（可选）

在.git/hooks/pre-push中添加检查：

#!/bin/bash
# 推送前检查分支状态
./.specify/scripts/bash/manage-branches.sh --check

CI/CD集成

在构建流程中添加分支检查：

- name: Check branch status
  run: ./.specify/scripts/bash/manage-branches.sh --status

🛠️ 故障排除

常见问题

问题1: 分支检查失败

# 检查脚本权限
chmod +x .specify/scripts/bash/manage-branches.sh

# 检查Git状态
git status

问题2: 合并冲突

# 解决冲突后继续合并
git add .
git commit -m "解决合并冲突"
spec-branch merge

问题3: 无法删除分支

# 强制删除
git branch -D <branch-name>

# 清理远程分支引用
git remote prune origin

📚 相关文档

版本: 1.0.0 更新日期: 2025-09-28 维护者: Spec Kit Team

branch-management.md 4.9 KB History Raw