| name | git-commit |
| description | 创建符合规范的 git 提交消息,并在提交前 review 将提交的变更。优先遵循项目现有提交规范,支持 Conventional Commits 格式。使用场景:用户要求创建提交、编写提交消息、提交前检查变更 |
Git 提交消息
创建清晰、规范的 git 提交消息。优先遵循项目现有风格,其次参考 Conventional Commits 标准。
执行流程
步骤 1:确定项目规范(首次)
如果对话中已通过本技能确定过项目规范,直接复用,跳过本步骤。
首次执行时并行收集以下信息:
git log -5 --pretty=format:"%s"
git branch --show-current
同时检查项目根目录是否存在 commitlint 配置(.commitlintrc.*、commitlint.config.*、package.json 中的 "commitlint" 字段)。
确定提交格式规范
按优先级取第一个匹配:
- commitlint 配置:找到则严格按其规则生成,提取
extends(预设)、parserPreset(解析模式)、rules(type-enum、scope-enum、header-max-length 等)
- 提交历史风格:从最近 5 条提交推断类型名称(
feat/feature)、语言(中文/英文)、issue 引用位置(subject 中/footer 中)
- Conventional Commits:以上均无明确规范时使用默认标准
提交类型
优先使用项目已有类型。无明确类型时参考:
| 类型 | 说明 |
|---|
feat / feature | 新功能 |
fix / bugfix | Bug 修复 |
docs | 文档变更 |
style | 代码格式(不影响功能) |
refactor | 重构(功能不变) |
perf | 性能优化 |
test | 测试相关 |
chore | 构建/工具链 |
提取分支关联的 Issue
从当前分支名中提取 issue 编号:
feature/#1254 → #1254
fix/123-login-blank → #123
feat/new-feature-456 → #456
issue/789 → #789
feature/PROJ-123-desc → #PROJ-123
解析到 issue 编号时,按上述确定的引用风格放置(subject 中或 footer 中)。
步骤 2:收集变更数据
一次并行执行以下命令,不要分步调用:
暂存区有内容时:
git status --short
git diff --cached --stat
git diff --cached
git diff --cached --check
git log @{u}..HEAD --oneline 2>/dev/null
暂存区为空时:
git status --short
git diff --stat
git diff
git diff --check
git log @{u}..HEAD --oneline 2>/dev/null
基于收集的数据一次性完成以下判断:
模块判断
属于同一模块(一起提交):
- 同一功能的不同部分(API、类型、工具函数)
- 功能开发 + 相关文档/配置/依赖
不搭界(分开提交):
处理逻辑
所有变更属于同一模块:直接提交。
大部分属于同一模块,少量不搭界:
主要模块:用户模块
不相关变更(建议暂不提交):
- src/api/orders.ts (订单模块)
跳过不相关内容,仅提交用户模块相关变更?(y/n)
多个模块变更相当:
用户模块:70行 | 订单模块:90行
建议先提交变更较多的模块,是否仅提交订单模块?(y/n/all)
合并提交检查
基于 git log @{u}..HEAD 结果判断。仅在有领先远程的本地提交时合并。合并条件:同一类型 + 相同模块文件、同一 bug 的修复、文档连续更新。其他情况不合并。
步骤 3:提交前 Review
用户明确要求跳过 review 时(如"不 review"、"直接提交"),跳过本步骤。
直接复用步骤 2 已收集的 diff 数据,不要重新执行 git diff 命令。
先判断当前运行环境使用的 agent 及其能力,按以下优先级执行:
- 支持 subagent 的 agent:必须启动独立 subagent 执行 review,避免主线程上下文、用户后续追问或已有结论干扰判断;如果 subagent 环境也支持内置 review 能力,由 subagent 优先使用内置能力。
- 不支持 subagent,但带内置 review 能力的 agent:使用该 agent 自带的 review 能力检查本次将提交的变更。
- 无内置 review 能力或无法确认能力的 agent:直接基于步骤 2 收集的 diff 进行 review。
- 用户明确要求使用某种 review 方式:遵循用户要求,同时保留下方阻塞问题处理逻辑。
优先 review 暂存区;如果没有暂存内容,则 review 工作区变更;如果步骤 2 决定拆分提交,只 review 将纳入本次提交的文件。
Subagent Review 要求
使用 subagent review 时,只传递客观材料:本次提交范围、git diff --stat、完整 diff、相关用户需求和本步骤检查项。不要传递主线程的判断结论、期望结果或提交消息草稿。subagent 输出应优先列出阻塞问题,其次列出非阻塞风险;无问题时明确说明未发现阻塞问题。
Review 检查项
- 敏感信息:密码、密钥、token、私有证书、真实生产凭据
- 临时代码:调试日志、断点、TODO 占位、硬编码测试数据
- 冲突与格式:冲突标记、尾随空格、缩进异常、格式化噪音
- 提交范围:是否混入不相关文件、生成物、大文件或本地环境配置
- 行为风险:明显的空值风险、错误处理缺失、破坏性变更未说明
- 测试影响:是否需要运行或补充测试;不能运行时在结果中说明原因
Review 处理逻辑
无阻塞问题:继续生成提交消息,并可在回复中简要说明 review 通过。
发现阻塞问题:先停止提交,向用户列出问题、文件位置和建议修复方式;不要生成会掩盖问题的提交消息。
发现非阻塞风险:继续生成提交消息,但在回复中提示风险和建议验证项。
步骤 4:生成提交消息
基于项目规范和变更内容生成消息:
<type>(<scope>): <subject>
<body>
<footer>
必需:type + subject(10-72 字符)
可选:scope、body、footer
Subject 规则
- 一句话精准概括,不啰嗦、不拆分描述
- 祈使句:
add 而非 added
- 英文首字母小写,中文正常大小写
- 句尾不加标点
Body 规则
- 尽量不写 body,subject 能说清的不要加 body
- 仅在以下情况才写:破坏性变更说明、复杂变更需要补充背景/迁移指引
- 每行限制 72 字符
- 不要仅罗列修改的文件列表,不要重复 subject 已表达的内容
Footer 规则
BREAKING CHANGE: API endpoints now require authentication
Closes #123
Refs #456
Scope 使用规范
- 使用小写字母,不超过 15 字符
- 跨模块或不确定时省略 scope
- 从项目已有提交或 commitlint
scope-enum 中获取可用值
破坏性变更
两种标记方式(均为 Conventional Commits 标准):
方式 1:类型后加 !
feat!: remove deprecated endpoints
feat(api)!: remove deprecated endpoints
方式 2:Footer 中声明
feat(api): remove deprecated endpoints
BREAKING CHANGE: v1 endpoints are no longer available.
Migration guide: docs/migration.md
注意事项
- 仅负责创建提交,不执行推送
- 不提交密码、密钥、token 等敏感信息
- body 非必须,subject 能说清就不要加 body
- 不要在提交消息中包含
Co-Authored-By 等元信息
示例
基础
feat: add dark mode support
fix: 修复登录超时问题
docs: 更新安装指南
带 Scope
feat(auth): 实现 OAuth2 登录
fix(ui): 修复移动端按钮对齐问题
带 Issue
feat(auth): #1254 实现 OAuth2 登录
fix(ui): #123 修复移动端按钮对齐问题
带 Body(仅复杂/破坏性变更时使用)
feat(api)!: 重构分页接口为 cursor-based
旧的 page/limit 参数不再支持,迁移方式见 docs/migration.md
Closes #42