ECC Review Mode 实战解析：为 AI 编码代理构建"流程—清单—分级"一体化的代码审查上下文

作为 ECC（Everything Claude Code 风格 agent 工作流体系）在 Kiro 场景下的落地形态，.kiro/steering/review-mode.md 是一份以"手动方式按需注入"的审查模式（Review Mode）上下文文件：它把一次高质量代码审查拆解为"五步流程 + 五类检查清单 + 四级严重度分级"的可执行规范，并在 #review-mode 指令被触发后让 AI 代理进入严格的审查心智。本文以该文档为主体骨架，结合仓库中 code-reviewer 代理、security.md 等 steering 文件与 code-review-on-write 等钩子实现，说明如何在日常 AI 辅助开发中把它当作"每一次变更合入前都值得跑一遍"的质量关卡。

一、Review Mode 是什么：按需激活的代码审查上下文

Review Mode 位于 .kiro/steering/review-mode.md，文件头部通过 YAML frontmatter 声明了它的加载策略：

---
inclusion: manual
description: Code review context mode for thorough quality and security assessment
---

inclusion: manual 意味着它不会被自动注入每次对话，而是由用户显式触发（#review-mode），这一点与同目录下的 #dev-mode、#research-mode 一脉相承。对比 .kiro/steering/coding-style.md 的 inclusion: auto（随会话自动加载）与语言类 steering 的 inclusion: fileMatch（如编辑 *.ts 时自动加载 .kiro/steering/typescript-patterns.md），可以清晰地看到 steering 文件机制的三档粒度：

加载方式	语义	仓库示例
auto	每个会话都生效，承载"始终成立"的团队规范	.kiro/steering/coding-style.md、.kiro/steering/security.md、.kiro/steering/testing.md
fileMatch	命中文件模式时生效，做语言/框架级约束	.kiro/steering/python-patterns.md、.kiro/steering/typescript-security.md
manual	仅在用户显式唤醒时注入，用于"模式切换"型场景	.kiro/steering/review-mode.md、.kiro/steering/dev-mode.md、.kiro/steering/research-mode.md

设计意图：审查是一项重上下文、重心智的任务，若把冗长的审查规则常驻在每次会话中，反而会稀释开发模式下的注意力。Review Mode 采用"平时不打扰、需要时全套就位"的策略——一旦被 #review-mode 唤醒，代理就能立即切换到以"发现问题、定位缺陷、评估风险"为核心的审查状态。从 .kiro/README.md 的组件清单看，.kiro/steering/ 共提供 22 个 steering 文件，其中 19 个为自动/按文件加载，3 个 manual 模式文件共同构成面向"开发—审查—研究"三种工作场景的显式上下文切换。

二、五步审查流程：从 git diff 到分级结论的标准化路径

review-mode.md 把审查抽象为 5 个严格串行的步骤（原文见 .kiro/steering/review-mode.md）。每一步都不是空泛口号，而是在仓库代理实现中有明确对应的可执行动作：

1. Gather context   —— 查看 git diff，掌握全部变更
2. Understand scope —— 判断哪些文件变了、为什么变
3. Read surrounding —— 通读周边代码，拒绝"孤立审查"
4. Apply checklist  —— 逐类过一遍检查清单
5. Report findings  —— 按严重级别输出结论

第 1 步：Gather context——先看完整差异，再谈判断

"Check git diff to see all changes" 在 .kiro/agents/code-reviewer.md 中被落实为具体命令：

Run git diff --staged and git diff to see all changes. If no diff, check recent commits with git log --oneline -5.

这意味着审查的输入集不是"代理猜出来的变更"，而是版本控制系统记录的精确差异：暂存区（--staged）加工作区（未暂存）共同构成完整变更面，无差异时再回退到最近 5 条提交。从源码结构看，这种"diff 优先、提交兜底"的策略能保证：即使代码已被提交或暂存，Review Mode 依然能重建完整的审查现场，不会因为遗漏未暂存部分而误判。

第 2 步：Understand scope——变更与业务意图挂钩

"Identify which files changed and why" 要求代理把"文件名列表"翻译成"业务语义"：此次改动属于新增特性、缺陷修复还是重构？文件之间的依赖关系如何？这一步决定了后续 checklist 的侧重——例如涉及鉴权的改动要把 Security 相关项推到最高优先级，而纯样式改动则不必在性能项上纠缠。

第 3 步：Read surrounding code——拒绝孤立审查

review-mode.md 明确写道 "Don't review in isolation"。code-reviewer 代理将其展开为 "Read the full file and understand imports, dependencies, and call sites"。单一 diff 片段往往无法暴露真实问题：一个函数在调用方眼中可能违反既有约定，一个"看起来正确"的重构可能破坏下游契约。只有通读 import、依赖与被调用点，才能区分"变更引入的缺陷"与"本就存在的存量问题"。

第 4 步：Apply review checklist——按序过五类清单

即进入下文第三节的五类检查清单。值得注意的实现细节是，code-reviewer 代理要求"从 CRITICAL 到 LOW 逐类推进"（work through each category below, from CRITICAL to LOW），即先扫最高风险，再逐级下沉，保证有限上下文中最高危的问题最先被覆盖。

第 5 步：Report findings——只报告高置信度结论

"Use severity levels" 不只是输出格式要求，还隐含一道置信度过滤阀。code-reviewer 代理对此有量化约束：

• 仅在 >80% 确信是真实问题时才报告；
• 跳过纯粹的个人风格偏好（除非违反项目约定）；
• 跳过未变更代码中的问题（CRITICAL 安全缺陷除外）；
• 合并同类项（例如报"5 个函数缺少错误处理"，而不是 5 条零散发现）；
• 优先暴露可能导致 bug、安全漏洞或数据丢失的问题。

这道过滤阀直接决定了 Review Mode 输出是"可执行的评审意见"还是"淹没真问题的噪音列表"。

三、五类检查清单：把"好不好"翻译成可逐条核验的问题

review-mode.md 的核心资产是 .kiro/steering/review-mode.md 中按 Correctness、Security、Performance、Maintainability、Testing 五类组织的检查项。下面逐一展开，并结合仓库内同主题资产说明每一项在实战中的落点。

3.1 Correctness（正确性）——地基项

• Does the code do what it's supposed to do?（行为是否符合预期）——核对 diff 是否真正实现了第 2 步锁定的业务意图，而非"编译通过但与需求南辕北辙"。
• Are edge cases handled properly?（边界情况是否完备）——空输入、超长输入、并发、时间边界、资源耗尽等，往往是缺陷高发区。code-reviewer 在审查 AI 生成代码的补充条款中亦把 "behavioral regressions and edge-case handling" 列为首要关注点（见 .kiro/agents/code-reviewer.md 的 v1.8 Addendum）。
• Is error handling appropriate?（错误处理是否得当）——对应 code-reviewer 清单里的 "Missing error handling"（未处理的 Promise rejection、空 catch 块等），同时要警惕错误信息向客户端泄露内部细节的反模式。

3.2 Security（安全性）——输入、密钥与注入的三重防线

Review Mode 的安全性清单与 .kiro/steering/security.md（inclusion: auto 常驻规则）互为表里。security.md 在"每次提交前"强制勾选 8 项：无硬编码密钥、所有用户输入经过校验、SQL 注入防护（参数化查询）、XSS 防护（HTML 消毒）、CSRF 防护开启、鉴权/授权核实、端点限流、错误信息不泄漏敏感数据。

code-reviewer 代理则给出**必须标记（MUST be flagged）**的安全项清单，每个都附正反例：

• 硬编码凭据（API key、口令、token、连接串出现在源码）；
• SQL 注入——字符串拼接查询而非参数化查询（.kiro/agents/code-reviewer.md 中给出 SELECT * FROM users WHERE id = ${userId} 的 BAD 与 id = $1 配合参数数组的 GOOD 对照）；
• XSS——未消毒的用户输入直接渲染进 HTML/JSX（要求经 DOMPurify.sanitize() 或等价手段处理）；
• 路径穿越、CSRF 缺失、认证绕过、已知漏洞依赖、日志中暴露密钥/PII。

值得注意的关联：当 Review Mode 在安全项上命中真实缺陷时，security.md 的安全响应协议要求"立即停止→切换到 security-reviewer 代理→修复 CRITICAL→轮换可能泄露的密钥→全库排查同类问题"，而 .kiro/skills/security-review/ 技能可提供更完整的 OWASP Top 10 级检查清单作为纵深补充。

3.3 Performance（性能）——查询与缓存的靶点

Review Mode 的性能清单聚焦三问：

• 是否有明显性能问题？——code-reviewer 将其细化为低效算法（可 O(n) 却写成 O(n²)）、同步 I/O 阻塞在异步上下文、大包体导入整库等；
• 数据库查询是否优化？——仓库对后端审查的补充项非常具体：SELECT * 或无 LIMIT 的无界查询、循环内逐条取关联数据的 N+1 查询（并给出 JOIN/json_agg 的修正范式）、用户态端点缺少限流、外部调用缺失超时配置。若审查对象涉及 SQL/ORM 层，可直接切换到 database-reviewer 代理做模式、索引与迁移安全级的专项核验；
• 缓存使用是否恰当？——重复昂贵计算不做 memoization、React 场景漏用 React.memo/useMemo/useCallback、大图不做压缩与懒加载等，均为常见失分项。

3.4 Maintainability（可维护性）——可读性、粒度与文档

• 代码可读、组织良好——code-reviewer 给出可量化的阈值经验：函数超过 50 行、文件超过 800 行、嵌套超过 4 层即触发拆分/提前返回的改造建议；console.log 调试语句、注释掉的死代码、未使用 import、不可达分支也属于此范畴。这些阈值与 .kiro/steering/coding-style.md 的常驻风格规则（不可变性优先、文件组织、错误处理、代码质量标准）互补；
• 函数与类粒度适中——聚焦单一职责，避免"上帝函数"；
• 文档充分——公共 API 缺 JSDoc/导出函数无注释、TODO/FIXME 不挂接 issue 编号都记为维护性债务；
• 命名遵循约定——非平凡上下文中出现单字母变量（x/tmp/data）、魔法数字无解释等，即使不至于阻断合入，也构成 LOW 级提示。

3.5 Testing（测试）——覆盖、边界与可维护性

• 测试是否充足？——项目级常驻规范 .kiro/steering/testing.md 以 80% 覆盖率作为最低门槛并强制 TDD 工作流，与 Review Mode "Are there sufficient tests?" 相互印证；新代码路径没有测试覆盖在 code-reviewer 中被直接归为 HIGH 级问题；
• 边界用例是否覆盖？——空值、异常路径、错误条件都应出现在单测中；
• 测试是否清晰可维护？——描述性命名、稳定快速，避免脆弱断言。

四、四级严重度分级：让每条发现带着"处置优先级"流动

review-mode.md 规定所有发现必须挂四级严重度（.kiro/steering/review-mode.md）：

级别	判定口径	典型处置
Critical	安全漏洞、数据丢失风险	合入前必须修复（Block）
High	破坏功能的 Bug、重大性能问题	强烈建议合入前修复（可谨慎合入，Warn）
Medium	代码质量问题、可维护性隐患	记录并排期处理（Info）
Low	风格不一致、微小改进	作为备注参考（Note）

这四级分级并不是孤立定义——仓库中的 code-reviewer 代理为它提供了完整的产出模板，使分级可被机器与人都无歧义地消费：

[CRITICAL] Hardcoded API key in source
File: src/api/client.ts:42
Issue: API key "sk-abc..." exposed in source code...
Fix: Move to environment variable and add to .gitignore/.env.example

  const apiKey = "sk-abc123";           // BAD
  const apiKey = process.env.API_KEY;   // GOOD

每次评审以汇总表收尾并给出 verdict：

## Review Summary

| Severity | Count | Status |
|----------|-------|--------|
| CRITICAL | 0     | pass   |
| HIGH     | 2     | warn   |
| MEDIUM   | 3     | info   |
| LOW      | 1     | note   |

Verdict: WARNING — 2 HIGH issues should be resolved before merge.

与之配套的合入判定标准同样清晰：Approve＝无 CRITICAL/HIGH；Warning＝仅有 HIGH（可谨慎合入）；Block＝存在 CRITICAL，必须先修再合。可以说，review-mode.md 定义了分级的"语义标尺"，而 code-reviewer 代理定义了"如何用这把尺子说话"，两者叠加便构成一套从检查到合入门的闭环策略。

五、在代理工作流中调用 Review Mode：#review-mode 的正确姿势

5.1 触发方式

review-mode.md 的 Invocation 一节明确：审查代码时使用 #review-mode 激活本上下文。在 Kiro 会话中的典型用法（与 .kiro/README.md 的手动上下文示例一致）：

# 在会话中显式进入审查模式
> #review-mode
> "Review all changes in the current PR"

# 或直接以 code-reviewer 代理开启审查会话
kiro-cli --agent code-reviewer
> "Review the changes in src/api/users.ts"

5.2 与 manual/auto steering 的协作关系

进入 Review Mode 时，常驻的 auto 类 steering（coding-style、security、testing、development-workflow、git-workflow 等）依然生效——它们构成"始终成立的基线"，而 review-mode 补充的是审查态专属的心智与步骤。这种分层设计避免了两种极端：全部常驻导致的上下文臃肿，以及审查时无章可循的漫无目的。

5.3 与审查代理生态的串联

.kiro/README.md 给出的推荐工作流把 Review Mode 嵌进了完整研发链：写完代码 → 切换到 code-reviewer 审查 → 涉及认证/API/敏感数据时换 security-reviewer 深挖 → 合入前触发 quality-gate 钩子做全量构建/类型/lint/测试 → 建 PR 前跑 verification-loop 技能做构建、类型、lint、测试、安全扫描与 diff 复核的全面验证。Review Mode 正是这条链上"由人显式接管审查心智"的开关，其余环节则由 agent 与钩子自动衔接。

六、把审查从"手动模式"扩展为"自动防线"：钩子与技能闭环

Review Mode 解决的是"主动审查时怎么做"，而仓库中的钩子体系负责把 checklist 的核心关切嵌入每一次写盘、推送与提交之前，形成被动防线：

6.1 code-review-on-write：写盘即轻量审查

.kiro/hooks/code-review-on-write.kiro.hook 在每次 write 工具调用后触发一次快速审查，其 prompt 与 review-mode 的四类检查点几乎一一对应：

{
  "name": "code-review-on-write",
  "version": "1.0.0",
  "enabled": true,
  "description": "Performs a quick code review after write operations to catch common issues",
  "when": {
    "type": "postToolUse",
    "toolTypes": ["write"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Code was just written or modified. Perform a quick review checking for: 1) Common security issues (SQL injection, XSS, etc.), 2) Error handling, 3) Code clarity and maintainability, 4) Potential bugs or edge cases. Only comment if you find issues worth addressing."
  }
}

注意其收尾约束 "Only comment if you find issues worth addressing"——与 code-reviewer 的置信度过滤是同一种反噪音哲学。

6.2 git-push-review 与 quality-gate：推送/合入门

• .kiro/hooks/git-push-review.kiro.hook 拦截 git push 之前的 shell 命令，先做一次质量确认再放行推送；
• .kiro/hooks/quality-gate.kiro.hook 为手动触发（userTriggered），通过 runCommand 调用 .kiro/scripts/quality-gate.sh——该脚本会探测项目包管理器（pnpm/yarn/bun/npm）并依次执行构建、类型检查、lint 与测试，工具缺失时优雅跳过。

6.3 会话级的验证兜底

合入 PR 前可调用 #verification-loop 技能（.kiro/skills/verification-loop/SKILL.md）：依次跑构建与类型检查、lint、全量测试、安全扫描、git diff 复核，并循环迭代直到全部通过。当它与 Review Mode 连用，"动态审查判断"与"静态工具验证"互为校验，能显著降低"看着没问题、跑起来崩了"的漏网概率。

七、团队落地：把 review-mode 定制成你自己的评审规范

steering 文件的全部价值在于"可以改"。仓库设计上，.kiro 下的所有文件在安装后都归你所有（安装器采用非破坏性复制，不会覆盖既有文件），因此完全可以：

• 在五类清单中追加团队特有的检查项（例如数据库 RLS 策略、错误边界约定、状态管理选型约束——code-reviewer 代理在其 Project-Specific Guidelines 中明确建议核对 CLAUDE.md 与项目规则里的文件规模上限、emoji 策略、不可变性要求等）；
• 调整严重度判定的量化阈值（如函数行数、覆盖率要求）；
• 把审查中反复发现的模式沉淀进 .kiro/steering/lessons-learned.md，形成团队的持续学习闭环——.kiro/hooks/extract-patterns.kiro.hook 会在代理停止工作时主动建议提炼新模式入档。

若想新增一个手动上下文模式，.kiro/README.md 给出了最小骨架，可照此在 .kiro/steering/ 下扩展：

---
inclusion: manual        # auto | fileMatch | manual
description: 该上下文文件解决什么问题
---

# 你的模式规则

结语

Review Mode 的价值不在于它的 5 步流程与 5 类清单本身有多"新"，而在于它把 AI 代码审查从"随机的、凭感觉的挑毛病"收敛为"有上下文、有顺序、有分级、有输出格式"的工程化动作。对照仓库实现可以看到：#review-mode 负责唤醒审查心智，code-reviewer 等代理负责执行细则与产出格式，security.md/testing.md 等 auto steering 提供常驻基线，code-review-on-write/git-push-review/quality-gate 等钩子把核心关切铺进每一次写盘与推送。四者叠加，才构成一套从差异读取、边界核验到分级放行的完整代码质量保障链路。