概述

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

功能：自动触发质量审查与修复闭环，支持 Skill/Rules 文件专项审查、代码审查、通用文档审查，并自动判断是否需要二次质疑

使用场景：

• AI 使用 write_to_file 或 replace_in_file 写入 .md / 代码文件后自动执行
• 需要验证 Skill/Rules 文件是否符合 YAML frontmatter 和 AI 说明层规范时
• 需要对代码变更进行质量审查时

自动审查规则

核心原则

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 报告之上附加标注，不修改原报告内容

跳过机制

以下情况跳过自动审查（不执行审查流程）：

• 用户明确说"不需要审查"、"跳过审查"、"不用 review"
• 仅修改单个字符/标点符号的微小变更
• 用户使用 --no-review 标记

以下情况跳过 challenger 二次质疑（但不跳过 auto-review）：

• 用户明确说"不用质疑"、"跳过 challenger"
• 修改明确属于非复杂场景（见 Step 6 判断表）

输出规范

审查通过后的输出格式：

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

文件：{文件路径}
审查方式：{skill名称 / 通用审查}
结论性质：静态检查（未实际运行）/ 已验证（实际执行了 {命令/测试}）
发现问题：X 个（均已修复）

示例

场景 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. 交付用户