Git 提交与分支规范

定位:提交信息/颗粒度/分支/tag/发布联动的 Git 纪律。完整守卫方法论见技能 .claude/skills/git-guardrails-claude-code。

负面清单(Do Not)

[禁止] 未经用户明确同意执行 git commit / git push(Hook 强制拦截)
[禁止] 使用英文或无关描述提交信息
[禁止] 一次提交混入多个无关功能(保持颗粒度)
[禁止] 提交包含密钥、本地环境文件副本、构建产物
[禁止] 提交 config.json(含 masterKey/databaseURI)与 .env(敏感配置不入 git,见 10-安全与环境部署.md)
[禁止] 直接提交到 master 后又强制覆盖历史

必须规则(提交信息)

[必须] 中文提交信息,格式 <type>: <中文描述>,一行内简明说明"做了什么、为什么"。
[必须] 提交前缀统一:feat 新功能/fix 修复 bug/docs 文档/refactor 重构(不改变行为)/test 测试/chore 构建工具依赖/config 配置 env/style 格式(无逻辑变更)。
[必须] 提交颗粒度:一个功能/一个修复一次提交;相关修改一起提交,无关修改分开。
[必须] 提交前检查:lint 通过、测试通过(前端+后端)、生产构建通过(ng build --configuration production,确认 Mock 开关已关闭、数据走真实 fmode-ng 查询)、无调试残留、无密钥、config.json/.env 未进入提交(gitignore 已忽略);提交信息引用对应修改留痕(如 docs/07-records/2026-08-01-xxx)。

必须规则(发布联动)

[必须] 提交即发布流程:提交并通过用户确认推送后即进入发布流程(手动 git 模式:服务器 git pull → 装依赖 → pnpm build → pm2 restart → 验证;完整步骤见 10-安全与环境部署.md);AI 完成提交后主动向用户给出发布操作清单,不等用户追问。
[必须] 发布类提交特别检查:涉及环境开关(鉴权/SKIP/dev 接口)、依赖变更、Nginx 代理、前端缓存结构的提交,发布时逐项确认:生产 env 未受影响、新依赖已安装、Nginx 是否需重载、版本戳是否需要 bump(仅缓存结构变更时)。

必须规则(分支与 tag)

[必须] master 为稳定分支:始终可部署;直接开发功能用 feature/功能名分支,完成后合并回 master。
[必须] 禁止自动提交:AI 需要提交时,先向用户说明提交内容与信息,由用户确认后手动执行(或在用户明确指示下执行)。
[必须] tag 标签统一:版本发布打 tag,格式 v1.2.3(SemVer),与 package.json 版本联动;CHANGELOG 同步记录。
[必须] 标签词汇统一:需求/文档分类标签(功能/缺陷/优化)使用统一词汇表,禁止同义混用(如"bug"与"缺陷"并存)。
[必须] 提交前自查清单(每次改动后自检):遵循最小改动无无关文件变动/符合本套规范(分层/命名/负面清单)/测试与 lint 通过/文档同步、留痕已写/无密钥、无调试残留、无死代码。

建议规则

[建议] 分支命名:feature/xxx、fix/xxx、refactor/xxx。
[建议] AI Review:合并前可用 code-review 能力对 diff 做一次审查,发现问题先修复再提交。