代码评审问题追踪闭环 · Vibe Coding 工具集

在 AI 辅助编码（Vibe Coding）场景下，把"评审—修复—验证"做成可追踪、可回溯、可防重复的闭环。 不再依赖对话历史记录，所有评审问题都有唯一编号 + 状态机。

---

这是什么

如果你正在用 AI 编程助手（Claude / Cursor / Trae 等）做大项目，应该遇到过这些问题：

• 同一问题被反复评估：AI 没记忆，下次评审又把"已决定不修"的问题报一遍
• 评审报告散落在对话里：找不到上次评了什么、修到哪一步
• 修复进度无法追踪：哪些已修、哪些待验证、哪些暂缓，全靠脑子记
• 新人/AI 接手时无据可依：不知道某个问题当初为什么这样处理

这套工具集就是为了解决以上痛点，它提供：

1. 结构化的评审产物：每条问题一个 .md 文件，编号终身不变
2. 状态机：pending_review → reviewed_fix → fixing → fixed → verified，每一步可追溯
3. 跨批次编号：第 1 次评审分配 L001-L018，第 2 次从 L019 开始，永不冲突
4. 指令速查：对 AI 说"修复 L002"，AI 自动读索引定位文件并执行修复流程
5. 录入问题工作流：非正式评审场景下零星发现的问题也能录入体系

---

目录结构

code-review-issues/
├── README.md                  # 本文件
├── review-prompt.md            # 核心：评审提示词 V1 + V2 + 修复指令速查
├── template-issue.md          # 单问题详情模板（AI 填空用）
├── review-index.md            # 问题索引表（当前状态总览，AI 必读）
├── review-changelog.md        # 状态变更日志（只追加）
└── review-batches/            # 评审批次文件夹
    └── YYYY-MM-DD-reviewNN/    # 每次评审一个文件夹
        ├── REVIEW-REPORT.md    # 完整报告（只读快照）
        ├── REVIEW-SUMMARY.md   # 摘要（统计 + 清单）
        └── details/            # 单问题详情
            ├── H001.md
            ├── M001.md
            └── L001.md

---

快速开始

1. 把整个文件夹放进你的项目

建议放在项目根目录的 docs/code-review-issues/ 或类似位置，AI 通过相对路径访问。

2. 首次使用前：清空索引和日志

review-index.md 和 review-changelog.md 已提供空模板（含示例注释，可保留作为格式参考）。 首次评审前不需要修改，AI 会按模板格式追加。

3. 配置 AI 评审规则

将 review-prompt.md 中的"V2 评审提示词"代码块内容，加入到你的 AI 助手的系统提示词或项目规则文件中。

关键配置项（在提示词中替换）：

• <你的项目路径>/docs/PRD.md → 你项目的 PRD 文档路径
• <你的项目路径>/frontend → 你项目的前端代码目录
• <你的项目路径>/backend → 你项目的后端代码目录

4. 发起一次评审

对 AI 说：

请基于代码和 PRD 完成一次全面评审，按 review-prompt.md 的 V2 流程输出评审产物。

AI 会按以下顺序产出：

1. 创建批次文件夹 review-batches/YYYY-MM-DD-review01/
2. 写 REVIEW-REPORT.md（完整报告，按等级排序）
3. 写 REVIEW-SUMMARY.md（统计 + 三类清单）
4. 写 details/H001.md、M001.md、L001.md（每问题一个文件）
5. 追加 review-index.md（每问题一行）
6. 追加 review-changelog.md（每问题一行状态变更）

5. 修复问题

评审完成后，对 AI 说：

你说	AI 做什么
讨论 L002	展示 L002 的推荐方案和评估结论，等你确认
修复 L002	状态 → fixing → 执行代码修复 → 状态 → fixed → 提示验证
L003 不修	状态 → reviewed_skip，填不修理由
L010 暂缓，等后端接口实现	状态 → reviewed_defer，填回顾条件
L002 验证通过	状态 → verified
待修复清单	筛选 reviewed_fix 状态的问题按等级排序展示
批次概览	按批次分组展示所有问题

完整指令列表见 review-prompt.md 第三节"修复指令速查"。

---

状态机

pending_review → reviewed_fix → fixing → fixed → verified
                → reviewed_skip（不修，附理由）
                → reviewed_defer（暂缓，附回顾条件）
verified → regression（回归，需重新评估）

状态	含义
pending_review	刚录入，未评估（录入问题工作流专用）
reviewed_fix	已评估，建议修复
reviewed_skip	已评估，决定不修（误报 / 有意设计 / 已有等效防护）
reviewed_defer	已评估，暂缓（收益有限 / 依赖未完成功能）
fixing	正在修复
fixed	已修复，待验证
verified	已验证修复有效
regression	修复后又复现（回归）

---

等级定义

等级	含义	处理时效
H（高危）	安全漏洞、数据丢失、功能不可用	立即修复
M（中危）	部分功能异常、性能问题、代码质量	计划修复
L（低危）	代码风格、文档、可维护性	视情况修复

编号格式：H001、M001、L001（前缀 + 三位数字）。

---

两种使用模式

模式 A：正式评审（推荐用于里程碑节点）

1. AI 完整扫描代码库
2. 按 V2 提示词输出 5 类产物（REPORT / SUMMARY / details / INDEX / CHANGELOG）
3. 用户基于 SUMMARY 决定修复优先级
4. 逐个问题用 修复 {编号} 指令处理

模式 B：录入问题（推荐用于日常开发零星发现）

非正式评审场景下发现的新问题，逐个录入：

录入问题 H 部署后静态资源 404
录入问题 M nginx 反代丢失 X-Forwarded-Proto

录入后状态为 pending_review，后续通过 讨论 {编号} 评估，再流转到 reviewed_fix / reviewed_skip / reviewed_defer。

详见 review-prompt.md 第四节"录入问题指令"。

---

防 AI 重复评估机制

这是这套体系最核心的价值：

• AI 每次评审前强制读 review-index.md
• 状态为 reviewed_skip / reviewed_defer 的问题 → 禁止重复评估，直接引用已有结论
• 状态为 fixed / verified 的问题 → 禁止重复修复
• 新评审从当前等级最大编号 +1 开始分配，永不冲突

效果：第 5 次评审时，AI 会自动跳过前 4 次已处理的问题，只评估新代码引入的新问题。

---

与代码变更日志的关系

日志	用途	写入时机
review-changelog.md	评审问题状态变更	AI 自动（评审/修复流程的一部分）
CHANGELOG.md（项目级）	代码变更	修复完成后由 AI 主动发起草案 → 用户确认 → 写入

两者严格区分，互不覆盖。

---

License

MIT

---

Trae 操作案例

以一个典型 Web 项目为例，演示在 Trae IDE 中从配置→评审→修复→验证的完整流程。

案例背景

• 项目：假设是一个 FastAPI + SQLAlchemy + 原生 JS 前端项目
• 评审目录：docs/code-review-issues/（你可以放在项目的任意位置）
• Trae 规则文件：.trae/rules/project_rules.md

注意：本案例路径假设评审目录是 docs/code-review-issues/，如果你的评审目录在其他位置（如项目根目录的 code-review-issues/），请相应调整所有路径。

---

第 1 步：配置 Trae 评审规则

在项目根目录创建或编辑 .trae/rules/project_rules.md，追加以下内容：

## 评审问题追踪闭环规范（强制）

> **核心原则**：评审问题必须结构化存储、状态可追踪、防止重复评估。
> **详细提示词和指令速查**：`docs/code-review-issues/review-prompt.md`

### 文件结构

docs/code-review-issues/
├── review-index.md          # 评审问题索引（当前状态，AI 必读）
├── review-changelog.md      # 评审状态变更日志（只追加）
├── template-issue.md        # 问题详情模板
└── review-batches/          # 评审批次文件夹
    └── YYYY-MM-DD-reviewNN/ # 每次评审一个文件夹
        ├── REVIEW-REPORT.md # 完整报告（只读快照）
        ├── REVIEW-SUMMARY.md # 摘要
        └── details/         # 单问题详情（H00X.md / M00X.md / L00X.md）

### 评审前（强制）

1. 读取 `docs/code-review-issues/review-index.md`
2. 已登记且状态为 `reviewed_skip` / `reviewed_defer` 的问题 → **禁止重复评估**，直接引用已有结论
3. 已登记且状态为 `fixed` / `verified` 的问题 → **禁止重复修复**
4. 新评审从当前等级最大编号 +1 开始分配（H/M/L 各自递增，编号全局唯一终身不变）

### 评审产物输出（强制）

5 类文件缺一不可：
1. `REVIEW-REPORT.md` — 完整报告（只读快照）
2. `REVIEW-SUMMARY.md` — 摘要（统计 + 建议修复/不修/暂缓清单）
3. `details/H00X.md`、`M00X.md`、`L00X.md` — 单问题详情（按 template-issue.md 模板）
4. 更新 `review-index.md` — 追加本次所有问题行
5. 追加 `review-changelog.md` — 每个问题一行状态变更

### 状态变更时（强制，3 处同步更新）

| 文件 | 更新方式 | 更新内容 |
|------|---------|---------|
| `details/{编号}.md` | Edit | 更新"元数据.状态" + 追加"变更历史" + 填写对应段落 |
| `review-index.md` | Edit | 更新该编号行的"状态"和"最后更新"列 |
| `review-changelog.md` | 追加 | 追加一行：`- {编号}: {旧状态} → {新状态}（{说明}）` |

关键点：

• 路径必须与你项目的实际目录匹配（本案例假设是 docs/code-review-issues/）
• 这段规则会在每次评审前被 AI 强制执行

---

第 2 步：发起第一次评审

在 Trae 对话框中发送：

请基于代码和 PRD 完成一次全面评审，按 review-prompt.md 的 V2 流程输出评审产物。

AI 执行过程：

1. 读取 review-index.md（发现是空的，跳过去重检查）
2. 扫描代码库（后端 app/、前端 frontend/、PRD 文档）
3. 创建批次文件夹：review-batches/2026-06-22-review01/
4. 输出评审产物：
   • REVIEW-REPORT.md（完整报告，70 个问题按等级排序）
   • REVIEW-SUMMARY.md（统计：25 H / 27 M / 18 L + 三类清单）
   • details/H001.md ~ L018.md（每个问题一个文件）
5. 更新索引：追加 70 行到 review-index.md
6. 追加日志：追加 70 行到 review-changelog.md

输出示例（review-index.md 前 5 行）：

| 编号 | 标题 | 状态 | 批次 | 最后更新 |
|------|------|------|------|---------|
| H001 | JWT 密钥硬编码在代码中 | reviewed_fix | 2026-06-22-review01 | 2026-06-22 10:30 |
| H002 | /api/admin/* 无认证保护 | reviewed_fix | 2026-06-22-review01 | 2026-06-22 10:30 |
| M001 | N+1 查询：角色列表未预加载关联 | reviewed_fix | 2026-06-22-review01 | 2026-06-22 10:30 |

---

第 3 步：查看待修复清单

在 Trae 对话框中发送：

待修复清单

AI 执行过程：

1. 读取 review-index.md
2. 筛选 状态 = reviewed_fix 的问题
3. 按等级排序（H → M → L）展示

AI 回复示例：

当前待修复问题（共 70 个）：

高危（25 个）：
- H001: JWT 密钥硬编码在代码中
- H002: /api/admin/* 无认证保护
...

中危（27 个）：
- M001: N+1 查询：角色列表未预加载关联
...

低危（18 个）：
- L001: 前端 console.log 未清理
...

---

第 4 步：修复高危问题 H001

在 Trae 对话框中发送：

修复 H001

AI 执行过程：

1. 读取 review-index.md → 找到 H001 在批次 2026-06-22-review01
2. 读取 review-batches/2026-06-22-review01/details/H001.md
3. 状态流转：reviewed_fix → fixing
4. 执行代码修复（比如：把 JWT 密钥移到环境变量）
5. 状态流转：fixing → fixed
6. 同步更新 3 处文件：
   • details/H001.md：更新"元数据.状态"为 fixed，追加"变更历史"
   • review-index.md：更新 H001 行的"状态"为 fixed
   • review-changelog.md：追加 - H001: reviewed_fix → fixing → fixed（JWT 密钥已移到环境变量）
7. 提示用户验证

修复后的 details/H001.md 片段：

## 元数据

| 字段 | 值 |
|------|---|
| 状态 | `fixed` |
...

## 变更历史

### 2026-06-22 14:30 — reviewed_fix → fixing
- 开始修复

### 2026-06-22 14:35 — fixing → fixed
- 已将 JWT_SECRET 从代码移到环境变量
- 已更新 backend/app/core/config.py
- 需在 .env 中配置 JWT_SECRET=your-secret-key

---

第 5 步：验证修复

在 Trae 对话框中发送：

验证 H001

AI 执行过程：

1. 读取 details/H001.md 确认当前状态是 fixed
2. 检查修复后的代码（确认 JWT 密钥已移到环境变量）
3. 状态流转：fixed → verified
4. 同步更新 3 处文件

---

第 6 步：标记不修的问题

对于评审后决定不修复的问题：

H025 不修，这是开发环境的默认配置，生产环境会用反向代理强制 HTTPS

AI 执行过程：

1. 状态流转：reviewed_fix → reviewed_skip
2. 在 details/H025.md 填写"不修理由"章节
3. 同步更新 3 处文件

效果：后续评审时，AI 会跳过 H025，直接引用"不修理由"。

---

第 7 步：暂缓问题

对于需要等其他功能完成后再修的问题：

L010 暂缓，等后端 WebSocket 接口实现后再修

AI 执行过程：

1. 状态流转：reviewed_fix → reviewed_defer
2. 在 details/L010.md 填写"暂缓理由"和"回顾条件"
3. 同步更新 3 处文件

后续回顾时：

暂缓清单

AI 会展示所有 reviewed_defer 状态的问题及其回顾条件。

---

第 8 步：录入新发现问题

在日常开发中发现新问题，不需要发起完整评审：

录入问题 M 新增的导出接口缺少文件大小限制

AI 执行过程：

1. 分配编号 M028（假设当前最大是 M027）
2. 创建新批次 review-batches/2026-07-26-review02/
3. 创建 details/M028.md（状态为 pending_review）
4. 追加到 review-index.md
5. 追加到 review-changelog.md

后续评估：

讨论 M028

AI 会展示 M028 详情，等你确认是否修复，再流转状态。

---

第 9 步：发起第二次评审（自动跳过已处理问题）

一周后，代码有新增功能，再次评审：

请基于代码和 PRD 完成一次全面评审，按 review-prompt.md 的 V2 流程输出评审产物。

AI 执行过程：

1. 读取 review-index.md
2. 自动跳过已登记的 70 个问题（H001-L018）
3. 新问题从 H026、M028、L019 开始编号
4. 只评估新代码引入的新问题

效果：第二次评审不会重复报告 H001-L018，避免"评审疲劳"。

---

总结：Trae 用户的核心收益

痛点	本工具集如何解决
同一问题被反复评估	AI 强制读索引，跳过已处理问题
评审报告散落对话历史	结构化 .md 文件，编号终身不变
修复进度无法追踪	状态机 + 3 处同步更新
新人/AI 接手无据可依	每个问题有详情文件，含评估结论、推荐方案、变更历史

一句话：把"评审—修复—验证"做成文件驱动的闭环，不再依赖对话记忆。