# Mr Commit Template

> Use when committing code, creating PRs, or generating MR descriptions with code review and commit record archiving. Pre-commit workflow with structured review checklist.

- Skill: `aze333sun/mr-commit-template` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aze333sun/mr-commit-template`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aze333sun/mr-commit-template/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Aze333Sun (https://skillmd.com/u/aze333sun)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/aze333sun/mr-commit-template

---


# 提交前 MR 模板生成 + 代码评审

本技能**自包含**：内嵌 MR 描述模板、评审 Checklist、评分规则与提交记录文件规范，不依赖任何外部文件，可整体复制到任意工程仓库的 `.trae/skills/mr-commit-template/` 下直接使用。**每次执行 git commit / 提交代码 / 提 MR 之前，必须依次完成：代码评审（列风险、打分、识别高风险项）→ 生成填写完整的 MR 描述 → 追问缺失信息 → 生成提交记录文件 → 经用户确认后才能提交。** 未完成上述步骤前禁止执行任何 git commit 动作。

## When to Use

- 用户说「提交」「commit」「提 MR」「合并请求」「push」等提交意图
- 准备执行 `git commit`、`git push`、`gh pr create` 等提交类命令之前
- 用户明确提到「MR 描述」「提交说明」「代码评审」
- 用户要求「演练 / 试运行 / 检验」本技能时

## 执行流程

1. **收集事实**（禁止凭空编写）：
   - `git status` + `git diff --staged`（或 `git diff`）查看真实改动
   - `git log --oneline -5` 了解近期提交风格；`git config user.name` 获取提交者
2. **圈定评审范围**（先定范围再评审——评审对象是**本次待提交的内容**，不是全部变更）：
   - 列出工作区改动文件清单，请用户确认哪些纳入本次提交，**不得默认全量纳入**
   - 已 staged 的内容：评审 `git diff --staged`；未 staged：仅评用户指定文件的 `git diff -- <paths>`
   - 提 MR / 评审已有提交场景：评审对象 = 该 MR 的 commit 区间 diff（如 `git diff <base>...HEAD`），不含工作区未提交改动
   - 范围一经确认，后续评审、MR 描述、自检清单行数统计、提交记录「变更规模」均以该范围为口径
3. **提交前代码评审**（仅针对圈定范围，按「提交前代码评审」一节执行）：
   - 按评审 Checklist 逐项核查，每项记录 ✅/⚠️/❌/N/A 与证据（文件:行号）
   - 列出风险清单（blocking / suggestion / nit 分级）
   - 客观计算评审总分（附评分明细，禁止拍脑袋给分）
   - 识别并单独列出高风险项
4. **逐项填写 MR 描述模板**，内容必须来自圈定范围的真实 diff：
   - 变更背景：关联需求/缺陷号未知时先追问用户
   - 变更内容：列出实际改动的模块、核心逻辑、受影响的调用方（通过代码搜索确认，不要猜测）
   - AI 使用情况：AI 工具参与编写的改动，勾选 `[AI-assisted]` 或 `[AI-generated]`，工具填实际使用的 AI 工具名（如 Trae、Copilot 等），提示词摘要写本次任务要点
   - 自检清单：**逐项真实核查后再勾选**：
     - 统计**圈定范围**的 diff 行数验证 ≤ 400 行（提交记录文件为流程产物，不计入统计），超出时注明原因
     - 检查改动中是否存在硬编码密钥/配置（搜索 password、secret、token、key 等）
     - 公共方法/接口变更时，用 Grep 列出全部调用方
     - 无法核实的项保持未勾选并向用户说明
5. **盘点缺项并追问**：按「信息不完整时的追问」盘点必填信息（含变更类型：需求/缺陷/其他），缺失项一次性集中追问，得到答复后再填写
6. **输出完整 MR 描述 + 评审结果**（风险清单、评分、高风险项），等待用户确认或修正
7. **生成提交记录文件**：按「提交记录文件落地」一节，将 MR 描述 + 评审结果写入 `提交记录/` 目录（不存在则创建），命名 `{类型}_{提交者}_{YYYYMMDD}_{序号}.md`
8. **按已确认的范围与方式执行提交**：按「提交方式与 IDEA 协同」一节进行（文件清单已在第 2 步确认，此时仅确认提交方式）；若用户要求修改 MR 描述或评审结论，按修改后版本更新提交记录文件后再提交

## MR 描述模板（固定格式，不得增删章节）

```markdown
## 变更背景
（关联需求/缺陷号：#XXXX，为什么改）

## 变更内容
- 改动模块：
- 核心逻辑：
- 影响范围（调用方清单）：

## AI 使用情况
- [ ] 未使用 AI
- [ ] [AI-assisted] 工具：___ 提示词摘要：___
- [ ] [AI-generated] 工具：___ 提示词摘要：___

## 自检清单
- [ ] 已逐行阅读并理解全部改动
- [ ] 公共方法/接口/数据结构变更已列出全部调用方并确认
- [ ] 已补充/更新测试，未为通过而修改断言
- [ ] 无顺带重构、格式化、批量重命名
- [ ] 无硬编码密钥/配置
- [ ] 本地已通过流水线同套命令验证
- [ ] 单 MR 规模 ≤ 400 行（超出请说明原因）

## 验证方式
（如何验证：步骤、环境、预期结果）

## 回滚方案
（出问题时如何恢复）
```

## 提交前代码评审

**评审对象 = 执行流程第 2 步圈定的本次待提交 diff**，不含：未纳入本次提交的工作区改动、历史已合入代码、其他分支内容。核查证据允许全局 Grep（调用方、重复实现等），但**判定只针对本次 diff 引入的变更**。范围外发现的问题（如顺带看到其他文件缺陷）不进评分、不阻断本次提交，以「范围外观察」附注提示用户。

按下方 Checklist 逐项核查，每项必须给出证据（文件:行号 或「未发现」），禁止无证据判定。

### Checklist（通用项，权重 60%）

| # | 核查项 | 核查方法 |
|---|--------|---------|
| G1 | 逻辑正确，边界条件（空值、0、极值、超长）已处理 | 阅读 diff 逻辑分支 |
| G2 | 异常处理不吞异常，日志不含敏感信息 | 检查 catch/日志语句 |
| G3 | 无并发问题，事务边界正确 | 检查共享状态/事务注解 |
| G4 | 无重复实现（是否已有公共工具方法） | Grep 相似实现 |
| G5 | 命名清晰，无魔法数字 | 阅读 diff |
| G6 | 无 N+1 查询、无慢 SQL、无内存泄漏风险 | 检查循环内查询/资源释放 |
| G7 | 测试覆盖关键分支，断言验证的是需求而非实现 | 查看测试 diff 与断言 |

### Checklist（AI 代码专项，权重 40%；未标注 AI 参与时并入通用项，通用项权重升为 100%）

| # | 核查项 | 核查方法 |
|---|--------|---------|
| A1 | 调用的 API/方法真实存在（防止幻觉 API） | Grep 定义处确认存在 |
| A2 | 无顺带重构与无关改动（diff 最小化） | 逐文件核对 diff 与任务目标 |
| A3 | 业务约束、历史兼容、边界规则未被破坏 | 对照调用方与既有逻辑 |
| A4 | 未引入重复的已有实现 | Grep 相似实现 |
| A5 | 安全/鉴权/加密/支付逻辑已由专人复核 | 标注待复核对象 |
| A6 | 提交人能解释每一处关键逻辑 | 列出 3 处随机追问点及答案 |
| A7 | 影响面自查清单与实际改动一致 | 核对调用方搜索结果 |

纯文档/配置类变更中不适用代码项标 N/A 剔除，**N/A 项不参与分母，避免拉低分数**。

### 评分规则（客观、可复核）

- 每项判定：✅ 通过 = 1 分 ｜ ⚠️ 有风险 = 0.5 分 ｜ ❌ 不通过 = 0 分 ｜ N/A 剔除
- 维度得分 = (✅ 数 + 0.5 × ⚠️ 数) ÷ 适用项数 × 100；**某维度适用项数为 0 时该维度记 N/A，其权重按剩余维度占比重新分配**
- 总分 = 通用项得分 × 60% + AI 专项得分 × 40%（未标注 AI 时 = 通用项得分 × 100%），四舍五入取整
- 输出评分明细表：每项的判定 + 证据，总分可复算

### 风险分级与挡位处置

| 级别 | 含义 | 处置 |
|------|------|------|
| blocking | 必须改（逻辑错误、安全问题、影响面未确认） | 默认阻断提交，修复后再走流程；用户坚持提交需在提交记录中标注「明知风险强制提交」 |
| suggestion | 建议改 | 随 MR 描述公示，不阻断 |
| nit | 可选优化 | 记录即可 |

| 总分挡位 | 结论 |
|---------|------|
| ≥ 90（绿） | 可提交 |
| 75–89（黄） | 可提交，风险随 MR 公示 |
| 60–74（橙） | 建议修复后提交；用户确认继续才提交，提交记录标注 |
| < 60（红）或存在 blocking ❌ | 高风险，默认阻断，需修复或 Tech Lead 明确批准 |

### 高风险项识别（满足任一即列出）

1. 改动属于高风险范围：公共库/基础组件、对外接口、数据库结构、权限与鉴权、资金与计费、AI 生成的核心逻辑
2. 存在任一 blocking 级问题
3. 公共方法/接口/数据结构变更但调用方清单不完整或未确认
4. 测试缺失、断言被修改以适配实现、或覆盖率低于主干基线
5. 总分落入红挡（< 60）

高风险变更须提示：**需 Tech Lead 审批后方可合入**。

## 提交记录文件落地

MR 描述确认后、git commit 之前，生成提交记录文件：

- **目录**：工程仓库根目录下 `提交记录/`，不存在则创建
- **命名**：`{类型}_{提交者}_{YYYYMMDD}_{序号}.md`
  - 类型：`需求`（有关联需求号）/ `缺陷`（缺陷修复）/ `其他`（无关联，如文档、配置）——由追问结果确定，无法确定时追问
  - 提交者：`git config user.name`
  - 日期：当天 YYYYMMDD
  - 序号：同一提交者同日已有记录数 + 1，两位数字（01、02…），先查看 `提交记录/` 已有文件确认（目录不存在则直接从 01 开始）
- **文件内容结构**（章节固定）：

```markdown
# 提交记录：{一句话标题}

| 项 | 内容 |
| --- | --- |
| 提交者 | {git user.name} |
| 日期 | {YYYY-MM-DD} |
| 变更类型 | 需求 / 缺陷 / 其他 |
| 关联编号 | #XXXX 或 无 |
| 变更规模 | {N 个文件，+x -y 行} |
| 评审总分 | {XX}/100（{绿/黄/橙/红}） |
| 高风险项 | 无 ｜ 有：{简列} |
| 高风险处置 | 不涉及 ｜ Tech Lead 审批 ｜ 强制提交说明 |

## 一、MR 描述
（模板填写全文，与 MR 平台内容一致）

## 二、代码评审结果
### 2.1 Checklist 核查明细
| 项 | 判定 | 证据（文件:行号） |
### 2.2 风险清单
| 级别 | 位置 | 问题描述 | 建议 |
### 2.3 评分明细
| 维度 | 得分 | 权重 |
（总分与复算过程）
### 2.4 高风险项
（逐项列出或「无」）

## 三、说明
（强制提交、豁免、待补充事项等，无则写「无」）
```

- 提交记录文件与业务变更**进入同一次 commit**，实现记录随版本留存
- 提交记录文件不计入单 MR ≤ 400 行的自检统计

## 提交方式与 IDEA 协同

技能不抢占提交权，提交方式二选一（用户未声明时追问一次）：

### 方式一：AI 代提

- 逐文件 `git add <明确路径>`，**禁止 `git add -A`、`git add .`**，只提交清单内文件
- 未列入清单的本地改动（进行中的工作、临时文件、个人配置）保持原状，不暂存、不提交
- commit message 按该仓库近期提交风格给出，提交后回显 commit 结果

### 方式二：IDEA / 用户自提（适合日常用 IDEA 勾选文件提交的习惯）

技能**不执行 git commit**，改为输出一份「IDEA 提交指引」：

- **提交清单**：逐个列出应勾选的文件路径（业务变更文件 + `提交记录/` 下的本次记录文件）
- **changelist 建议**：将上述文件放入同一 changelist（如 `commit-YYYYMMDD-序号`），避免提交记录文件漏勾
- **commit message**：给出可直接粘贴的主题行（及正文）
- 用户在 IDEA 提交面板中按清单勾选文件提交；**提交记录文件务必与业务文件同次勾选**，保证记录随版本同 commit 留存

### 兜底校验（两种方式都执行）

- **AI 代提**：commit 后立即用 `git status` + `git log -1 --stat` 校验业务文件与提交记录文件是否都进入同一次 commit
- **IDEA 自提**：AI 无法感知用户在 IDE 内的提交时刻，校验在以下两个时点执行——① 用户回话告知「已提交」时；② **下次触发本技能时**，先回查 `git log -- 提交记录/` 确认上次记录文件是否入库
- 若提交记录文件被漏掉（IDEA 漏勾常见），提示用户并自动补一个独立 commit（`chore(commit-record): 随附 {原提交主题}`），同时在提交记录文件「说明」栏补注实际所在 commit

## 信息不完整时的追问

输出 MR 描述前，盘点以下必填信息，有缺失时**必须先向用户追问，不得直接用占位符糊弄**：

| 缺失信息 | 优先获取方式 | 仍缺失时追问话术 |
|----------|-------------|-----------------|
| 本次提交范围（哪些文件纳入） | git status 清单 + 用户勾选确认 | 「本次提交包含哪些文件？（列出改动清单供确认）」——**必须在评审前确定** |
| 变更类型（需求/缺陷/其他） | 由变更背景推导 | 「本次变更是需求、缺陷修复还是其他（文档/配置）？」 |
| 需求/缺陷号 | 需求单、用户输入 | 「本次改动关联哪个需求/缺陷号？」 |
| 影响范围（调用方） | Grep 代码搜索 | 搜索结果有歧义时，列出候选清单让用户确认 |
| 验证方式 | 流水线记录、用户输入 | 「如何验证：步骤、环境、预期结果是什么？」 |
| 回滚方案 | 发布方式、用户输入 | 「出问题时如何恢复（回滚版本/回滚脚本）？」 |

追问规则：

- **一次性集中追问**全部缺失项，不得挤牙膏式逐条反复追问
- 用户明确答复「先提交，后面补」或「占位」时，才允许保留模板占位符，并在对应位置标注 `⚠️ 待补充`
- 用户拒绝回答或确实无法提供的项，保留占位符格式，**禁止虚构**
- AI 使用情况、自检清单、Checklist 判定与评分由 AI 自行核实填写，不依赖用户提供

## 约束

- MR 模板章节与顺序固定，不得新增、删除或重排章节
- `git add` 只允许逐文件精确添加，禁止 `git add -A` / `git add .`；未列入提交清单的文件不得暂存
- 用户选择 IDEA 自提时，技能不得代为执行 git commit，只输出提交指引
- 所有勾选项必须有真实依据，未核实的不勾选并说明
- Checklist 判定与评分必须附证据（文件:行号），总分须可复算，禁止凭印象打分
- 评审不通过（红挡/blocking）时不得静默放行：要么修复，要么用户/Tech Lead 明确批准并在提交记录中留痕
- 只有用户知道的信息（需求号、验证环境、回滚方式等）缺失时必须先追问，经用户确认跳过才可保留占位符并标注 `⚠️ 待补充`
- 不为通过检查而虚报或修改事实（如测试断言）
- 提交记录文件命名与目录结构不得随意变更；当日重复提交按序号递增，不得覆盖旧记录

## 推广安装（给研发同学）

1. 将 `mr-commit-template/` 整个目录复制到目标工程仓库的 skills 目录下（如 `.trae/skills/`、`.claude/skills/`、`.opencode/skills/` 等，保持目录名与 SKILL.md 不变）
2. 随仓库提交该技能文件，全组拉取后即人人可用；技能升级时同步更新各仓库副本
3. 技能不依赖任何外部文档或服务，仅依赖 git 与 AI 编码助手内置工具，开箱即用

## Quick Reference

| 步骤 | 操作 |
|------|------|
| 收集事实 | `git status` + `git diff --staged` + `git log --oneline -5` |
| 圈定范围 | 列出改动文件，用户确认 |
| 代码评审 | Checklist逐项核查，评分+风险分级 |
| 填写MR描述 | 变更背景→变更内容→AI使用情况→自检清单 |
| 追问缺项 | 一次性集中追问缺失信息 |
| 生成记录 | `提交记录/{类型}_{提交者}_{YYYYMMDD}_{序号}.md` |
| 执行提交 | AI代提 或 IDEA自提 |

## Common Mistakes

- ❌ 使用`git add -A` → ✅ 逐文件精确添加
- ❌ 跳过评审直接提交 → ✅ 必须先完成代码评审
- ❌ 用占位符糊弄缺失信息 → ✅ 必须先追问用户
- ❌ 凭印象打分 → ✅ 每项必须附证据（文件:行号）