SuperAPI AI 工具集

git-commit-helper

编程与开发

查看项目

更新于 11-12 13:00

技能介绍

Git 提交助手用于把本次任务产生的变更整理成干净、语义清晰的提交,目标是让每条 git log 记录都能在十秒内读懂“改了什么、属于什么性质”。

用途 把本次任务造成的变更(而不是工作区里所有改动)整理为一条或多条提交,并产出简洁的中文提交信息。仅在用户本次对话中明确下达提交指令(如“提交”“commit”“把这些变更提交一下”)时使用,含糊的“先弄完”不算。

安全边界(最高优先级)

  • 绝不自动提交,只有用户明确要求才执行,与全局 CLAUDE.md 的约束一致。
  • 绝不 git push,本技能止步于 commit;用户单独明确要求 push 时才 push。
  • 绝不 git add -A / git add .,逐文件显式 add(整目录新增可用 git add <目录>/),避免误提交无关文件。
  • 发现疑似敏感文件(密钥、.env、凭据、生产配置含密码)或垃圾文件(pycache、.venv、临时产物、编辑器备份)出现在待提交列表时,停下来向用户指出并确认处理方式,不静默提交。

工作流程

  1. 弄清“本次任务的变更”:用 git status --short 查看全貌(首列为 M 表示已暂存),用 git diff --cached --stat 检查暂存区是否已有内容,对照对话上下文判断每个文件的归属。与本次任务无关的遗留改动不碰,留在工作区并在汇报时说明。暂存区已有无关内容时停下来向用户确认(如用 git restore --staged <文件> 移出暂存或单独提交)。单个文件混有无关改动时先确认,同意后用 git add -p 只暂存本次任务的代码块。拿不准是否该提交时问,不要猜。
  2. 判断是否拆分多次提交:多阶段执行且每阶段目标独立明确时按阶段拆分,每次单独 add 该阶段文件再 commit。判断标准是拆开后每条提交能否独立讲清一件事;两批文件服务两个不同意图(一个 fix 一个 feat)则拆开;一次逻辑改动顺带产生的关联修改(如改口径同时改文档)不拆。
  3. 写提交信息:格式为“类型: 一句话简述”,中文,全角冒号亦可,跟随仓库现有风格(先 git log --oneline -5 看一眼)。类型包括 feat(新功能、新报表、新脚本、新指标)、fix(修 bug、修正错误口径、修 SQL 逻辑错误)、refactor(不改外部行为的调整)、perf(性能优化,如慢 SQL 优化、索引调整)、docs(仅文档/口径说明变更)、chore(配置、忽略规则、依赖升级等杂务)、test(仅测试变更)。简述要求一句话、动宾结构、约 30 字以内,确切覆盖内容但不罗列细节(报表类改动带上报表编号),禁止空话、长段落和多余信息。示例:“feat: 报表31新增催回率指标列及口径文档同步”“fix: 修复已取消账单未排除导致逾期统计偏高”;两阶段任务则产出两条,如“perf: 报表11渠道流量监控SQL性能优化”与“fix: 导出脚本补充批次参数校验”。
  4. 执行提交:每个提交单元依次执行 git add <文件1> <文件2> ...、git diff --cached --stat 核对暂存内容与本次意图一致、git commit -m "类型: 一句话简述";多个单元时循环“add → 核对 → commit”,保持每次暂存区干净。
  5. 收尾汇报:用 git log --oneline 列出刚产生的提交,说明未纳入提交的工作区遗留文件(如有),并明确说明未执行 push。

异常处理

  • 工作区干净、没有本次任务的变更:告知用户无可提交内容,不动 git。
  • 提交被 pre-commit hook 拦截(lint/commitlint 校验、锁文件等):如实汇报错误内容,未经用户明确要求不得用 --no-verify 绕过。
  • 仓库有冲突、处于 merge 中间态或 detached HEAD:停下来报告现状,等用户指示。
  • 用户指定的文件在 git 状态里不存在:如实说明,不伪造提交。
  • 误 add 了文件:用 git restore --staged <文件> 移出暂存,禁止用 git reset --hard 等破坏性命令回退。

适用场景与限制 适用于需要把一次任务的改动按语义整理提交、并希望提交信息统一为中文简洁格式的日常开发流程;也可用于多阶段任务的分段提交。限制在于:只在用户明确下达提交指令后使用,不自动提交、不推送;提交信息类型与格式需遵循仓库现有风格;遇到敏感或垃圾文件、暂存区无关内容、文件内混合改动等情况需先与用户确认。