204 Git 工作流规范化
使用 Codex 生成 Conventional Commits，自动化 PR 描述与变更日志，集成 Git Hooks
学习目标
一、Conventional Commits 自动生成
什么是 Conventional Commits
Conventional Commits 是一种标准化的提交信息格式：
<type>(<scope>): <description>
[optional body]
[optional footer]Codex 提交命令
# Codex 自动分析变更并生成规范提交信息
codex commit
# 预览提交信息（不实际提交）
codex commit --dry-run
# 指定提交类型
codex commit --type feat生成的提交信息示例
feat(auth): 添加双因素认证功能
- 实现 TOTP 令牌生成与验证
- 新增 /api/auth/2fa/enable 端点
- 添加恢复码备份机制
Closes #234**💡 提示：** 在 `.codex/commit.yaml` 中配置 scope 白名单，确保生成的 scope 始终符合项目规范。
二、PR 描述与变更日志自动化
自动生成 PR 描述
# 对比 main 分支生成 PR 描述
codex pr --base main
# 生成详细的变更摘要
codex pr --base main --detailed生成的 PR 描述自动包含：
- **变更概览**：一句话总结本次改动
- **详细变更**：按文件/模块分组的变更清单
- **测试计划**：建议的测试步骤
- **截图/录屏**：UI 变更的提示区域
变更日志自动生成
# 生成 CHANGELOG
codex changelog --since v1.5.0
# 按 Conventional Commits 类型分组
codex changelog --since v1.5.0 --group-by type三、Git Hooks 集成
安装各类 Hooks
# 安装 pre-commit：提交前审查
codex hook install pre-commit
# 安装 commit-msg：验证提交信息格式
codex hook install commit-msg
# 安装 pre-push：推送前运行测试
codex hook install pre-push
# 查看所有已安装的 hooks
codex hook listHook 配置示例
`.codex/hooks.yaml`：
hooks:
pre-commit:
- codex review --fail-on critical
- codex test --changed
commit-msg:
- codex commit --lint
pre-push:
- codex test --coverage --threshold 80
- codex review --security四、分支管理最佳实践
分支命名规范检查
# 检查当前分支名是否符合规范
codex branch --lint
# 根据任务自动建议分支名
codex branch --suggest "添加用户导出功能"
# → 建议：feat/user-export标准分支命名约定
| 分支类型 | 命名格式 | 示例 |
|---|---|---|
| 功能开发 | `feat/<描述>` | `feat/payment-integration` |
| Bug 修复 | `fix/<描述>` | `fix/login-timeout` |
| 文档更新 | `docs/<描述>` | `docs/api-reference` |
| 重构 | `refactor/<描述>` | `refactor/auth-module` |
| 发布 | `release/<版本>` | `release/v2.0.0` |
五、PR 工作流中的代码审查自动化
完整 PR 工作流
# 1. 从 main 创建功能分支
git checkout -b feat/new-feature main
# 2. 开发完成后，Codex 审查 + 生成提交
codex review
codex commit
# 3. 推送并创建 PR
git push origin feat/new-feature
codex pr --base main --assignee @team-lead
# 4. PR 合并后，生成变更日志
codex changelog --since last-release六、本课总结
**核心要点：**
- `codex commit` 自动分析变更并生成 Conventional Commits
- `codex pr` 自动生成结构化 PR 描述
- Git Hooks 集成让审查、测试、提交验证全流程自动化
- 分支命名规范确保仓库整洁可追溯
- 完整 PR 工作流从审查到变更日志一气呵成
**下一步：** 学习 CI/CD 集成 → [205 CI/CD 集成](module3-205.md)