Git 工作流

User: what files have I changed?

Claude: 你当前修改了 7 个文件，分布在 3 个目录中：

  数据库层 (2 文件):
    - migrations/20250426_add_user_prefs.sql  (+45 行)
    - src/db/schema.ts                         (+12, -3 行)

  API 层 (3 文件):
    - src/api/user.ts                          (+67, -8 行)
    - src/api/types.ts                         (+15 行)
    - src/middleware/auth.ts                   (+23 行)

  测试 (2 文件):
    - tests/api/user.test.ts                   (+89 行)
    - tests/middleware/auth.test.ts            (+34 行)

其中 4 个文件已暂存，3 个未暂存。

User: 创建一个功能分支来实现通知系统，基于 main 分支

Claude: 已创建并切换到分支 feature/notification-system
       （基于 main，当前最新 commit: a3f7d2e）

User: 把这个分支变基到最新的 main 上

Claude: 正在获取远程更新...
       已将 feature/notification-system 变基到 origin/main 之上
       （解决了 0 个冲突）

User: 删除所有已经合并到 main 的本地分支

Claude: 发现以下 3 个分支已合并到 main，可以安全删除：
       - fix/auth-timeout
       - chore/update-deps
       - docs/api-guide
       
       确认删除吗？ (y/n)

User: 只暂存 src/api/ 目录下的修改

Claude: 已暂存 src/api/ 目录下的 3 个文件。
       剩余 2 个未暂存文件：tests/api/user.test.ts, README.md

User: 撤销刚才对 auth.ts 的所有修改

Claude: 已重置 src/middleware/auth.ts 到 HEAD 状态。
       （丢弃了 23 行新增内容）

User: 把未暂存的修改保存起来，我要切换分支

Claude: 已创建 stash: "WIP on feature/notification-system"
       包含 2 个文件的未暂存修改。

User: commit these changes

Claude: 我已分析你的变更，生成以下提交信息：

       feat(api): add cursor-based pagination to search endpoint

       - Implement keyset pagination using created_at + id composite cursor
       - Add database migration for composite index on (created_at, id)
       - Update OpenAPI spec with pagination query parameters
       - Add integration tests for edge cases (empty result, last page)

       提交信息是否符合你的预期？
       [y] 确认提交  [n] 修改信息  [s] 拆分提交  [c] 取消

## 提交规范

- 使用 Conventional Commits 格式：feat, fix, docs, refactor, test, chore
- 包含作用域：feat(auth): add OAuth flow
- 主题行不超过 72 个字符
- 多文件变更添加正文，使用 bullet points
- 关联 Issue 编号：Closes #123

User: 我的工作目录里有多个不相关的修改，帮我拆分成独立的提交

Claude: 我分析了你的变更，识别出 3 个逻辑组：

       组 1 - Bug 修复 (2 文件):
         src/auth/session.ts      - 修复会话超时计算
         tests/auth/session.test.ts
         → 建议提交: fix(auth): correct session timeout calculation

       组 2 - 新功能 (3 文件):
         src/api/search.ts        - 添加分页参数
         src/db/migrations/...    - 添加索引
         tests/api/search.test.ts
         → 建议提交: feat(api): add pagination to search endpoint

       组 3 - 重构 (2 文件):
         src/utils/helpers.ts     - 提取公共函数
         src/utils/validators.ts
         → 建议提交: refactor(utils): extract shared validation logic

       确认这个分组方案吗？确认后我会按组依次暂存并提交。

feat(api): add cursor-based pagination to search endpoint

- Implement keyset pagination using created_at + id composite cursor
- Add database migration for composite index on (created_at, id)

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

{
  "includeCoAuthoredBy": false
  // 其他 Git 相关配置请以官方文档为准
  // https://code.claude.com/docs/en/setup
}

User: 为支付集成功能创建一个新分支

Claude: 已创建并切换到 feature/payment-integration
       （基于当前分支 main，commit: 8e2a1c4）

User: 切换到包含认证重构的那个分支

Claude: 找到匹配分支: refactor/auth-module
       已切换。该分支基于 main，领先 12 个 commit。

## 分支命名规范

- 功能分支: feat/{short-description}
- 修复分支: fix/{issue-id}-{short-description}
- 重构分支: refactor/{area}
- 文档分支: docs/{topic}

User: 把我的分支变基到最新的 main 上

Claude: 正在执行: git fetch origin && git rebase origin/main
       变基完成，无冲突。
       
User: 如果有冲突，逐个解释并让我确认后再解决

Claude: 发现 2 个冲突文件：

       文件 1: src/auth/handlers.ts
       - main 分支添加了速率限制逻辑
       - 你的分支重构了 handler 为多个小函数
       - 建议: 将速率限制逻辑移入你新建的 validateLogin 函数
       
       [展示建议的合并结果]
       
       确认这个解决方案吗？

User: 显示哪些本地分支已经合并到 main 可以删除

Claude: 以下分支已完全合并到 main：

       已合并 (可安全删除):
       - fix/auth-timeout      最后提交: 3 周前
       - feat/email-notify     最后提交: 2 周前
       - chore/lint-config     最后提交: 1 周前
       
       未合并 (保留):
       - feature/ai-chat       领先 main 15 个 commit
       - refactor/db-layer     领先 main 8 个 commit
       
       要删除已合并的分支吗？

User: 解决 rebase 后的所有冲突

Claude: 发现 3 个冲突文件，按严重程度排序：

       === 文件 1: src/api/routes.ts (高) ===
       
       冲突描述:
       - main 分支将路由注册改为异步加载模式
       - 你的分支添加了新的 /webhook 路由
       
       分析: 两个变更都需要保留。新路由需要适配异步加载模式。
       
       建议方案:
       [展示合并后的代码]
       
       确认 / 修改 / 跳过这个文件？

我有 merge/rebase 后的冲突。对每个冲突文件：

1. 解释冲突双方各自的意图是什么
2. 判断哪一方明显正确，或是否需要合并
3. 展示建议的解决方案
4. 等我确认后再解决每个文件

不要自动解决。我要理解每个冲突的原因。

User: 总结当前分支相对于 main 的所有变更

Claude: 分支 feature/pagination 相对于 main 的变更摘要：

       ## 变更概览
       - 5 个提交，涉及 7 个文件，+312/-45 行
       
       ## 按区域分组
       
       数据库层:
       - 新增复合索引 (created_at, id)
       - 新增迁移文件
       
       API 层:
       - 搜索端点支持 cursor 分页
       - 新增分页参数校验
       
       测试:
       - 分页功能的集成测试
       - 边界条件测试（空结果、末页）
       
       ## 潜在关注点
       - 新索引对写入性能的影响需关注
       - cursor 编码使用 base64，需确认是否兼容旧客户端

User: 为这个分支创建 PR，描述要包含测试方法和迁移步骤

Claude: 已生成 PR 描述：

       ## 摘要
       为搜索端点添加基于 cursor 的分页支持，替代原有的 offset 分页。
       
       ## 变更内容
       - 实现 keyset pagination，使用 created_at + id 复合 cursor
       - 添加数据库迁移创建复合索引
       - 更新 OpenAPI 规范
       - 添加完整测试覆盖
       
       ## 测试方法
       1. 运行 `npm test -- search.pagination`
       2. 手动测试: `curl http://localhost:3000/api/search?cursor=eyJpZCI6MTB9`
       3. 验证末页响应中 `hasMore: false`
       
       ## 迁移步骤
       运行 `npm run migrate:up` 应用新索引
       
       ## 破坏性变更
       无。offset 参数仍受支持但标记为弃用。
       
       确认创建 PR 吗？

为这个分支创建 Pull Request，包含：

1. 70 字符以内的简洁标题
2. 2-3 个 bullet points 的变更摘要
3. 测试方法部分，描述如何验证变更
4. 破坏性变更或迁移步骤的说明
5. 关联的 Issue 链接（如果有）

如果分支还没 push，先 push。

User: PR #42 有什么审查反馈？

Claude: PR #42 有 3 条审查评论：

       1. @alice 在 src/api/search.ts:45:
          "cursor 解码应该有错误处理"
          → 建议添加 try/catch，返回 400 错误
       
       2. @bob 在 tests/api/search.test.ts:89:
          "缺少空 cursor 的测试用例"
          → 建议添加测试: 不传 cursor 时默认返回第一页
       
       3. @alice 在 migrations/...:
          "索引应该先评估对写入性能的影响"
          → 建议添加性能测试或分阶段 rollout 计划
       
       要我逐条处理这些反馈吗？

User: 提交并创建 PR

Claude: [交互式命令] /commit-push-pr
       已分析变更，执行以下操作：
       1. 暂存所有变更
       2. 生成提交信息: feat(api): add cursor-based pagination
       3. 推送到 origin/feature/pagination
       4. 创建 PR #143: https://github.com/org/repo/pull/143
       
       会话已关联到 PR #143。之后可用 `claude --from-pr 143` 恢复此会话。

User: 创建 PR 并关联 Issue #456

Claude: 已在 PR 描述中添加 `Closes #456`。
       当 PR 合并时，Issue #456 将自动关闭。

User: 触发部署工作流到 staging 环境

Claude: 正在触发 workflow "deploy.yml"...
       运行 ID: 8923456712
       状态: 排队中
       
       监控链接: https://github.com/org/repo/actions/runs/8923456712

User: 检查 CI 状态

Claude: 最新 CI 状态 (PR #143):
       - 测试: 通过 (2m 34s)
       - 类型检查: 通过 (1m 12s)
       - 构建: 通过 (3m 45s)
       - 代码覆盖率: 87% (+2%)
       
       所有检查通过，PR 可合并。

# 触发工作流并传入参数
gh workflow run deploy.yml -f environment=staging -f version=1.2.3

User: 整理最近 5 个提交。把两个 "fix typo" 提交合并到前面的功能提交里，
     并把 "add user auth" 的提交信息改得更详细一些

Claude: 正在构建 rebase 计划：

       pick    a1b2c3d  feat: add user authentication
       squash  e4f5g6h  fix typo
       squash  i7j8k9l  fix typo
       reword  m0n1o2p  add user auth
       pick    q3r4s5t  test: add auth integration tests
       
       执行 rebase 吗？

User: 把这个分支的所有提交压缩成一个，并写一个好的提交信息

Claude: 将把 8 个提交压缩为 1 个：

       新提交信息:
       feat(api): implement cursor-based pagination
       
       - Replace offset pagination with keyset pagination
       - Add composite index on (created_at, id)
       - Update OpenAPI spec with cursor parameters
       - Add comprehensive test coverage
       
       确认执行 squash 吗？

User: 把 release 分支上的数据库迁移修复 cherry-pick 到 main

Claude: 找到提交 abc1234 (fix: correct migration rollback logic)
       正在 cherry-pick 到当前分支...
       成功应用，无冲突。

User: 帮我 bisect，这个 Bug 是在最近 20 个提交里引入的

Claude: 启动 bisect...
       坏提交: HEAD (当前)
       好提交: HEAD~20
       
       测试第 10 个提交... [自动运行测试]
       结果: 测试通过 → 好提交
       
       测试第 15 个提交... [自动运行测试]
       结果: 测试失败 → 坏提交
       
       ...
       
       找到引入 Bug 的提交: a3f7d2e
       作者: Alice
       时间: 3 天前
       变更: refactor(auth): extract token validation
       
       要查看这个提交的详细 diff 吗？

User: 认证超时行为最近什么时候改过的？给我看提交和 diff

Claude: 找到相关提交：
       
       commit 8e2a1c4 (2 周前)
       Author: Bob
       
       fix(auth): reduce session timeout from 30min to 15min
       
       - Security requirement from audit #2025-04
       - Active users get refresh token automatically
       - Configurable via SESSION_TIMEOUT_MINUTES env var

User: 支付模块的回归问题是谁引入的？Bug 是 1 月 15 日报的

Claude: 分析 1 月 8 日-15 日的提交...
       
       引入回归的提交: 7d3e9f1 (1 月 12 日)
       Author: Carol
       
       feat(payment): add retry logic for failed transactions
       
       问题: 重试逻辑未正确处理已部分完成的交易，
       导致重复扣款。

# 创建新 worktree 并启动 Claude 会话
claude --worktree feature-payments

# 等价于
claude -w feature-payments

# Terminal 1: 支付功能开发
claude -w feature-payments

# Terminal 2: 认证 Bug 修复
claude -w fix-auth-timeout

# Terminal 3: 数据库重构
claude -w refactor/db-layer

# 创建新 worktree 并同时创建新分支
git worktree add ../myproject-feature-a -b feature/notifications

# 为已有分支创建 worktree
git worktree add ../myproject-hotfix hotfix/auth-timeout

# 列出所有 worktree
git worktree list

# 移除 worktree
git worktree remove ../myproject-feature-a

# 清理已不存在的 worktree 记录
git worktree prune

/projects/
├── my-project/          # 主工作树 (main 分支)
│   └── .git/            # 实际的 Git 仓库数据
│
├── auth-refactor/       # worktree (feat/auth-refactor)
│   └── .git             # 指向主仓库的链接文件
│
├── ai-chat-feature/     # worktree (feat/ai-chat)
│   └── .git
│
└── bug-fix-patch/       # worktree (fix/bug-patch)
    └── .git

# 继续最近的会话
claude -c

# 从会话列表中选择
claude --resume

# 从特定 PR 恢复会话
claude --from-pr 142

User: 在重构认证模块前创建一个检查点

Claude: 已创建检查点。
       代码状态 + 对话上下文已保存。
       可随时恢复到此状态。

## Git 规范

### 提交格式
- 使用 Conventional Commits，英文
- 分支前缀: feat/, fix/, chore/, refactor/, docs/
- PR 必须包含描述和测试清单
- 合并策略: 使用 rebase 保持线性历史

### 分支保护
- 禁止直接 push 到 main
- PR 需要至少 1 个审查人批准
- CI 通过后方可合并

### 工作流
- 功能开发: 从 main 切出 feature 分支
- 修复: 从 main 切出 fix 分支，cherry-pick 到 release
- 发布: 使用 squash merge 到 main