开始学习
第 03 模块 · 4 节

团队 Git 规范落地

《Codex 进阶实战》03 Git 工作流集成 · 本节时长 28 分钟

← 返回课程大纲

一个人一个习惯，仓库就乱了

如果每个人（和每个 AI 会话）都按自己的习惯提交，仓库很快变乱：提交信息五花八门、分支命名混乱、合并策略各搞一套。团队 Git 规范就是统一这些，让协作有序。

这一节，把 Git 规范落地。

贯穿项目file-lib 是团队项目，而且还有 Codex 这个「不稳定成员」——每个新会话都可能按自己的习惯来。把 Git 规范写进 file-lib 的 CLAUDE.md，让 Codex 每次开工都「照着同一套规矩」走：提交信息统一 feat(scope): 描述、分支命名统一 feature/*、合并都走 PR。这一节我们给 file-lib 定这套规范并落地。

为什么必须统一 Git 规范

  • 可追溯：提交信息统一，才能快速看懂历史
  • 可预期：分支命名统一，一看就知道是干嘛的
  • 可维护：规范统一，AI 也能照着做

规范的目的是「让别人（和 AI）容易理解你的改动」。 对 file-lib 尤其重要：因为它有 AI 频繁参与，如果规范不统一，每次新会话都「重新发明」，历史记录会变成一锅粥，谁也看不懂谁，包括 Codex 自己。

三块核心规范

1. 提交信息规范

统一格式，用 Conventional Commits：

<type>(<scope>): <描述>

feat(auth): 增加登录接口
fix(login): 修复空密码导致崩溃
docs(readme): 更新安装说明

type：feat 功能 / fix 修复 / docs 文档 / refactor 重构 / test 测试。对 file-lib，scope 就是模块名：

feat(date): 新增 leapYear 闰年判断
fix(io): 修复读取不存在文件时崩溃
test(cli): 补充命令行参数测试

scope 用模块名，git log 一看就知道这次提交动了哪个模块。

2. 分支命名规范

统一命名，一看就懂：

feature/<功能>    功能分支
fix/<问题>        修复分支
release/<版本>    发布分支

file-lib 的分支就该是 feature/cli、feature/date、fix/io-crash 这种——名字本身就在说「这个分支在干嘛」。

3. 合并策略规范

统一怎么合：

  • 主干受保护，不能直接改
  • 改动走 PR + 评审
  • 合并前测试通过

file-lib 的 main 受保护，任何人（包括 Codex）都不能直接推 main，所有改动走 PR + 评审 + 测试通过再合。

让 Codex 遵守 Git 规范

Codex 可以帮你守规范——只要把它写进配置：

  • 写进 CLAUDE.md：让它知道团队 Git 规范
  • 让 Codex 按规范写提交信息：
帮我按 Conventional Commits 写提交信息，scope 用本次涉及模块

规范写进配置，AI 才会稳定遵守。 对 file-lib，在 CLAUDE.md 里加这样一段：

## Git 规范（file-lib 团队）

- 提交信息一律用 Conventional Commits：<type>(<scope>): <描述>
  scope 用本次涉及的模块名（string/io/path/date/cli…）
- 分支命名：feature/<功能>、fix/<问题>、release/<版本>
- main 受保护，任何改动走 PR + 评审 + 测试通过后合并
- 每次提交前先跑 npm test，确认测试通过

写进 CLAUDE.md，Codex 每次开工都会读到，它就能「自觉」遵守，而不是你每次都要提醒。

一个落地清单

  • [ ] 提交信息格式统一了？（type(scope): 描述）
  • [ ] 分支命名统一了？（feature/ fix/）
  • [ ] 合并策略定了？（PR + 评审 + 测试）
  • [ ] 规范写进了 CLAUDE.md，Codex 也遵守？

落地建议

  • 别一次定太多，先从「提交信息」开始
  • 规范写成文档放仓库，人人可查
  • 让 Codex 守规范：写进配置 + 让它照做
练习给 file-lib 定一套 Git 规范并让 Codex 遵守。①三步走：先定三块核心规范（提交信息 feat(scope): 描述、分支 feature/*、合并走 PR）；把规范写进 file-lib 的 CLAUDE.md；然后用一次真实提交验证 Codex 是否按规范走（提交信息 scope 用模块名、分支在 feature/*、提交前跑了测试）。②怎么判断做对了：Codex 的新提交信息符合 type(scope): 描述、它不会主动直接推 main、你不需要每次都重复提醒它规范。③卡住了怎么办：如果 Codex 还是乱写提交信息，把 CLAUDE.md 里的规范段落直接贴给它要求「严格按这个来」；如果它推 main，强调「main 受保护，先建 feature/* 分支」。

常见坑：规范定了，但没写进 AI 能读到的地方

很多人「定规范」只写在团队群里发一条消息、或口头说一句。这对人有效，对 Codex 完全无效——它看不到群消息，每个新会话都从零开始。结果规范形同虚设，Codex 还是按自己的习惯来。

避坑办法：规范必须落到 Codex 每次都能读到的地方——也就是仓库里的 CLAUDE.md。而且写完要验证它真能读到：

读一下仓库里的 CLAUDE.md，说说本项目的 Git 规范是什么。
然后按这个规范，把刚才的改动写成一条提交信息（先别提交）。

让 Codex 复述一遍规范，你就能确认它「真的读到并理解」了。规范只有写进 Codex 的「开机必读」，才叫落地。 否则只是「写在纸上、AI 看不见」。

小结

  1. 统一 Git 规范：可追溯、可预期、可维护
  2. 三块：提交信息、分支命名、合并策略
  3. 规范写进 CLAUDE.md，Codex 才能稳定遵守
  4. 别贪多，先定提交信息，再滚动扩展

下一模块进入「任务规划与提示词」。

返回《Codex 进阶实战》大纲