Aze333Sun 提交前 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 描述」「提交说明」「代码评审」
- 用户要求「演练 / 试运行 / 检验」本技能时
执行流程
- 收集事实（禁止凭空编写）：
git status+git diff --staged（或git diff）查看真实改动git log --oneline -5了解近期提交风格；git config user.name获取提交者
- 圈定评审范围（先定范围再评审——评审对象是本次待提交的内容，不是全部变更）：
- 列出工作区改动文件清单，请用户确认哪些纳入本次提交，不得默认全量纳入
- 已 staged 的内容：评审
git diff --staged；未 staged：仅评用户指定文件的git diff -- <paths> - 提 MR / 评审已有提交场景：评审对象 = 该 MR 的 commit 区间 diff（如
git diff <base>...HEAD），不含工作区未提交改动 - 范围一经确认，后续评审、MR 描述、自检清单行数统计、提交记录「变更规模」均以该范围为口径
- 提交前代码评审（仅针对圈定范围，按「提交前代码评审」一节执行）：
- 按评审 Checklist 逐项核查，每项记录 ✅/⚠️/❌/N/A 与证据（文件:行号）
- 列出风险清单（blocking / suggestion / nit 分级）
- 客观计算评审总分（附评分明细，禁止拍脑袋给分）
- 识别并单独列出高风险项
- 逐项填写 MR 描述模板，内容必须来自圈定范围的真实 diff：
- 变更背景：关联需求/缺陷号未知时先追问用户
- 变更内容：列出实际改动的模块、核心逻辑、受影响的调用方（通过代码搜索确认，不要猜测）
- AI 使用情况：AI 工具参与编写的改动，勾选
[AI-assisted]或[AI-generated]，工具填实际使用的 AI 工具名（如 Trae、Copilot 等），提示词摘要写本次任务要点 - 自检清单：逐项真实核查后再勾选：
- 统计圈定范围的 diff 行数验证 ≤ 400 行（提交记录文件为流程产物，不计入统计），超出时注明原因
- 检查改动中是否存在硬编码密钥/配置（搜索 password、secret、token、key 等）
- 公共方法/接口变更时，用 Grep 列出全部调用方
- 无法核实的项保持未勾选并向用户说明
- 盘点缺项并追问：按「信息不完整时的追问」盘点必填信息（含变更类型：需求/缺陷/其他），缺失项一次性集中追问，得到答复后再填写
- 输出完整 MR 描述 + 评审结果（风险清单、评分、高风险项），等待用户确认或修正
- 生成提交记录文件：按「提交记录文件落地」一节，将 MR 描述 + 评审结果写入
提交记录/目录（不存在则创建），命名{类型}_{提交者}_{YYYYMMDD}_{序号}.md - 按已确认的范围与方式执行提交：按「提交方式与 IDEA 协同」一节进行（文件清单已在第 2 步确认，此时仅确认提交方式）；若用户要求修改 MR 描述或评审结论，按修改后版本更新提交记录文件后再提交
MR 描述模板（固定格式，不得增删章节）
## 变更背景
（关联需求/缺陷号：#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 明确批准 |
高风险项识别（满足任一即列出）
- 改动属于高风险范围：公共库/基础组件、对外接口、数据库结构、权限与鉴权、资金与计费、AI 生成的核心逻辑
- 存在任一 blocking 级问题
- 公共方法/接口/数据结构变更但调用方清单不完整或未确认
- 测试缺失、断言被修改以适配实现、或覆盖率低于主干基线
- 总分落入红挡（< 60）
高风险变更须提示：需 Tech Lead 审批后方可合入。
提交记录文件落地
MR 描述确认后、git commit 之前，生成提交记录文件：
- 目录：工程仓库根目录下
提交记录/，不存在则创建 - 命名：
{类型}_{提交者}_{YYYYMMDD}_{序号}.md- 类型：
需求（有关联需求号）/缺陷（缺陷修复）/其他（无关联，如文档、配置）——由追问结果确定，无法确定时追问 - 提交者：
git config user.name - 日期：当天 YYYYMMDD
- 序号：同一提交者同日已有记录数 + 1，两位数字（01、02…），先查看
提交记录/已有文件确认（目录不存在则直接从 01 开始）
- 类型：
- 文件内容结构（章节固定）：
# 提交记录：{一句话标题}
| 项 | 内容 |
| --- | --- |
| 提交者 | {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 明确批准并在提交记录中留痕
- 只有用户知道的信息（需求号、验证环境、回滚方式等）缺失时必须先追问，经用户确认跳过才可保留占位符并标注
⚠️ 待补充 - 不为通过检查而虚报或修改事实（如测试断言）
- 提交记录文件命名与目录结构不得随意变更；当日重复提交按序号递增，不得覆盖旧记录
推广安装（给研发同学）
- 将
mr-commit-template/整个目录复制到目标工程仓库的 skills 目录下（如.trae/skills/、.claude/skills/、.opencode/skills/等，保持目录名与 SKILL.md 不变） - 随仓库提交该技能文件，全组拉取后即人人可用；技能升级时同步更新各仓库副本
- 技能不依赖任何外部文档或服务，仅依赖 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→ ✅ 逐文件精确添加 - ❌ 跳过评审直接提交 → ✅ 必须先完成代码评审
- ❌ 用占位符糊弄缺失信息 → ✅ 必须先追问用户
- ❌ 凭印象打分 → ✅ 每项必须附证据（文件:行号）