git-commit-standards

Git 提交规范

何时进入本 skill

hooks/check-git-commit-skill.js 已经替你做了路由：

• 小改放行：≤ 2 文件 ∧ insertions+deletions ≤ 30 ∧ 全部为 M（仅修改现有文件，无 A/R/D）→ hook 直接放过 git commit，根本不会进本 skill，模型用一句清晰的 commit message 提交即可。阈值可用环境变量 TEAM_STANDARDS_TRIVIAL_FILES / TEAM_STANDARDS_TRIVIAL_LINES 调整。
• 大改强制：以上任一不满足时，hook 检查当前 transcript 是否含 "skill":"team-standards:git-commit-standards" 调用记录，未调用直接 exit 2 阻断 → 你看到这套五步清单就意味着本次属于"大改"。
• git push 不再拦截：commit 已落地，push 不门禁。

核心原则：提交信息以当前会话的实际改动意图为准；diff 只是用来兜底校验"有没有遗漏"或"有没有出现你没碰过的文件"。不要把 diff 再翻译成文字——那是重复劳动，且会丢掉只在会话里有的 WHY（设计取舍、踩坑、跟用户对齐的结论）。

team-standards 特例（只作用于插件源码仓库）： 仅当以下三项同时满足时，才自动完成 git add → git commit → git push：

1. 当前 git 仓库的目录名或 remote URL 明确指向 team-standards / kpay-team-standards。
2. 本次变更对象属于插件自身文件：skills/、hooks/、.claude-plugin/、.codex-plugin/、AGENTS.md、CLAUDE.md、README.md、docs/skill-flow*、docs/dev-log/。
3. 用户没有明确说"不要提交 / 不要 push / 只改不提交"。

业务项目即使安装了 team-standards plugin，也绝不触发自动 stage、自动 commit、自动 push 或自动版本号递增。业务项目提交必须走普通确认流程。

授权边界： 自动 push 是本 skill 的行为规则，不等于可以绕过 Codex / Claude / IDE 宿主的命令审批。若宿主环境对 git push 启用了每次确认，仍会弹授权；只有宿主支持并保存了对应命令授权时，后续才可能免确认。

---

提交信息格式

<type>(<scope>): <标题——用一句话说清楚做了什么>

<body——中文说明，解释为什么这样改、改了哪些地方、解决了什么问题>

Author: <姓名> <邮箱>

格式规则

部分	规则
type	必填，见下表
scope	可选，填模块/功能名，如 order、user-auth
标题	不超过 72 字符；动词开头；不加句号
body	必填；中文；说清楚改了什么、为什么改；多点用换行
Author	必填；格式：姓名 <邮箱>；只填真实提交者，禁止添加任何 AI 工具署名

---

Type 类型表

Type	含义	示例场景
feat	新功能	新增接口、新增业务流程
fix	Bug 修复	修复空指针、修复逻辑错误
refactor	重构	不改变功能的代码改善，如提取方法、替换实现
perf	性能优化	优化 SQL、减少 N+1 查询、加缓存
docs	文档	修改注释、更新 Javadoc、更新设计文档
test	测试	新增/修改单元测试或集成测试
style	格式	不影响逻辑的格式调整（空格、换行、命名）
chore	杂项	依赖升级、配置修改、构建脚本
ci	CI/CD	流水线配置变更
revert	回滚	回滚某次提交

---

五步执行清单（每步完成后才能进入下一步）

收到提交任务时，立即用 TodoWrite 创建以下五条待办项，逐条完成后标记：

[ ] 第一步：读取 git config user.name / user.email
[ ] 第二步：基于会话上下文确认改动范围；用 git diff --staged --name-only 兜底校验
[ ] 第三步：用会话已知的改动意图直接写 type / scope / body
[ ] 第四步：输出完整提交信息；team-standards 自动收尾场景记录"自动确认"
[ ] 第五步：执行 git commit；team-standards 自动收尾场景继续执行 git push

第一步：获取提交者信息

git config user.name
git config user.email

• 两项均有值 → 记为 Author，继续第二步
• 任意一项为空 → 暂停，告知用户缺失哪项，等用户补充后再继续，禁止使用占位值

第二步：基于会话上下文确认改动范围

优先用会话上下文，不要直接全量读 diff。

a) 从对话历史归纳本次会话中你 Edit/Write 过的所有源文件，以及每个文件的改动意图。

b) 跑一次轻量校验：

git status --short
git diff --staged --name-only

c) 比对 staged 文件列表 vs 你在本次会话改过的文件：

情况	处理
staged ⊆ 会话改过的文件	直接进第三步，不用读完整 diff
出现你没碰过的文件（用户在 IDE 手动改 / 之前残留的 stage）	对这部分文件跑 git diff --staged -- <file>，必要时问用户是否要一起提
工作区有未暂存变更	team-standards 自动收尾场景执行 git add -A 后重新校验；其它场景暂停让用户先 git add
当前会话被压缩过（关键改动上下文已丢失）	降级：跑完整 git diff --staged + --stat 重建上下文
无任何变更	停止，不提交空 commit

第三步：基于会话意图写 type / scope / body

直接用会话里已知的改动目的填：

• 新增了类/方法/接口 → feat
• 修改了已有逻辑修复问题 → fix
• 改了代码结构但功能不变 → refactor
• 只改了注释/文档 → docs
• 改了测试文件 → test
• 改了 pom.xml/build 配置 → chore
• 涉及多个 type → 选主要的，其余在 body 中说明

scope 从变更的包路径或模块名中提取（取最小公共前缀）。

body 段重点：

• 写为什么这样改（设计取舍、踩坑、跟用户对齐的结论）——这部分只在会话里有
• 不要把 diff 当成 changelog 翻译一遍——文件名、方法名 git 本身会显示
• 第二步 c) 兜底发现的"你没碰过的文件"，body 里单独标一段说明来源

第四步：输出提交信息并处理确认

将完整提交信息输出给用户。

• 普通场景：明确询问"是否确认提交"，收到确认后才能进入第五步。
• team-standards 插件源码仓库自动收尾场景：记录"自动确认：team-standards 源码仓库收尾规则授权"，直接进入第五步。

普通场景禁止在未收到用户确认的情况下执行 git commit。

第五步：执行 git commit

使用 HEREDOC 方式传入提交信息：

git commit -m "$(cat <<'EOF'
type(scope): 标题

body 中文说明

Author: 姓名 <邮箱>
EOF
)"

提交信息末尾禁止追加任何内容，包括但不限于：

• Co-Authored-By: Claude ...
• Generated by ...
• 🤖 ...

team-standards 插件源码仓库自动收尾场景在 commit 成功后继续执行：

git push

push 前必须确认三处 manifest 版本号完全一致——.claude-plugin/plugin.json、.claude-plugin/marketplace.json、.codex-plugin/plugin.json，三处缺一不可（CI version-sync-check 对三处强校验，.codex-plugin/plugin.json 是常见漏升点）。若本次改动含 CLAUDE.md，push 前还须运行 node scripts/sync-agents.js 重新生成 AGENTS.md（CI agents-sync-check 强校验，无 hook 自动同步）。该版本号递增与同步要求只适用于 team-standards 插件源码仓库，禁止在业务项目中套用。

---

Red Flags

出现以下念头时立即停止，回到对应步骤：

念头	现实
"我已经改完了，直接全量 git diff --staged 再读一遍才放心"	第二步明确：会话上下文优先，diff 只兜底；全量读是重复劳动
"git config 肯定有值，跳过读取"	必须执行命令确认，不能假设
"提交信息很简单，不用确认直接提交"	普通场景第四步确认是刚性要求；只有 team-standards 仓库自动收尾才免确认
"业务项目安装了 team-standards，所以也自动提交推送"	错。自动提交推送只作用于 team-standards 插件源码仓库
"team-standards 改完先放着下次一起提"	插件源码仓库要求小步提交并自动 push，避免累计大包变更
"加上 Co-Authored-By 是好习惯"	这是明确禁止的行为，立即删除
"用户让我快点，可以省几步"	用户说"提交"是 WHAT，流程是 HOW，不可跳过

---

示例

新功能提交

feat(order): 新增订单支付状态回调接口

新增 PayCallbackController#callback() 接口，接收支付网关异步通知。
实现 OrderPayService#handleCallback() 处理支付结果，包含：
- 幂等校验（基于 payOrderNo 去重）
- 订单状态流转（待支付→已支付/支付失败）
- 发布 OrderPaidEvent 触发后续业务

Author: 张凯 <[email protected]>

Bug 修复提交

fix(user-auth): 修复 token 刷新时并发导致的重复登出问题

根因：TokenRefreshServiceImpl#refresh() 未加锁，并发请求同时判断 token 过期，
导致旧 token 被多次删除，后续请求因 token 不存在而被登出。
修复方式：对 userId 维度加分布式锁，确保同一用户同一时刻只有一个刷新操作执行。

Author: 李明 <[email protected]>

重构提交

refactor(payment): 替换 BeanUtils 为 MapStruct 转换器

将 PaymentServiceImpl 中 BeanUtils.copyProperties 替换为 PaymentConvert.INSTANCE 转换，
新增 com.example.payment.convert.PaymentConvert 接口。
无业务逻辑变更，仅优化转换方式，消除反射带来的类型安全隐患。

Author: 王芳 <[email protected]>

---

多文件变更的 body 组织方式

变更文件超过 5 个时，按模块分组描述，不逐文件列举：

feat(inventory): 新增库存预占与释放功能

【新增】
- InventoryReserveService 及其实现，支持库存预占、确认、释放三态流转
- inventory_reserve 表及对应 DO/Repository

【修改】
- OrderCreateServiceImpl#create()：下单时调用库存预占接口
- InventoryController：新增预占查询接口

【依赖】
- 新增 com.example.inventory.feign.InventoryFeignClient，需同步部署库存服务

Author: 张凯 <[email protected]>

---

团队配置

Author 信息统一从当前仓库的 git 配置中读取，无需在 CLAUDE.md 中手动配置：

git config user.name    # 例：张凯
git config user.email   # 例：[email protected]

每位成员在本机配置好 git 用户信息即可，Skill 自动读取。若仓库未配置，则回退读取全局配置（--global）；若均为空，暂停并提示用户配置后再继续。