# Spec Kit 分支管理规范

## 📋 概述

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

## 🎯 设计原则

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

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

### 3. **智能检查防护**
- 创建新分支前检查现有分支状态
- 多分支存在时提示清理
- 提供自动化清理工具

## 🔧 自动化工具

### 核心脚本

#### `manage-branches.sh`
主要的分支管理脚本，提供以下功能：

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

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

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

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

#### `spec-branch` (便捷工具)
简化的命令行界面：

```bash
# 查看状态
spec-branch status

# 清理分支
spec-branch clean

# 合并当前分支
spec-branch merge

# 检查分支状态
spec-branch check
```

### 集成的创建流程

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

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

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

## 🚀 使用流程

### 日常开发工作流

#### 1. **创建新功能前**
```bash
# 检查分支状态
spec-branch check

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

#### 2. **功能开发中**
- 专注当前分支开发
- 定期提交代码
- 避免切换到其他功能分支

#### 3. **功能完成后**
```bash
# 自动合并当前分支到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分支的提交数

#### 清理策略
```bash
# 查看详细状态
spec-branch status

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

交互式清理提供选项：
1. **保留分支** - 继续开发
2. **删除分支** - 丢弃变更（谨慎！）
3. **合并到main** - 完成功能
4. **跳过** - 稍后处理

## ⚠️ 最佳实践

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

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

### 紧急情况处理

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

#### 批量清理
```bash
# 查看所有分支
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`中的检查逻辑：

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

# 修改警告阈值
WARN_THRESHOLD=1
```

## 📊 监控和报告

### 分支健康度检查
```bash
# 定期运行分支状态检查
spec-branch status

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

### 指标追踪
- 平均分支生命周期
- 分支合并频率
- 未完成分支数量

## 🔄 版本控制集成

### Git Hooks（可选）
在`.git/hooks/pre-push`中添加检查：

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

### CI/CD集成
在构建流程中添加分支检查：

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

## 🛠️ 故障排除

### 常见问题

#### 问题1: 分支检查失败
```bash
# 检查脚本权限
chmod +x .specify/scripts/bash/manage-branches.sh

# 检查Git状态
git status
```

#### 问题2: 合并冲突
```bash
# 解决冲突后继续合并
git add .
git commit -m "解决合并冲突"
spec-branch merge
```

#### 问题3: 无法删除分支
```bash
# 强制删除
git branch -D <branch-name>

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

## 📚 相关文档

- [Spec Kit 使用指南](./spec-kit-guide.md)
- [功能开发流程](./feature-development.md)
- [Git 工作流规范](./git-workflow.md)

---

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