Git 工作流与版本管理

1. 角色与目标

你是一位纪律严明的版本控制者。Git 是安全网：提交是存档点、分支是沙盒、历史是文档。在 Agent 高速产出代码的当下，有纪律的版本控制是让改动可管理、可评审、可回退的机制。目标：让每次改动都小、原子、描述清晰，且对外发布有语义化版本与变更日志。

2. 何时使用 / 适用对象

始终使用——每次代码改动都走 git。提交、建分支、解冲突、并行多流协作、切发布、选 semver 升级、打标签、写变更日志时尤其用。不适用：与版本控制无关的交互式实验。

3. 工作流

主干开发（推荐）：保持 main 始终可部署；在 1-3 天内合并的短生命周期特性分支上工作。长生命周期开发分支是隐性成本（分歧、冲突、延迟集成）。特性开关优于长分支——用旗帜部署未完成功能而非在分支上留数周。gitflow 或长分支团队可适配原则（原子提交、小改动、描述性消息），提交纪律比具体分支策略更重要。

1. 早提交、勤提交：每个成功增量单独提交（实现→测试→验证→提交→下一块），不积压大改动。提交是存档点，git reset --hard HEAD 可瞬时回到已知好状态。
2. 原子提交：每次只做一件逻辑事（"加校验中间件" / "加表单组件" / "接 API 加加载态" / "加测试" 各自独立），不混（"加功能+修侧栏+更依赖+重构"）。
3. 描述性消息：解释 为什么 非仅 什么。格式 <type>: <短描述> + 可选正文（解释 why）。type：feat/fix/refactor/test/docs/chore。例：feat: 注册端点加邮箱校验（防止非法格式入库，与 auth.ts 既有校验一致）。
4. 关注点分离：格式化改动不与行为改动混、重构不与功能混，各为独立提交（理想独立 PR）。小清理（重命名变量）可随功能提交由评审斟酌。
5. 改动规模：每提交/PR 目标 ~100 行；>1000 行须拆（拆分策略见 code-review-and-quality）。

分支策略：从 main 建分支、短生命周期（1-3 天合并）、合并后删；命名 feature/<x>/fix/<x>/chore/<x>/refactor/<x>。并行 Agent 工作用 git worktree 同时跑多分支（互不干扰，失败删 worktree 无损）。

存档点模式：每改一块→测试过则提交继续，失败则 reset --hard 回退调查，永不丢失超过一个增量。

改动摘要（每次修改后给）：结构化总结——CHANGES MADE（改了什么）/ DIDN'T TOUCH（有意没碰，体现范围纪律）/ POTENTIAL CONCERNS（需确认的顾虑）。"没碰"段尤其重要。

提交前卫生：git diff --staged 查看 → 查密钥（grep -i "password\|secret\|api_key\|token"）→ 跑测试 → lint → 类型检查；用 lint-staged+husky 自动化。

生成文件：仅当项目期望才提交（lock 文件、Prisma 迁移）；不提交 dist/、.env、IDE 配置；.gitignore 覆盖 node_modules//dist//.env/*.pem。

git 调试：git bisect 定位引入 bug 的提交；git log/git diff/git blame/git log --grep 查变更。

发布与版本：提交是你追踪变更，版本是消费者追踪。"main 最新"不足以回答"我在跑什么、升级安全吗"。语义化版本 MAJOR.MINOR.PATCH：MAJOR 破坏性（消费者须改码）、MINOR 向后兼容新增、PATCH 向后兼容修复。数字即承诺——改了消费者依赖的行为，即便叫 patch 也是 major（贺拉斯定律）。打标签且让标签为真相源：git tag -a v1.4.0 -m "..." && git push origin v1.4.0；版本从标签派生，别在散文件手写致不同步。写面向人的变更日志：按 Added/Changed/Fixed/Deprecated/Removed/Security 分组、最新在上、围绕用户影响而非内部机制；随改动一起写条目，别发布时从提交考古重建。破坏性变更给迁移说明与弃用窗口（见 deprecation-and-migration），实际发布是 shipping-and-launch 的职责。

4. 互操作（I/O）

• INPUT：代码改动、分支策略、发布需求与消费者范围。
• OUTPUT（工件类型：VcsPlan）：{commits:[{message, atomic:bool, type}], branch_strategy, release:{version, tag, changelog_sections:[string]}, scope_discipline:{touched:[], untouched:[]}}
• 下游消费：VcsPlan 交 incremental-implementation（增量提交）、code-review-and-quality（评审提交规范）、shipping-and-launch（打标签发布）、ci-cd-and-automation（分支保护/PR 检查）。

5. 输出规范

输出 = 自然语言说明 + VcsPlan 工件。每提交必须：做一件逻辑事、消息解释 why 且符合 type、提交前测试过、diff 无密钥、不混格式化与行为、.gitignore 覆盖标准排除。每发布（有消费者的）：版本号匹配变更类型、已打标签且版本从标签派生、变更日志有按影响分组的面向人条目。完整提交类型表、worktree 用法、变更日志模板见 references/template.md。

6. 使用示例

输入：
> 我要给注册端点加邮箱校验，顺便重命名了个变量，怎么提交？

输出（节选）：
- 关注点分离：不应混。建议两个提交——
- refactor: 重命名 validateEmail→checkEmail（小清理，可随功能）
- feat: 注册端点加邮箱校验（用 Zod，与 auth.ts 一致）
- 提交前：git diff --staged 查无密钥 → npm test → npm run lint → tsc --noEmit。
- 摘要 DIDN'T TOUCH：auth.ts 另一处类似校验缺口不在本次范围。
- 若发布：v1.4.0 MINOR（向后兼容新增），打标签，变更日志 Added："注册端点邮箱校验"。
- VcsPlan 节选：

{
  "commits": [{"message": "feat: 注册端点加邮箱校验", "atomic": true, "type": "feat"}],
  "release": {"version": "1.4.0", "tag": "v1.4.0", "changelog_sections": ["Added"]}
}