| name | git-commit-template |
| description | 进行代码提交时触发。提供统一的提交标题(Conventional Commits)、正文模板、字段含义、写作风格和正反示例。应由 git-commit-standard 等提交流程 skill 强制加载。 |
git-commit-template
提交说明的书写规范与模板。不负责提交流程(版本、固件、changelog 同步等),只定义 commit message 怎么写。
标题(Subject)
标题使用 Conventional Commits 格式,英文小写 type,可追加 scope,中文描述:
<type>[scope]: <中文描述>
Commit Types
| type | 用途 |
|---|
feat | 新功能 |
fix | 修复缺陷 |
docs | 文档变更 |
style | 格式/风格(无逻辑变更) |
refactor | 代码重构(无功能/修复变更) |
perf | 性能优化 |
test | 新增/更新测试 |
build | 构建/依赖变更 |
ci | CI/配置变更 |
chore | 维护/杂项 |
示例:
refactor: 简化编码规范流程并增强编译指令生成
feat[agent-browser]: 新增截图对比功能
fix: 修复 skills 链接在 Windows 下失效
正文模板
主题行可使用 Conventional Commits 简写(如 feat: xxx、fix: xxx),但正文必须包含以下字段(格式优先参考仓库既有提交历史):
版本:<artifact-or-release-version,无版本号则填 N/A>
时间:<date>
修改者:<git config user.name>
更改点:
1)修改原因:
1. <why-1>
2. <why-2>
2)修改依据:
1. <basis-1>
2. <basis-2>
3)修改方法:
1. <how-1>
2. <how-2>
4)修改影响:
1. <impact-1>
2. <impact-2>
若仓库已有自己的模板,按仓库模板。
字段说明
| 字段 | 来源 | 说明 |
|---|
| type[scope] | 标题 | Conventional Commits 格式 |
| 版本 | 版本源文件或发布版本号;若无版本号,填 N/A | 不把长版本信息塞进标题;禁止在没有版本号时尝试查找或推导版本号 |
| 时间 | 当前日期 | 格式沿用仓库历史;若无固定格式,使用 YYYY.MM.DD |
| 修改者 | git config user.name | 除非仓库另有要求 |
| 修改原因 | 本次改动要解决什么问题 | 从用户/产品/业务角度说明 |
| 修改依据 | 基于什么理由做这个修改 | 需求、bug、设计文档等 |
| 修改方法 | 关键实现手段摘要 | 只写方法摘要,不展开实现细节 |
| 修改影响 | 对用户/系统/兼容性的影响 | 只写关键结果,不写过细技术影响 |
写作风格
- 标题:
type[scope]: 中文描述,聚焦提交目的,简练清晰。
- 正文:只描述本次真实业务、代码、文档、兼容性和影响变化。不要写提交流程、是否递进版本、是否归档固件、后续应该做什么等流程话术。
- 默认禁止一整段说明式写法:在
修改原因/修改依据/修改方法/修改影响 后直接跟一大句完整说明而不分点(除非仓库历史模板明确要求单段写法)。
- 同一一级字段下最多 3 条子点:先压缩语言,再检查是否还能继续合并同类项。能写成一条摘要时,不拆成多条细节。
- 同一一级字段下存在两个及以上独立主题时:拆成
1. 2. 3. 子点,不要把多个主题塞进一个长句、分号串联句或并列从句里。
- "修改方法" 默认不写过细实现细节:不写具体函数级处理步骤、内部状态机细节、输入输出字节级变化、调试日志点布置、具体兼容分支和兜底路径。
- "修改影响" 默认不写过细技术影响:不写某种旧报文/旧字段/旧格式会被拒绝、某个中间态如何切换、内部 session/payload 如何分段推进、过细的协议兼容边界。
- 不要把"已按默认流程检查/同步固件和 README/changelog"写成变更点或原因;默认流程是否执行记录在任务汇报中即可。
正反示例
修改方法
推荐(短句概括,最多 3 点):
3)修改方法:
1. 收口提交正文模板
2. 增加最多 3 点约束
3. 补充正反示例
不推荐(长句串联、函数级细节):
3)修改方法:收口提交正文模板并增加最多 3 点约束,同时补充正反示例以
避免提交时继续输出整段长句。修改了 validate_template() 函数内部的状态机
处理,增加了字段级校验和回退逻辑。
修改影响
推荐(用户/业务视角):
4)修改影响:
1. 提交模板统一为四字段结构
2. 不再接受整段式提交说明
不推荐(过细技术影响):
4)修改影响:
1. 旧的单段提交格式会被拒绝
2. 内部 session 状态切换逻辑不变
3. 兼容旧版本 review 工具
常见错误
- 在 commit message 里写"按默认流程检查/同步固件和 README"造成提交说明噪音。
- 在 commit message 或版本履历里写"不修改版本宏""不归档固件产物""后续需要更新固件"等流程说明。
- 标题塞入过长版本字符串。
- 多个独立影响面挤在一条长句里,导致兼容性、策略和行为混在一起。
- 一级字段下分出 5-8 条碎点,没有先压缩语言、合并同类项。
- 正文与版本头、README/changelog、归档产物不一致。
- 在没有版本号时尝试查找或推导版本号(如搜索 VERSION 宏、package.json 等),应直接填
N/A。