18 - Git 工作流

1. Git 纪律核心价值

价值	说明
可追溯性	每次提交都能回答"改了什么、为什么改"
可回滚性	任何一次提交都可以安全 revert，不会引发连锁问题
可恢复性	意外中断时，通过 WIP commit + handoff 文件恢复上下文
可审查性	提交粒度适中，代码审查可以逐 commit 进行
可调试性	出问题时可用 bisect/blame 快速定位引入点
可协作性	即使是个人项目，未来的自己也是"另一个协作者"

2. 原子提交原则

2.1 单一职责

每个 commit 只做一件事。判断标准：commit message 能用一句话说清楚。

✅ feat(auth): add JWT token refresh endpoint
✅ fix(user): prevent duplicate email registration
✅ test(order): add integration tests for checkout flow

❌ feat(auth): add login, fix user page, update deps
❌ misc: various fixes and improvements

2.2 测试通过才提交

改代码 → 跑测试 → 全绿 → 提交
                → 红 → 修复 → 重新跑测试 → 全绿 → 提交

不允许提交已知会导致测试失败的代码。唯一例外：WIP commit（见 §6）。

2.3 只提交已验证的改动

AI 生成的代码必须经过验证才能提交：

至少运行过一次相关测试
至少阅读过 diff 确认改动符合预期
不提交未理解的代码

2.4 横切面拆分

当一次改动涉及多个关注点时，按关注点拆分为多个 commit：

场景：新增用户注册功能

拆分方式：
  commit 1: feat(db): add User table migration
  commit 2: feat(user): add user registration service
  commit 3: feat(api): add POST /api/users endpoint
  commit 4: test(user): add registration unit and integration tests
  commit 5: feat(ui): add registration form component

3. Conventional Commits 格式

3.1 格式规范

type(scope): subject

[可选 body]

[可选 footer]

3.2 Type 枚举

Type	用途	示例
`feat`	新功能	feat(auth): add OAuth login
`fix`	Bug 修复	fix(cart): correct price calculation
`refactor`	重构（不改行为）	refactor(user): extract validation logic
`test`	测试	test(order): add checkout edge cases
`docs`	文档	docs(api): update endpoint descriptions
`chore`	工具/构建/依赖	chore(deps): upgrade Next.js to 15.2
`style`	格式调整（不改逻辑）	style: apply prettier formatting
`perf`	性能优化	perf(query): add database index for user lookup
`ci`	CI/CD 配置	ci: add test coverage threshold

3.3 Scope 映射

按项目模块定义 scope，写入 CLAUDE.md：

markdown

## Git Scope 映射

按项目实际模块定义，例如：
- auth — 认证模块
- user — 用户模块
- api — API 层
- db — 数据库/迁移
- ui — 前端组件
- deps — 依赖管理
- config — 配置文件

3.4 Subject 规则

英文，小写开头
祈使句语气（add, fix, update，不是 added, fixed, updated）
不超过 50 字符
不加句号
说明 why 而非 what（改动本身在 diff 中可见）

4. 暂存区纪律

4.1 按意图暂存

逐文件添加，不用 git add . 或 git add -A：

bash

# ✅ 逐个添加相关文件
git add src/services/user.ts
git add src/routes/user.ts
git add tests/user.test.ts

# ❌ 全量添加（可能混入无关文件、敏感文件）
git add .
git add -A

4.2 禁止提交文件清单

写入 .gitignore 且提交前复查：

.env / .env.local / .env.production  — 环境变量
*.key / *.pem                        — 密钥文件
node_modules/                        — 依赖目录
.DS_Store                            — 系统文件
*.log                                — 日志文件
dist/ / .next/ / build/              — 构建产物

4.3 提交前审查

每次 git commit 前执行：

bash

git diff --staged      # 审查即将提交的内容
git diff --check       # 检查空白错误

AI 辅助开发时，在 CLAUDE.md 中写入：

markdown

- MUST 提交前运行 `git diff --staged` 确认暂存内容
- NEVER 使用 `git add .` 或 `git add -A`
- NEVER 提交 .env 或包含密钥的文件

5. 分支策略

5.1 命名规范

前缀	用途	示例
`feat/`	新功能	feat/user-auth
`fix/`	Bug 修复	fix/login-redirect
`test/`	测试补充	test/order-coverage
`wip/`	实验性工作	wip/new-ui-approach
`release/`	发布准备	release/v1.2.0

5.2 个人项目简化版

个人项目不需要 Git Flow 的完整分支模型。推荐：

main ──────────────────────────────── 稳定可部署
  └── feat/xxx ─── 开发 ─── 合并回 main
  └── fix/xxx ──── 修复 ─── 合并回 main

main 始终可部署
功能分支从 main 拉出，完成后合并回 main
小改动可以直接在 main 上提交
实验性工作用 wip/ 分支，确认方案后合并或丢弃

6. WIP Commit 模板

当需要暂停工作（下班、切换任务、上下文接近上限）时，使用 WIP commit 保存进度。

6.1 格式

wip(scope): 简要描述当前状态

## Done
- [x] 已完成的工作项 1
- [x] 已完成的工作项 2

## Next
- [ ] 下一步要做的事 1
- [ ] 下一步要做的事 2

## Risk
- 已知风险或阻塞项

## Verify
- 恢复后需要运行的验证命令

6.2 示例

wip(auth): JWT refresh endpoint - service done, tests pending

## Done
- [x] Token refresh service with rotation logic
- [x] Refresh token database model

## Next
- [ ] Add API route handler
- [ ] Write integration tests
- [ ] Update API documentation

## Risk
- Token expiry edge case needs discussion

## Verify
- npm run test -- --grep "auth"
- npm run lint

6.3 恢复后处理

恢复工作后，WIP commit 应该被后续的正式 commit 覆盖。不要让 WIP commit 进入 main 分支的最终历史。

完整的会话检查点流程详见 19-上下文管理执行手册 §2-§3

7. 绿色基线 Tag

当 E2E 测试全部通过时，打一个绿色基线标签：

bash

# 打标签
git tag e2e-green-$(date +%Y%m%d)

# 查看所有绿色基线
git tag -l "e2e-green-*"

# 回到最近的绿色基线
git log --oneline e2e-green-$(git tag -l "e2e-green-*" | tail -1)..HEAD

用途：

标记"已知稳定"的代码状态
大重构前打一个，失败时可以快速回到已知好的状态
查看从上次绿色基线到现在的所有变更

8. 用 Git 调试

8.1 git bisect — 定位引入 Bug 的提交

bash

git bisect start
git bisect bad                    # 当前版本有 Bug
git bisect good e2e-green-0220   # 这个版本没有 Bug
# Git 自动切换到中间的 commit，测试后标记 good/bad
# 重复直到找到引入 Bug 的 commit
git bisect reset                 # 回到原来的分支

前提：原子提交越好，bisect 越快越精确。

8.2 git blame — 追溯特定代码的来源

bash

git blame src/services/user.ts       # 每行代码的最后修改者和提交
git blame -L 50,70 src/services/user.ts  # 只看第 50-70 行

8.3 git show — 查看特定提交的详情

bash

git show <commit-sha>             # 查看某次提交的完整 diff
git show <commit-sha>:path/file   # 查看某次提交时某个文件的内容

9. 提交前检查清单

写入 CLAUDE.md 或作为 /commit Skill 的前置步骤：

markdown

## 提交前检查清单

1. [ ] `git diff --staged` — 暂存内容符合预期
2. [ ] `npm run lint` — 零警告
3. [ ] `npx tsc --noEmit` — 零类型错误
4. [ ] `npm run test` — 全部通过
5. [ ] `git diff --check` — 无空白错误
6. [ ] commit message 符合 Conventional Commits 格式
7. [ ] 不包含 .env、密钥、日志等敏感文件
8. [ ] 单次提交不超过 10 个文件（超出考虑拆分）

10. 与其他子系统的关系

doc-10 可靠性 ──→ §5 回归验证 + 提交前全量验证
doc-19 上下文管理 ──→ WIP commit + Handoff 的执行 SOP
/commit Skill ──→ 本文档的执行自动化（格式+检查+提交）
/checkpoint Skill ──→ WIP commit + handoff 的一键操作
CLAUDE.md ──→ 写入暂存区纪律、scope 映射、提交前检查

18 - Git 工作流 ​

1. Git 纪律核心价值 ​

2. 原子提交原则 ​

2.1 单一职责 ​

2.2 测试通过才提交 ​

2.3 只提交已验证的改动 ​

2.4 横切面拆分 ​

3. Conventional Commits 格式 ​

3.1 格式规范 ​

3.2 Type 枚举 ​

3.3 Scope 映射 ​

3.4 Subject 规则 ​

4. 暂存区纪律 ​

4.1 按意图暂存 ​

4.2 禁止提交文件清单 ​

4.3 提交前审查 ​

5. 分支策略 ​

5.1 命名规范 ​

5.2 个人项目简化版 ​

6. WIP Commit 模板 ​

6.1 格式 ​

6.2 示例 ​

6.3 恢复后处理 ​

7. 绿色基线 Tag ​

8. 用 Git 调试 ​

8.1 git bisect — 定位引入 Bug 的提交 ​

8.2 git blame — 追溯特定代码的来源 ​

8.3 git show — 查看特定提交的详情 ​

9. 提交前检查清单 ​

10. 与其他子系统的关系 ​

18 - Git 工作流

1. Git 纪律核心价值

2. 原子提交原则

2.1 单一职责

2.2 测试通过才提交

2.3 只提交已验证的改动

2.4 横切面拆分

3. Conventional Commits 格式

3.1 格式规范

3.2 Type 枚举

3.3 Scope 映射

3.4 Subject 规则

4. 暂存区纪律

4.1 按意图暂存

4.2 禁止提交文件清单

4.3 提交前审查

5. 分支策略

5.1 命名规范

5.2 个人项目简化版

6. WIP Commit 模板

6.1 格式

6.2 示例

6.3 恢复后处理

7. 绿色基线 Tag

8. 用 Git 调试

8.1 git bisect — 定位引入 Bug 的提交

8.2 git blame — 追溯特定代码的来源

8.3 git show — 查看特定提交的详情

9. 提交前检查清单

10. 与其他子系统的关系