SDD + Harness 四周学习计划 · Week 4 · Day 24（全计划第 24 课）
今日主题：团队流程：分支规范（feat/fix/chore）、commit 规范、review/merge、release 与 SemVer
建议用时：60–90 分钟 ｜ 前置：Day 23 的 commands 与 config.sh + Day 13 的 hook 实操
输出物：一页纸《团队 Git 协作规范》（分支 / commit / review / merge / release 五块）
0. 一句话剧透
Day 23 你固化了”单次开发怎么走”，今天往上加一层：多人协作时仓库怎么流转。sdd-harness 给了一套很克制的规范——从 develop 切分支、命名 type/short-description、squash merge 回 develop、main 只做发布、release/vX.Y.Z 流程。今天把这条链走通，并搞懂 pre-commit hook 的分支豁免为什么和分支规范是配套的：分支名是 hook 判断”该不该查 spec”的唯一线索。
1. 今日目标（学完你能做到）
- 能画出 develop / feature / main / release 四条分支的生命周期
- 能说出分支命名规范（type/short-description）和 type 的合法集合（feat/fix/chore/docs/hotfix）
- 能讲清 squash merge 解决什么问题、main 为什么只做发布
- 能说清 release/vX.Y.Z → tag → back-merge 的完整流程与 SemVer 三段号规则
- 完成动手练：写一页纸《团队 Git 协作规范》
2. 学习动线
| 步骤 | 内容 | 用时 |
|---|---|---|
| 1 | 精读「3」：分支规范与 hook 豁免的配套 | 15 分钟 |
| 2 | 精读「4」：commit 规范（type/short-description + spec-first） | 10 分钟 |
| 3 | 精读「5」：review/merge（书面审查 + squash merge + main 只发布） | 20 分钟 |
| 4 | 精读「6」：release 流程与 SemVer | 15 分钟 |
| 5 | 动手练「7」：写一页纸规范 | 15 分钟 |
| 6 | 自测「8」+ 打卡 | 10 分钟 |
3. 分支规范
3.1 四条分支各自干什么
| 分支 | 用途 | 谁在上面动 |
|---|---|---|
| develop | 集成分支，日常合入目标 | 团队所有人（经 squash merge） |
| feat/（feature/） | 功能开发，从 develop 切出 | 开发者个人 |
| fix/* chore/* docs/* hotfix/* | 修复 / 杂务 / 文档 / 紧急修复 | 开发者个人 |
| main | 只做发布，不接受直接提交 | 发布者 |
| release/vX.Y.Z | 发布准备分支 | 发布者 |
3.2 为什么 hook 豁免和分支规范是配套的
Day 13 的 hook 行为回顾：feat/* 或 feature/* 分支上改代码但不碰 .ai/specs/ 或 .ai/adrs/ → 提交被拒；chore/* docs/* fix/* hotfix/* 豁免；SH_SDD_SKIP=1 显式例外且 shell 历史留痕。
含义很清晰：
- feature 分支 = 功能变更 = 必须带 spec（spec-first 的落地点）
- chore/fix/docs/hotfix 分支 = 非功能性或紧急变更 = 豁免
这套规则只有建立在”大家按规范起分支名”之上才成立——分支名是 hook 判断意图的唯一线索。 你起个 abc 分支干功能开发的活，hook 既不拦也不豁免，规范就失效了。
3.3 命名规范：type/short-description
示例：feat/user-login、fix/pagination-off-by-one、chore/update-deps、docs/readme-zh、hotfix/refund-npe
- type：feat / fix / chore / docs / hotfix（与 hook 豁免集合对齐）
- short-description：短横线分隔，≤3–4 个词，描述意图不描述过程
4. commit 规范
4.1 格式
1
<type>/<short-description>: 一句话说明
示例：feat/user-login: 实现邮箱+密码登录接口并返回 token
4.2 spec-first 提交
功能分支上，spec 与代码同一批提交（Day 13 练过）：先有 .ai/specs/<功能>.md，再有代码。这样任何一次 checkout 都能看到”这份代码的契约”。
4.3 commit 粒度
一个 commit 一个逻辑变更；避免”实现 + 顺手改格式 + 修了个 typo”混在一个 commit——review 时说不清。AI 生成的代码尤其要检查这一点。
5. review / merge
5.1 书面审查
review 不是口头”我看了”，要留记录：审查人、日期、结论（approve / request-changes）、遗留问题。对应 Day 23 的 review.md command；Day 25 会专门展开”书面”二字的分量。
5.2 squash merge：为什么”压扁”
功能分支上可能有十几个小 commit（AI 生成尤其如此），直接合入 develop 会让历史变成噪音。squash merge 把它们压成一个 commit 合入 develop——develop 历史 = 一条条”完整功能”，回滚时以功能为单位，而不是在一堆碎片里找。
5.3 main 只做发布
main 不接受开发提交，只有 release 流程能碰它 → main 永远处于可发布状态，这是”main 保护”的核心。
6. release 与 SemVer
6.1 release/vX.Y.Z 流程（sdd-harness 规范）
- 从 develop 切
release/vX.Y.Z - 在 release 分支上只做发布准备（版本号、changelog、回归），不做新功能
- squash merge 到 main
- 打 tag
vX.Y.Z - back-merge 回 develop（把版本号等变更同步回去，避免 develop 落后）
6.2 SemVer 三段号
主版本.次版本.修订号（如 1.4.2）：
| 段 | 什么时候升 | 示例场景 |
|---|---|---|
| 主版本 | 不兼容的 API 变更 | 删接口、改请求语义 |
| 次版本 | 向后兼容的功能新增 | 加字段、加接口 |
| 修订号 | 向后兼容的缺陷修复 | 修 bug、修文案 |
一句话记忆：破坏性改动升主版，新功能升次版，修 bug 升修订版。
7. 动手练（约 15–20 分钟）
写一页纸《团队 Git 协作规范》（Markdown，可放进你的 .ai/CONTEXT.md 或单独 docs/）：
- 分支规范：四条分支职责 + 命名 type/short-description + hook 豁免对照表
- commit 规范：格式 + spec-first + 粒度
- review/merge：书面审查要求 + squash merge + main 保护
- release：vX.Y.Z 六步 + SemVer 规则
- 用 3–5 个真实 commit 消息做示范
打卡：文件存盘。Day 26 大作业将按这份规范实际走一遍。
8. 自测题
- 四条分支各自干什么？main 为什么不接受开发提交？
- 分支命名 type/short-description 中，type 的合法集合是什么？
- 为什么 hook 的豁免规则依赖分支命名规范？（一句话）
- squash merge 解决什么问题？合入后 develop 历史长什么样？
- release/vX.Y.Z 的完整流程是什么？back-merge 是干什么的？
- SemVer 三段号各自什么时候升？
- 一个 commit 消息的规范格式是什么？spec-first 提交是什么意思？
- 如果你的修复属于 hotfix，它在 hook 检查中的待遇是什么？
提示：第 3 题答案在 3.2；第 5 题在 6.1；第 6 题在 6.2；第 8 题在 3.2 的 hook 行为回顾。
9. 延伸阅读
- sdd-harness 仓库（分支与 release 规范的出处）：https://github.com/iMark21/sdd-harness
- 腾讯云《出码率90%却没提效？》（从”个人技能”到”团队级工程能力”的动机）：https://cloud.tencent.com/developer/article/2669269
本工作纸依据《SDD+Harness四周学习计划.md》Day 24 主题编制。整理日期：2026-09-09
