| name | git-commit-standards |
| description | Use when the user asks to commit code or generate a commit message AND the staged diff is non-trivial (>2 files, >30 net lines, or contains new/renamed/deleted files). For trivial commits (≤2 files, ≤30 lines, only modifications to existing files) skip this skill and write a clear `git commit` message directly — `hooks/check-git-commit-skill.js` enforces the same threshold at the Bash layer (only blocks `git commit` when staged diff exceeds it). Compose the message from the current session's edit intent first; only re-read diffs to cover gaps. Automatic stage/commit/push applies ONLY to the team-standards plugin source repository, never to business projects that merely install this plugin. |
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 不门禁。
- AI 署名机械兜底：无论大改小改、是否进本 skill，
hooks/check-commit-no-ai-signature.js 都会在 git commit 落盘前扫描提交信息，命中 Co-Authored-By 指向 AI / noreply@anthropic.com / 机器人 emoji / Generated by <AI> 即 exit 2 阻断（默认 block）。宿主/IDE 默认追加的签名会被当场拦下——别依赖"记得删"，写消息时本就不要带。
核心原则：提交信息以当前会话的实际改动意图为准；diff 只是用来兜底校验"有没有遗漏"或"有没有出现你没碰过的文件"。不要把 diff 再翻译成文字——那是重复劳动，且会丢掉只在会话里有的 WHY（设计取舍、踩坑、跟用户对齐的结论）。
team-standards 特例（只作用于插件源码仓库）： 仅当以下三项同时满足时，才自动完成 git add → git commit → git push：
- 当前 git 仓库的目录名或 remote URL 明确指向
team-standards / kpay-team-standards。
- 本次变更对象属于插件自身文件：
skills/、hooks/、.claude-plugin/、.codex-plugin/、AGENTS.md、CLAUDE.md、README.md、docs/skill-flow*、docs/dev-log/。
- 用户没有明确说"不要提交 / 不要 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: 张凯 <kai.zhang@example.com>
Bug 修复提交
fix(user-auth): 修复 token 刷新时并发导致的重复登出问题
根因：TokenRefreshServiceImpl#refresh() 未加锁，并发请求同时判断 token 过期，
导致旧 token 被多次删除，后续请求因 token 不存在而被登出。
修复方式：对 userId 维度加分布式锁，确保同一用户同一时刻只有一个刷新操作执行。
Author: 李明 <li.ming@example.com>
重构提交
refactor(payment): 替换 BeanUtils 为 MapStruct 转换器
将 PaymentServiceImpl 中 BeanUtils.copyProperties 替换为 PaymentConvert.INSTANCE 转换，
新增 com.example.payment.convert.PaymentConvert 接口。
无业务逻辑变更，仅优化转换方式，消除反射带来的类型安全隐患。
Author: 王芳 <wang.fang@example.com>
多文件变更的 body 组织方式
变更文件超过 5 个时，按模块分组描述，不逐文件列举：
feat(inventory): 新增库存预占与释放功能
【新增】
- InventoryReserveService 及其实现，支持库存预占、确认、释放三态流转
- inventory_reserve 表及对应 DO/Repository
【修改】
- OrderCreateServiceImpl#create()：下单时调用库存预占接口
- InventoryController：新增预占查询接口
【依赖】
- 新增 com.example.inventory.feign.InventoryFeignClient，需同步部署库存服务
Author: 张凯 <kai.zhang@example.com>
团队配置
Author 信息统一从当前仓库的 git 配置中读取，无需在 CLAUDE.md 中手动配置：
git config user.name
git config user.email
每位成员在本机配置好 git 用户信息即可，Skill 自动读取。若仓库未配置，则回退读取全局配置（--global）；若均为空，暂停并提示用户配置后再继续。
