# Git Commit Template

> 进行代码提交时触发。提供统一的提交标题（Conventional Commits）、正文模板、字段含义、写作风格和正反示例。应由 git-commit-standard 等提交流程 skill 强制加载。

- Skill: `docevilock/git-commit-template` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add docevilock/git-commit-template`
- Raw SKILL.md: https://api.skillmd.com/api/skills/docevilock/git-commit-template/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: docevilock (https://skillmd.com/u/docevilock)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/docevilock/git-commit-template

---


# 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 下失效`

## ⚠️ 硬性输出约束

以下规则为强制门禁，违反即错误，不可协商：

### 逐行输出

**版本、时间、修改者、更改点、以及更改点下的一级子项（修改原因/修改依据/修改方法/修改影响）必须各自独占一行。**

禁止将多个顶级字段拼接为单行，例如：

``n# 错误 — 禁止以下输出格式
版本：N/A 时间：26.07.16 修改者：Yangyp 更改点：gbk_prepare改为stamp增量扫描，gbk_encode用C重写
``n
正确格式：每个字段独占一行，子项缩进换行。

### 篇幅上限

| 字段 | 上限 |
|------|------|
| 修改原因 | ≤ 1 行 |
| 修改依据 | ≤ 1 行 |
| 修改方法 | ≤ 2 行 |
| 修改影响 | ≤ 1 行 |

这是硬性字数/行数约束，不是建议。超出上限即为格式错误。

## 正文模板

**主题行**可使用 Conventional Commits 简写（如 `feat: xxx`、`fix: xxx`），但**正文必须包含**以下字段（格式优先参考仓库既有提交历史）：

```text
版本：<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` | 除非仓库另有要求 |
| 修改原因 | 本次改动要解决什么问题 | 从用户/产品/业务角度说明，**≤ 1 行** |
| 修改依据 | 基于什么理由做这个修改 | 需求、bug、设计文档等，**≤ 1 行** |
| 修改方法 | 关键实现手段摘要 | 只写方法摘要，不展开实现细节，**≤ 2 行** |
| 修改影响 | 对用户/系统/兼容性的影响 | 只写关键结果，不写过细技术影响，**≤ 1 行** |

## 写作风格

- **标题**：`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`。
- 将版本、时间、修改者、更改点等所有字段拼接在一行输出（如 `版本：N/A 日期：26.07.16 修改者：Yangyp 更改点：...`），必须每个顶级字段和一级子项独占一行。
- 修改原因/依据/影响超过 1 行，或修改方法超过 2 行，未按硬性篇幅上限压缩。