Auto Review

---
name: auto-review
description: 写入 .md / 代码文件后自动做质量审查与修复闭环，判断是否属复杂场景（是则接力 challenger 二次质疑），并在契约面改动时提示影响面缺口（建议转 code-change-impact，不自动执行）。触发：每次 write_to_file / replace_in_file 写入后自动执行。
---

## 概述

**目的**：确保 AI 生成的每一份文件在交付前经过质量审查，减少人工返工

**功能**：自动触发质量审查与修复闭环，支持 Skill/Rules 文件专项审查、代码审查、通用文档审查；自动判断是否需要二次质疑（challenger）；契约面改动时提示影响面缺口（建议转 `code-change-impact`，**只提示不自动执行**）

**使用场景**：
- AI 使用 write_to_file 或 replace_in_file 写入 .md / 代码文件后自动执行
- 需要验证 Skill/Rules 文件是否符合 YAML frontmatter 和 AI 说明层规范时
- 需要对代码变更进行质量审查时
- 改了签名 / 字段 / 表结构 / 枚举后，需要判断"有没有把调用方写坏"时（见 Step 8）

# 自动审查规则

## 核心原则

AI 生成的每一份文件（.md 文档、代码）在交付给用户之前，**必须经过自动审查→修复→再审查的闭环**，确保交付质量，减少人工返工。

**证据纪律：静态检查 ≠ 已验证**：审查结论必须区分两种性质——"静态检查通过"（仅阅读内容判断，未实际运行）与"已验证"（实际执行过代码/命令/测试并观察到结果）。未实际运行时，不得声称"可正常运行/已验证通过"，只能表述为"静态检查未发现问题"。

## 触发范围

以下文件类型在写入后自动进入审查管道：

| 文件类型 | 扩展名 | 审查策略 |
|----------|--------|----------|
| Skill 文件 | `.md`（位于 `skills/` 目录） | **专项审查**：YAML frontmatter + AI 说明层 |
| Rules 文件 | `.md`（位于 `rules/` 目录） | **专项审查**：YAML frontmatter + 规则结构 |
| Markdown 文档 | `.md`（其他位置） | 先查对应 skill，无则通用审查 |
| Python 代码 | `.py` | 查 `code-review` skill → 通用审查 |
| C/C++/Java/Go/Rust 代码 | `.c`, `.cpp`, `.h`, `.java`, `.go`, `.rs` | 通用审查 |
| Shell 脚本 | `.sh`, `.bash` | 通用审查 |
| PowerShell 脚本 | `.ps1` | 通用审查 |
| 配置文件 | `.toml`, `.yaml`, `.yml`, `.json` | 通用审查 |
| 前端代码 | `.js`, `.ts`, `.tsx`, `.jsx`, `.vue`, `.css` | 通用审查 |

**不触发审查的文件类型**：
- 纯数据文件（`.csv`, `.txt`, `.log`）
- 图片/二进制文件
- 临时/缓存文件
- 用户明确要求跳过审查的文件

## 审查流程

### Step 1：写入文件后自动触发

每次使用 `write_to_file` 或 `replace_in_file` 写入匹配的文件类型后，自动进入 Step 2。

### Step 2：查找对应 Skill（skill 优先）

检查 `skills/` 目录下是否存在与文件类型/场景匹配的 skill：

| 场景 | 对应 skill |
|------|-----------|
| 代码变更审查 | `code-review` |
| 代码审查二次确认 | `challenger` |
| 技术设计文档 | `design-review` |
| 需求文档 | `requirement-mining`（结构验证） |

匹配规则：
- **找到对应 skill**：使用 `use_skill` 加载 skill，按其流程执行审查。
- **无匹配 skill**：使用下方"通用审查标准"执行审查。

### Step 3：审查标准

#### 3.1 Skill 文件专项审查（位于 `skills/` 目录的 `.md` 文件）

| 检查项 | 内容 | 修复方式 |
|--------|------|----------|
| 1. YAML frontmatter | 必须包含 `name` 和 `description` 字段 | 补充缺失字段 |
| 2. name 字段格式 | 最多 64 字符，仅允许小写字母、数字、连字符 | 修正格式 |
| 3. description 字段格式 | 最多 1024 字符，必须非空，`description:` 后必须紧跟描述（不能换行） | 修正格式 |
| 4. AI 说明层 | 必须包含"概述"部分，说明：目的、功能、使用场景 | 补充 AI 说明层 |

#### 3.2 Rules 文件专项审查（位于 `rules/` 目录的 `.md` 文件）

| 检查项 | 内容 | 修复方式 |
|--------|------|----------|
| 1. YAML frontmatter | 必须包含 `description`、`alwaysApply`、`enabled`、`updatedAt` 字段；可选字段：`provider` | 补充缺失字段 |
| 2. description 字段格式 | 最多 1024 字符，必须非空，`description:` 后必须紧跟描述（不能换行） | 修正格式 |
| 3. alwaysApply 字段 | 默认值为 `true`；如果为 `false`，提醒用户该规则不会自动应用 | 提醒用户确认 |
| 4. 规则结构 | 规则内容结构完整，逻辑清晰 | 优化结构 |

#### 3.3 通用审查标准（其他文件）

当没有匹配的 skill 时，执行以下四项基础检查：

| 检查项 | 内容 |
|--------|------|
| 1. 格式完整性 | 文件格式是否符合预期？是否有残缺内容？ |
| 2. 逻辑一致性 | 内容前后是否矛盾？引用的文件/路径是否存在？ |
| 3. 安全风险 | 代码中是否有硬编码密钥、SQL 注入、命令注入等？ |
| 4. 可执行性 | 代码是否能在目标环境运行？依赖是否声明？ |

### Step 4：发现问题 → 自动修复

审查发现的问题分为三级：

| 级别 | 处理方式 |
|------|----------|
| P0 严重 | 立即自动修复，修复后重新进入 Step 3 审查 |
| P1 建议 | 自动修复，修复后重新进入 Step 3 审查 |
| P2 可选 | 自动修复（如修复成本低），或标注后跳过 |

修复策略：
- 修复必须保持代码的核心意图不变
- 修复后必须重新执行完整的审查流程（全量再审，不是增量）
- 修复过程中发现新的子问题，一并修复

### Step 5：循环与上限

```
写文件 → 审查 → 发现问题？→ 修复 → 审查 → 仍有问题？→ 修复 → 审查
                                                              ↓
                                              最多3轮 → 仍不通过 → 报告用户
                                                              ↓
                                                         Step 6：复杂场景判断
                                                              ↓
                                                （如触发 challenger）Step 7：质疑过滤
```

- **最多 3 轮审查-修复循环**
- 第 3 轮后如仍有未解决的问题，**停止自动修复**，向用户呈报：
  ```
  ⚠️ 自动审查第 3 轮仍未完全通过，以下问题需人工判断：
  
  - [问题1] ...
  - [问题2] ...
  
  建议：...
  ```

### Step 6：复杂场景判断 → challenger 二次质疑

auto-review 循环结束后（无论通过或达到上限），**自动评估本次修改是否属于复杂场景**。满足以下**任一条件**即视为复杂：

| 判断维度 | 复杂场景特征 |
|----------|-------------|
| 变更规模 | 涉及 3 个以上文件，或单文件变更超过 50 行 |
| 核心逻辑 | 修改涉及控制流（条件/循环）、错误处理、并发/异步逻辑 |
| Bug 修复 | 修复了运行时错误、逻辑缺陷、数据一致性问题 |
| 新增功能 | 添加了新的函数/方法/类/模块，或新增了外部接口 |
| 重构优化 | 重命名公共接口、提取模块、调整依赖关系、性能优化 |
| 关键路径 | 涉及认证、权限、数据持久化、支付、事务等关键业务逻辑 |
| 跨模块影响 | 变更影响多个模块之间的调用或数据流 |

**判定为复杂场景后**，自动调用 `challenger` skill 进行二次质疑：

```
use_skill("challenger")
```

challenger 会根据变更类型（Bug 修复/新增功能/优化）选择对应质疑策略进行深度审查，发现 auto-review 可能遗漏的潜在风险。

**不属于复杂场景**的情况（跳过 challenger）：
- 仅文档措辞修改、注释补充、格式调整
- typo 修复、变量重命名（无语义变化）
- 配置值调整（如版本号、阈值）

### Step 7：challenger 结果过滤评审

challenger 产出质疑报告后，**自动对质疑点进行过滤评审**。challenger 的质疑天然偏向严格，需要根据被审查对象类型和质疑层面做分层处理。

#### 7.1 按质疑层面分级

| 质疑层面 | 包含内容 | 处理方式 |
|----------|----------|----------|
| **非代码层面** | 架构设计、接口契约、数据模型、交互流程、安全约定、异常约定 | **一律不过滤**，全量保留并呈现 |
| **代码层面** | 空值校验、日志记录、输入校验、并发加锁、资源释放、重试策略、代码规范 | **结合内容判断**是否可延后 |

#### 7.2 代码层面过滤判断

对代码层面的每个质疑点，判断：**该质疑若不在文档/设计中明确，编码阶段 AI 是否会做错？**

| 判断结果 | 含义 | 处理 |
|----------|------|------|
| **会做错** | 缺少明确约定会导致编码方向错误 | **保留**，作为需关注的质疑点 |
| **不会做错** | AI 编码时大概率会自行完善（如常规空值校验、标准日志格式等） | **标注「可延后」**，保留在报告中但不阻塞当前阶段 |

**判断原则**：
- 如果质疑点涉及的是**通用编码实践**（如"参数应该做空值校验"），AI 在编码时自然会处理 → 可延后
- 如果质疑点涉及的是**业务特有约定**（如"删除操作必须是软删除而非硬删除"），不明确写出 AI 会按默认行为处理 → 必须保留
- 如果质疑点涉及的是**跨模块影响**（如"这个接口变更会影响下游系统"），即使属于代码层面也需保留

#### 7.3 重要原则

- **所有质疑点都不丢弃**：被标注「可延后」的质疑点仍然保留在报告中，只是加上说明标记
- **标注格式**：在质疑点后追加 `💤 可延后：AI 编码时通常会自行处理此细节，可在实现阶段关注`
- **过滤不影响 challenger 原始输出**：过滤是在 challenger 报告之上附加标注，不修改原报告内容

### Step 8：影响面缺口（条件出口，不自动执行）

**为什么单独一步**：Step 2~7 审的是"**写进去的文件质量**"；本步判的是"**这次写入有没有把别处写坏**"。后者最容易漏——签名 / 返回值 / 字段一改，被改文件单看完全正确，调用方仍按旧契约，而调用方不在本次 diff 里。能穷举这类影响面的只有 `code-change-impact`。

**适用范围**：**仅当本次写入包含代码文件**（`.py` / `.ts` / `.go` / `.java` / `.rs` / `.sh` 等）时执行。纯文档改动（`.md` / `.json` 配置说明类）**跳过本步**——文档没有"调用方"，它的影响面就是引用它的地方，已由链接检查覆盖。

**判据**（命中任一，用实际取数不靠感觉）：

| 信号 | 判定方式 |
|------|----------|
| 改动触及**契约面** | 函数签名 / 返回值 / 异常类型 / API 路由 / DTO / 事件格式 / 表结构 / 字段 / 枚举值 / 配置项 |
| 被改符号**被 ≥3 处引用** | 符号查询或 grep 的实际命中数 |
| 本次写入**跨 ≥2 个模块** | 同一任务的多文件改动 |

**动作**（建议而非执行）：在交付说明末尾追加一行，不阻塞交付：

```text
⚠️ 影响面未覆盖：本次改了 {签名 X / 表字段 Y}，建议转 code-change-impact 补齐调用方与回归风险清单（确认调用方已同步可忽略）
```

**不自动执行的理由**：`code-change-impact` 的取数是**穷举级**（Step 3 要求逐消费方取证），成本远高于一次文件质量审查；此时用户可能只想确认"这个文件写得对不对"。给出依据，由用户决定。

**去重**（避免重复提示）：

- 本会话已对同一改动执行过 `code-change-impact` → 跳过
- `code-review` 已按其约束 22 转过 `code-change-impact` → 跳过
- 已由 Step 6 的 challenger 补齐影响面清单 → **仍需提示，但改写为**「影响面清单来自质疑环节，未做穷举取证」——challenger 查的是"结论站不站得住"，不等于穷举影响面

**与 Step 6/7 的关系**：challenger 质疑"结论对不对"（Step 6-7），本步判断"影响面查全没有"，两者不互相替代；都命中时**先跑完 Step 6-7 再给本步提示**，不打断质疑链。

**降级**：`code-change-impact` 未安装 → 仅提示"建议人工梳理调用方"，不报错、不阻塞。

## 跳过机制

以下情况跳过自动审查（不执行审查流程）：
- 用户明确说"不需要审查"、"跳过审查"、"不用 review"
- 仅修改单个字符/标点符号的微小变更
- 用户使用 `--no-review` 标记

以下情况跳过 challenger 二次质疑（但不跳过 auto-review）：
- 用户明确说"不用质疑"、"跳过 challenger"
- 修改明确属于非复杂场景（见 Step 6 判断表）

## 输出规范

审查通过后的输出格式：

```
✅ 自动审查通过（第 N 轮）

文件：{文件路径}
审查方式：{skill名称 / 通用审查}
结论性质：静态检查（未实际运行）/ 已验证（实际执行了 {命令/测试}）
发现问题：X 个（均已修复）
影响面：已覆盖 / ⚠️ 未覆盖（命中 Step 8，见下方建议）
```

> 「影响面」行仅在 Step 8 命中时写；未命中可省略整行。命中时在输出末尾追加一行转交建议（`code-change-impact`），**不作为审查未通过的标志**。

## 示例

**场景 1：AI 创建了一个 Skill 文件（专项审查）**

```
1. AI 用 write_to_file 写入 skills/new-skill/SKILL.md
2. 触发 auto-review 规则
3. 识别为 Skill 文件（位于 skills/ 目录）
4. 专项审查：
   - YAML frontmatter：缺少 description 字段 → 自动补充
   - description 格式：正确（紧跟描述）
   - AI 说明层：缺少"概述"部分 → 自动补充
5. 重新审查：通过
6. 复杂场景判断：仅文档补充，不属于复杂场景 → 跳过 challenger
7. 交付用户
```

**场景 2：AI 创建了一个 Rules 文件（专项审查）**

```
1. AI 用 write_to_file 写入 rules/new-rules.md
2. 触发 auto-review 规则
3. 识别为 Rules 文件（位于 rules/ 目录）
4. 专项审查：
   - YAML frontmatter：缺少 alwaysApply 字段 → 自动补充默认值 true
   - description 格式：正确（紧跟描述）
   - alwaysApply 字段：值为 true，正常
   - 规则结构：完整
5. 重新审查：通过
6. 交付用户
```

**场景 3：AI 修改了一个 Rules 文件，设置 alwaysApply 为 false（提醒用户）**

```
1. AI 用 replace_in_file 修改 rules/existing-rules.md，将 alwaysApply 设置为 false
2. 触发 auto-review 规则
3. 识别为 Rules 文件（位于 rules/ 目录）
4. 专项审查：
   - YAML frontmatter：正确
   - description 格式：正确（紧跟描述）
   - alwaysApply 字段：值为 false → 提醒用户：该规则不会自动应用，需要手动启用
5. 用户确认：确认设置为 false
6. 重新审查：通过
7. 交付用户
```

**场景 4：AI 编写了一个 Python 脚本（复杂场景 → 触发 challenger → 代码层面过滤）**

```
1. AI 用 write_to_file 写入 script.py（新增函数 + 异常处理 + 涉及数据持久化）
2. 触发 auto-review 规则
3. 查找 skill：code-review 存在 → 使用 skill 审查
4. code-review 发现：缺少 docstring、未处理异常
5. AI 自动修复：添加 docstring + try/except
6. 重新审查：通过
7. 复杂场景判断：新增功能 + 关键路径 → 属于复杂场景
8. 自动调用 challenger，选择「新增功能」质疑策略
9. challenger 深度质疑：发现边界条件未覆盖、建议加并发锁、建议加强输入校验
10. Step 7 过滤评审：
    - 「边界条件未覆盖」→ 非代码层面（业务逻辑完整性）→ 保留
    - 「建议加并发锁」→ 代码层面 → 判断：不明确约定 AI 可能用错锁粒度 → 保留
    - 「建议加强输入校验」→ 代码层面 → 判断：通用实践，AI 编码时自然会处理 → 标注「可延后」
11. 输出过滤后的报告，用户关注保留的 2 个问题
12. 交付用户
```

**场景 5：AI 修改了一个 .sh 脚本（简单场景 → 跳过 challenger）**

```
1. AI 用 replace_in_file 修改 deploy.sh
2. 触发 auto-review 规则
3. 查找 skill：无 shell 专项 skill
4. 通用审查：发现未引用的变量
5. AI 自动修复
6. 重新审查：通过
7. 复杂场景判断：仅变量清理，不属于复杂场景 → 跳过 challenger
8. 交付用户
```

**场景 6：AI 编写了设计文档（触发 challenger → 设计文档场景过滤）**

```
1. AI 用 write_to_file 写入 design/module-design.md（技术设计文档）
2. 触发 auto-review 规则
3. 查找 skill：design-review 存在 → 使用 skill 审查
4. design-review：通过
5. 复杂场景判断：新增功能 + 跨模块影响 → 属于复杂场景
6. 自动调用 challenger
7. challenger 产出质疑报告：
    - 质疑1：接口只定义了成功响应，未定义错误码体系（非代码层面 → 保留）
    - 质疑2：数据库表缺少 created_at 索引（非代码层面 → 保留）
    - 质疑3：方法参数应该做空值校验（代码层面 → 判断：通用实践 → 标注「可延后」）
    - 质疑4：日志应该统一使用结构化格式（代码层面 → 判断：通用实践 → 标注「可延后」）
    - 质疑5：缓存 key 的命名规范未约定（代码层面 → 判断：不约定 AI 可能用不一致的命名 → 保留）
8. Step 7 过滤评审完成，输出报告：
    - 保留 3 个质疑（接口错误码、索引、缓存命名）
    - 标注 2 个可延后（空值校验、日志格式）
9. 用户看到已分类的报告，优先处理保留的架构级问题
10. 交付用户
```