Claude Code Git工作流：分支到合并全实战

graph TB
    subgraph "Claude Code Git工作流架构"
        A[开发者指令] --> B[Claude Code理解层]
        B --> C{操作类型判断}
        C -->|提交| D[智能Commit]
        C -->|分支| E[分支策略引擎]
        C -->|合并| F[冲突解决引擎]
        C -->|PR| G[PR自动化管线]

        D --> D1[变更语义分析]
        D1 --> D2[Conventional Commits生成]
        D2 --> D3[Co-Authored-By追加]

        E --> E1[Feature Branch模式]
        E --> E2[Git Flow模式]
        E --> E3[Trunk-Based模式]

        F --> F1[三方合并分析]
        F1 --> F2[冲突块语义理解]
        F2 --> F3[自动/半自动解决]

        G --> G1[PR描述生成]
        G --> G2[Review标签自动标注]
        G --> G3[Test Plan建议]
    end

# 在Claude Code中直接说：
claude "提交当前的修改"

# Claude会执行以下步骤：
# 1. git status — 查看所有变更
# 2. git diff — 分析具体改动内容
# 3. 生成语义化commit message
# 4. git add 相关文件（不是无脑 git add .）
# 5. git commit -m "生成的message"

feat: add user authentication with JWT tokens

Implement JWT-based authentication including:
- Login/logout endpoints
- Token refresh mechanism
- Middleware for route protection

Co-Authored-By: Claude <[email protected]>

## Git配置
- 不要在commit message中添加Co-Authored-By行

claude config set --global git.coAuthor false

## Git规范
- 使用Conventional Commits格式
- 提交信息使用英文，以动词原形开头
- scope使用模块名：如 feat(auth):, fix(api):
- body说明"为什么"而非"是什么"

你: "我改了登录功能、修复了支付bug、还更新了依赖。帮我分三次提交。"

Claude会:
1. git diff --stat 分析变更文件
2. 识别三组逻辑独立的变更
3. 分别暂存和提交：
   - git add src/auth/* → commit "feat(auth): ..."
   - git add src/payment/* → commit "fix(payment): ..."
   - git add package.json package-lock.json → commit "chore: ..."

graph LR
    subgraph "❌ 单分支模式"
        M[main] --> C1[commit 1: 功能A]
        C1 --> C2[commit 2: 功能B]
        C2 --> C3[commit 3: 功能A修改]
        C3 --> C4[commit 4: 功能B修改]
        C4 --> C5[commit 5: 回滚功能A]
        style M fill:#ff6b6b,color:#fff
    end

    subgraph "✅ 多分支模式"
        M2[main] --> F1[feature/auth]
        M2 --> F2[feature/payment]
        M2 --> F3[fix/header-bug]
        F1 --> PR1[PR #1]
        F2 --> PR2[PR #2]
        F3 --> PR3[PR #3]
        PR1 --> M3[main merged]
        PR2 --> M3
        PR3 --> M3
        style M2 fill:#51cf66,color:#fff
        style M3 fill:#51cf66,color:#fff
    end

# 第1步：为新功能创建分支
claude "创建一个feature/user-profile分支，基于最新的main"

# Claude执行：
# git checkout main
# git pull origin main
# git checkout -b feature/user-profile

# 第2步：在分支上开发
claude "在feature/user-profile分支上实现用户个人资料页面，包含头像上传和基本信息编辑"

# Claude会在这个分支上工作，不影响main

# 第3步：完成后提交并创建PR
claude "提交所有改动并创建一个PR到main分支"

## Git分支策略
- 所有新功能在feature/*分支开发
- Bug修复在fix/*分支
- 永远不要直接push到main
- 分支命名格式：{type}/{ticket-id}-{简短描述}
  - 示例：feature/PROJ-123-user-profile
  - 示例：fix/PROJ-456-login-timeout
- 合并前必须创建PR，至少一人review
- 合并后立即删除分支

# Claude Code中设置Git Flow
claude "帮我初始化Git Flow工作流：
- main分支用于生产发布
- develop分支用于集成开发
- 当前任务是开发v2.0的用户认证功能
- 创建feature/v2-auth分支从develop分出"

# Claude会执行：
# git checkout develop
# git pull origin develop  
# git checkout -b feature/v2-auth

# 开发完成后
claude "将feature/v2-auth合并回develop，然后删除feature分支"

# 发布时
claude "从develop创建release/v2.0分支，准备发布"

claude "在main分支上添加用户收藏功能，但用feature flag 'enable_favorites' 控制，
默认关闭。只修改相关文件，不要影响现有功能。"

# Claude会：
# 1. 添加feature flag配置
# 2. 在功能入口添加flag检查
# 3. 确保flag关闭时原有行为不受影响
# 4. 提交时标注 [feature-flag]

graph TD
    A[合并冲突检测] --> B{冲突类型判断}
    B -->|文本冲突| C[第一层：语义分析]
    B -->|逻辑冲突| D[第二层：代码流分析]
    B -->|架构冲突| E[第三层：人工介入]

    C --> C1[分析双方diff意图]
    C1 --> C2[自动合并非冲突部分]
    C2 --> C3[对冲突块给出建议]

    D --> D1[追踪函数调用链]
    D1 --> D2[检查API兼容性]
    D2 --> D3[生成兼容代码]

    E --> E1[列出冲突详情]
    E1 --> E2[给出方案选项]
    E2 --> E3[等待开发者决策]

    C3 --> F{自动解决?}
    F -->|是| G[自动合并完成]
    F -->|否| E
    D3 --> G
    E3 --> G

# 步骤1：让Claude Code分析冲突
claude "我遇到了合并冲突，帮我看看怎么解决"

# Claude会执行：
# git status — 找到冲突文件
# 读取冲突标记（<<<<<<, ======, >>>>>>）
# 分析双方改动意图

# 步骤2：Claude输出分析结果
# "检测到 src/auth.js 有3处冲突：
#  冲突1（第45-62行）：你在main改了token过期时间为2h，
#    而feature分支改为支持可配置过期时间。
#    建议：保留feature分支的实现（更灵活）。
#
#  冲突2（第89-103行）：两边都新增了refreshToken函数。
#    建议合并两版本，main版本有更好的错误处理。
#
#  冲突3（第156-178行）：feature分支新增了速率限制。
#    main分支无此部分修改。建议直接采用feature分支。"

# 步骤3：确认后自动解决
claude "按你的建议解决所有冲突，然后提交"

# Claude执行：
# 编辑文件，移除冲突标记
# git add src/auth.js
# git commit -m "merge: resolve conflicts in auth module"

# 安装mergiraf
cargo install mergiraf

# 配置为Git合并驱动
git config --global merge.conflictstyle diff3
git config --global core.attributesFile ~/.gitattributes

# 在 .gitattributes 中添加：
# *.js merge=mergiraf
# *.ts merge=mergiraf
# *.py merge=mergiraf

claude "将feature/user-profile分支rebase到最新的main上，
遇到冲突自动解决，如果不确定的地方暂停问我"

# Claude执行流程：
# 1. git fetch origin main
# 2. git rebase origin/main
# 3. 遇到冲突 → 分析 → 自动解决（有把握的）
# 4. 不确定的冲突 → 展示给用户 → 等待决策
# 5. git rebase --continue
# 6. 重复直到完成

claude "帮我创建一个PR，包含以下要求：
- 基于feature/payment-integration分支
- 目标是main分支
- 标题不超过70个字符
- 包含变更摘要、测试计划和截图说明"

# Claude完整执行：
# 1. git log main..feature/payment-integration — 分析所有commits
# 2. git diff main...feature/payment-integration --stat — 统计变更
# 3. 生成PR标题：feat: integrate Stripe payment processing
# 4. 生成PR描述（包含Summary、Changes、Test Plan）
# 5. gh pr create --title "..." --body "..."

## Summary
- 集成Stripe支付网关，支持信用卡和Apple Pay
- 添加订单状态webhook处理
- 实现支付失败自动重试机制（最多3次）

## Changes
- `src/services/payment.ts`: 新增Stripe服务封装
- `src/routes/checkout.ts`: 结账流程集成支付
- `src/models/order.ts`: 订单状态枚举扩展
- `src/webhooks/stripe.ts`: Webhook事件处理
- `tests/payment.test.ts`: 47个测试用例

## Test Plan
- [ ] 单元测试：`npm test -- payment`
- [ ] Stripe测试模式端到端验证
- [ ] Webhook签名验证测试
- [ ] 支付失败场景回归测试
- [ ] 移动端Apple Pay按钮渲染验证

# 自动响应Review评论
claude "查看PR #42的review评论，帮我逐条回复并修复代码"

# Claude会：
# 1. gh pr view 42 --comments — 获取评论
# 2. gh api repos/{owner}/{repo}/pulls/42/comments — 获取inline comments
# 3. 分析每条评论的意图
# 4. 修改代码
# 5. 推送修复
# 6. 回复评论说明修改内容

## PR规范
- PR标题格式：{type}({scope}): {简短描述}
- 描述必须包含：Summary、Changes、Test Plan三个section
- 变更超过500行时，增加"Migration Guide"section
- 至少关联一个Issue或Ticket
- 合并方式：squash merge到main

// .claude/settings.json
{
  "hooks": {
    "pre-commit": {
      "type": "command",
      "command": "npm run lint && npm run type-check",
      "description": "提交前运行lint和类型检查"
    }
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$TOOL_INPUT\" | grep -q 'git commit'; then echo 'Commit blocked: use Claude Code commit workflow'; exit 1; fi"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# 自动校验commit message格式
MSG=$(cat "$1")
if ! echo "$MSG" | grep -qE "^(feat|fix|refactor|docs|test|chore|perf|ci|build)(\(.+\))?: .{1,70}$"; then
    echo "ERROR: Commit message不符合Conventional Commits格式"
    echo "Expected: type(scope): description"
    echo "Got: $MSG"
    exit 1
fi

#!/bin/bash
# .git/hooks/post-merge
# 检测CLAUDE.md是否有变更，提醒更新
if git diff HEAD@{1} HEAD --name-only | grep -q "CLAUDE.md"; then
    echo "⚠️  CLAUDE.md已更新，请查看最新项目规范"
    echo "运行 cat CLAUDE.md 查看详情"
fi

# 步骤1：初始化项目上下文
claude "/init"
# Claude扫描项目，生成/更新CLAUDE.md

# 步骤2：创建功能分支
claude "基于develop分支创建feature/wishlist功能分支"

# 步骤3：开发（在Claude Code交互中完成）
claude "实现商品收藏功能，要求：
1. 用户可以点击心形图标收藏/取消收藏商品
2. 收藏列表在用户中心页面展示
3. 使用现有的API架构风格
4. 添加乐观更新（optimistic update）提升体验
5. 编写完整的单元测试和集成测试"

# Claude会自动：
# - 分析现有代码架构
# - 创建/修改需要的文件
# - 遵循项目现有的代码风格
# - 编写测试

# 步骤4：运行测试验证
claude "运行所有测试，确保没有破坏现有功能"

# 步骤5：原子化提交
claude "将改动分成合理的原子提交：
1. 数据模型和API变更
2. UI组件
3. 集成和页面
4. 测试"

# 步骤6：推送到远程并创建PR
claude "推送feature/wishlist分支到远程，
创建PR到develop分支，包含完整的PR描述"

# 步骤7：处理review反馈
# （假设reviewer提出了修改意见）
claude "PR #87有一条reviewer评论：
'收藏按钮在未登录时应该跳转到登录页而不是静默失败'
请修复这个问题并回复reviewer"

sequenceDiagram
    participant D as 开发者
    participant C as Claude Code
    participant G as Git
    participant R as GitHub Remote

    D->>C: /init 初始化项目
    C->>G: 扫描代码库
    G-->>C: 项目结构分析
    C-->>D: 生成CLAUDE.md

    D->>C: 创建feature分支
    C->>G: git checkout -b feature/wishlist
    G-->>C: 分支创建成功

    D->>C: 实现收藏功能
    C->>G: 创建/修改文件
    C->>C: 运行lint检查
    C-->>D: 功能实现完成

    D->>C: 运行测试
    C->>G: npm test
    G-->>C: 测试结果
    C-->>D: 所有测试通过

    D->>C: 原子化提交
    C->>G: git add + commit (4次)
    Note over G: feat(model): add wishlist schema<br/>feat(ui): add favorite button<br/>feat(page): integrate wishlist<br/>test: add wishlist tests

    D->>C: 创建PR
    C->>G: git push origin feature/wishlist
    G->>R: 推送到远程
    C->>R: gh pr create
    R-->>C: PR #87 创建成功

    D->>C: 处理review反馈
    C->>G: 修复代码
    C->>R: 推送修复 + 回复评论
    R-->>D: PR merged ✓

## Git安全规则（必须遵守）
- 永远不要在main分支上直接commit
- 不要使用 git push --force
- 不要使用 git reset --hard（除非我明确要求）
- 不要跳过pre-commit hooks（不使用 --no-verify）
- commit前必须运行 npm run lint 和 npm test
- 每个commit只包含逻辑相关的变更
- 删除文件前必须先确认

## 分支命名规范
格式：{type}/{ticket}-{简短描述}
type可选值：
- feature/ — 新功能
- fix/ — Bug修复
- refactor/ — 代码重构
- docs/ — 文档更新
- chore/ — 构建/工具变更

示例：
- feature/PROJ-456-wishlist
- fix/PROJ-789-login-timeout
- refactor/PROJ-101-api-cleanup

# 在主仓库中
claude "我在backend仓库的API做了Breaking Change，
检查frontend仓库中所有调用这个API的地方，
创建fix分支来适配新的接口"

# Claude会：
# 1. 分析API变更内容
# 2. 在frontend仓库中搜索所有调用点
# 3. 创建适配分支
# 4. 逐个修复调用代码

# 生产环境出Bug，紧急修复
claude "生产环境出现支付超时问题。
1. 从main创建hotfix/payment-timeout分支
2. 定位 src/services/payment.ts 第156行的超时逻辑
3. 将超时时间从5s改为15s，并添加重试机制
4. 提交并创建紧急PR，标题标注 [HOTFIX]
5. 添加详细的变更说明和回滚方案"

# Claude理解紧急性，会：
# - 精准定位问题
# - 最小化变更范围
# - 标注紧急程度
# - 提供回滚方案

# 查看操作历史
git reflog

# 回到Claude操作之前的版本
git reset --soft HEAD@{1}

- 每个commit不超过200行变更
- 超过200行时自动拆分为多个原子commit

"帮我把上一个commit拆分成3个更小的原子commit"

# 实例1：在worktree A中开发功能A
claude "创建worktree feature/auth并切换过去"

# 实例2：在worktree B中修复bug
claude "创建worktree fix/header-bug并切换过去"