代码审查意见生成器

技能文档

---
name: melodic-software-review-comment
title: 代码审查意见生成器
category: 开发工具
description: 基于 Conventional Comments 规范生成结构化、专业、可执行的代码审查意见，自动区分意见类型（问题/建议/疑问/表扬等）与严重级别（blocking/non-blocking），并提供直接与委婉两种语气版本。当用户需要撰写代码审查评论、评审 PR、给出代码反馈时触发。触发词：代码审查、审查意见、PR 评审、code review。
---

# 代码审查意见生成器

使用 Conventional Comments（约定式评论）格式生成建设性的代码审查意见，让反馈清晰、专业、可直接执行。

## 技能工作流

根据用户对某个代码问题或观察的描述，生成一条格式规范的审查意见。

### 步骤1：理解问题

向用户确认以下信息（用户已提供的信息直接沿用，不必重复追问）：

1. **问题或观察是什么？** —— 用户在代码中注意到了什么？
2. **上下文** —— 涉及哪个文件/函数/行？
3. **严重程度** —— 是阻塞合并（必须修复）还是非阻塞（锦上添花）？
4. **修复建议** —— 用户是否已有推荐方案？（可选）

### 步骤2：分类定级

确定合适的标签（label）：

| 标签 | 适用场景 |
| ----- | ----------- |
| `praise` | 表扬做得好的地方 |
| `nitpick` | 轻微的风格或偏好问题 |
| `suggestion` | 改进建议，非强制 |
| `issue` | 需要修复的缺陷或问题 |
| `question` | 需要澄清或确认理解 |
| `thought` | 分享观点，无需行动 |

确定修饰符（decoration）：

- `(blocking)` —— 合并前必须修复
- `(non-blocking)` —— 可选，作者可自行忽略
- `(if-minor)` —— 仅当修复成本很低时建议顺手改掉

### 步骤3：生成评论

输出格式：`[label] (decoration): [主题]`

按以下模板组织输出：

```markdown
## 审查意见

**标签：** [label]
**修饰符：** (blocking/non-blocking)
**位置：** [file:line，如已知]

---

### 评论正文

**[label] ([decoration]):** [一句话主题]

[解释为什么这个问题重要]

[如适用，附上修复建议]

---

### 备选措辞

**更直接的版本：**
> [直接表述]

**更委婉的版本：**
> [柔和表述]

---

### 补充说明

- [对方可能如何接受这条反馈]
- [作者不同意时的替代思路]
```

### 步骤4：语气校准

生成的评论应遵循以下原则：

- 对事不对人，聚焦代码本身
- 对不明显的反馈解释「为什么」
- 指出问题时尽量附上建议
- 使用协作式语言（「我们」「建议」「可以考虑」）

## 示例

### 示例1：缺陷（issue）

**用户输入：**「用户不存在的时候他们没有处理 null」

**生成的评论：**

````markdown
**issue (blocking):** 用户不存在时会出现空指针异常

`getUserById` 在用户不存在时可能返回 `undefined`，但后续代码没有做检查就直接访问了 `.name`。

一旦有人查询已删除的用户，应用就会崩溃。

**修复建议：**
```javascript
const user = getUserById(id);
if (!user) {
  throw new UserNotFoundError(id);
}
return user.name;
```
````

### 示例2：细节挑剔（nitpick）

**用户输入：**「变量名有点含糊」

**生成的评论：**

```markdown
**nitpick (non-blocking):** 建议使用更具描述性的变量名

`x` 和 `tmp` 无法传达它们代表的含义。`userCount`、`pendingRequests` 这类命名能让人一眼看懂。

如果你想保留现状也可以，这只是可读性上的小建议。
```

### 示例3：表扬（praise）

**用户输入：**「错误处理写得很干净」

**生成的评论：**

```markdown
**praise:** 错误处理覆盖非常到位

每一种错误情况都得到了显式处理，并带有明确的错误信息，这会大幅降低线上问题的排查成本。可重试错误与致命错误的区分尤其漂亮。
```

使用说明

# 代码审查意见生成器

基于 Conventional Comments 规范，把一句「这里有问题」变成结构化、专业、可直接执行的代码审查意见。

## 使用

向 AI 描述你在代码里观察到的问题，例如：

```text
帮我为这个问题写一条审查意见：getUserById 可能返回 undefined，
但代码没有判空就直接访问了 .name，属于必须修复的缺陷。
```

输出会包含：标签与严重级别（`issue (blocking)` 等）、位置、问题解释、修复建议，以及直接/委婉两种备选措辞。

## 工作原理

1. 确认问题、上下文、严重程度与修复建议四要素
2. 按约定式评论规范分类：praise / nitpick / suggestion / issue / question / thought，并标注 (blocking) / (non-blocking) / (if-minor)
3. 按统一模板生成评论正文与备选措辞，坚持对事不对人、解释原因、附带建议的协作式语气

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。