deep-review

深度审查

基于独立审查者开展多维度代码审查。通过并行覆盖多个维度来拓展审查广度；通过对抗式验证和全局重复项合并，在问题进入报告前提升审查精度。

核心原则

以下每项设计选择都服务于其中一条原则。不确定如何执行某个步骤时，请回到这里。

1. 防止幻觉 — 审查者需要查看周边上下文，而不只是差异片段。深度模式通过独立 Agent 验证候选问题，由其返回 confirmed / false_positive / need_more_context。轻量模式采用下文所述的有限后续流程；不会为每个问题额外增加一套独立验证流程。
2. 防止自我认可 — 刚写完代码的 Agent 就像在给自己的作业打分，往往会放过问题。两种模式都使用站在第三方立场的独立审查者。轻量模式：使用一名非主 Agent 的审查者。深度模式：根据环境手册使用独立子 Agent。绝不能悄悄降级为“主 Agent 自己审查差异”。
3. 规则优于模型 — 审查质量来自细粒度、可执行的维度规则，而不是更聪明的模型。子 Agent 使用均衡型／快速型模型等级运行；每个维度文件都会明确告知它们如何检查、哪些情况算作问题、哪些不算。
4. 根据代码库和生命周期进行校准 — 按照代码库现有的标准审查差异，而非理想化标准。如果某种模式在现有代码中已广泛存在，且此次差异没有让情况变得更糟，就不算问题。对于明确属于临时用途的代码（限时活动、实验、一次性脚本），应根据其生命周期来判断：硬编码和降低可扩展性的捷径是为了快速交付而做出的预期取舍；“到期后删除代码”也是有效方案——不要要求为注定要删除的代码提供可配置性。（安全问题不受任何校准影响，详见维度文件。）
5. 速度也是一项特性 — 审查者并行执行一轮；按维度流水线式验证（绝不设置全局屏障）；提前剔除不相关的维度。

两种入口模式

模式	触发条件	执行内容
轻量（默认）	任何常规审查请求：“审查这个 PR”、非正式地说“看看这个改动有没有问题”、粘贴差异以供审查——但不包括仅要求解释某项改动的问题	使用快速检查清单，由一名独立审查者检查每个适用维度。如果可用，优先使用不同厂商的工具链；否则使用同一工具链下的一个子 Agent。最多进行一轮后续验证，具体见下文。
深度	仅限明确指定：/deep-review、“执行深度审查”、“进行完整的多 Agent 审查”	完整编排：维度审查 Agent → 流水线式验证 → 全局合并 → 结构化报告 → 交互式修复流程。

不要自动将轻量模式升级为深度模式。不要因为随口说一句“看看这个改动”，就运行深度模式——这属于轻量模式。

何时建议使用 Deep

Deep 仍需用户同意，但当变更风险较高时，Agent 必须征求用户同意。在轻量审查前或创建 PR 前，如果差异符合以下任一情况，请建议运行 Deep（用一句话指出触发信号）：

• 涉及资金或权益：收费、账单、订阅、额度、支付 Webhook；
• 涉及身份验证、权限或用户隔离；
• 新增或修改数据库查询、架构、迁移或回填，或删除持久化数据；
• 修改跨软件包、代码仓库或已发布客户端共享的契约；
• 规模大到一位审查者无法掌握（约 1,000 行以上非测试变更）。

例如，添加支付路径模型查询且仅使用 Mock 测试的 PR 符合条件。只有在用户同意后才运行 Deep；否则继续使用轻量模式。以下 Deep 模式预算仍然适用。

Deep 模式预算

在同一个逻辑需求（同一需求、PR 或分支）内，默认最多运行一次 Deep 模式。修复后的后续审查、CI 工作、变基、清理、上下文压缩或恢复的会话均使用轻量模式，即使再次审查整个差异也一样。这些事件不会重置预算，而一次 Deep 运行中的审查／验证／整合阶段都计为同一次运行。

只有在用户明确要求再次进行 Deep 审查，或真正开始新的逻辑需求时，才再次运行 Deep。诸如“再审查一下”“复核一下”或“再看看”这样的随口跟进属于轻量请求，并不代表用户默认授权再次运行 Deep。

维度

规则统一存放在 references/dimensions/ 中，每个维度对应一个文件。两种模式使用相同的文件。轻量审查者会阅读完整的 Quick checklist 部分，包括嵌套的示例小节；Deep 模式 Agent 会阅读完整的维度文件，以及适用于所涉及表面的规则来源和路由引用。

维度	id 前缀	涵盖内容	已验证？
ai-coding-bad-habits	ai	通用代码中的狭窄特殊情况、不完整的重构、冗余的类型保护/别名、注释复述代码，以及忽视先例的实现	是
code-style	style	命名、可读性、死代码、注释、i18n 硬编码、UI 库和样式规范	是
logic	logic	逻辑正确性：边界情况、null、竞态、错误处理、状态机、偏离需求、测试覆盖	是
business-logic	design	设计判断：误用框架、违反最佳实践、方案与问题不匹配、自行引入的复杂性	是
new-feature	feature	新能力设计：领域词汇和结构、持久化数据模型与迁移证据、产品分析和运维可观测性	是
reuse-architecture	reuse	重复实现、未采用现有模式、可扩展性、架构边界	是
performance	perf	N+1、阻塞调用、资源泄漏、渲染路径浪费、数据库迁移锁定和幂等性	是
release-risk	risk	发布/不发布门槛：不可逆的持久化状态（包括无模式数据形态漂移）、开发周期中的迁移残留、部署时正在进行的工作与配置、不可逆的出站影响、提示词/工具描述行为变化、共享界面和高频 UI 的影响范围、PR 纯净度	是 + 检查
security	sec	注入、绕过身份验证、泄露机密/PII、业务领域机密性	是
compatibility	compat	浅色/深色主题、桌面应用 / Web（桌面端、移动端）/ RN、已发布客户端的 API 兼容性、客户端与服务端 Agent 运行时（网关开启/关闭）、Vercel 与 Docker 部署、配对的路由器配置	是
ux	ux	空状态/加载状态/错误状态、异步反馈、确认流程、遵循设计价值	是
observability	obs	调试：无法解释的修复、未注释的变通方案、静默捕获异常、缺少日志；产品：对符合条件的新能力进行分析；性能：对高频/高流量/轮询路径进行监控	是
workflow	flow	问题跟踪状态、PR 描述的时效性、未记录的关键决策、CI / 预览构建状态	否（客观状态）
skill-freshness	skill	因此差异而失效的 Agent 技能、值得提炼成新技能的知识	否（建议项）
Verified? no 表示该维度的发现属于客观状态检查或提醒——它们会跳过验证阶段，直接进入报告。yes + checks 表示该维度的发现会照常验证，但还会生成第二项未经验证的输出——release_checks，即有关生产环境状态的部署前确认事项，仓库无法回答这些问题（参见该维度文件）。

剪枝表（深度模式）

启动前，主 Agent 会剪去不适用于此次差异的维度。在报告标题中列出被剪去的维度及其一句话原因。如有疑问，请运行该维度。

维度	跳过条件
ai-coding-bad-habits, code-style, logic, business-logic, reuse-architecture	从不跳过（仅当差异只涉及文档/锁文件时跳过）
new-feature	差异未引入新的产品、运算符或平台功能
performance	未修改服务器/数据库/循环/渲染路径代码（例如文档、文案、纯类型变更）
release-risk	不涉及数据库架构/迁移、无模式的持久化载荷、队列/定时任务/配置/出站依赖、提示词或工具描述文本、共享组件或软件包公共 API、高频用户界面，且差异只有一个明显目的
security	仅涉及锁文件/生成文件的差异——文档和文案仍会运行此检查（文本可能导致信息泄露：密钥、内部 URL、商业细节）
compatibility	差异未涉及 UI 主题/路由、API 契约、部署配置或运行时分支代码
ux	未更改面向用户的界面（组件、样式、文案、交互流程）
observability	未涉及错误处理、异步流程、服务器代码、新的面向用户功能或性能敏感路径
workflow	轻量：没有可用的 PR/issue/CI 上下文；深度：从不（低成本外部状态检查）
skill-freshness	轻量：差异既未更改 Agent 指令，也未更改现有技能涵盖的行为/约定；深度：从不（成本低）
“仅文档”仅指面向人的说明文字。 为 Agent 提供可执行指令的文件——.agents/skills/**、AGENTS.md / CLAUDE.md、提示词模板、编排手册——在剪枝时都视为代码：其中的“说明文字”承载着控制流、契约和规则，而这些内容之间的矛盾正是 logic / business-logic / reuse-architecture 要捕捉的问题。涉及这些文件的差异绝不属于仅文档。

轻量模式使用同一张表来决定传给审查者的 Quick 检查清单。

扩展包

包装仓库（例如将本仓库作为子模块纳入的私有部署）无需分叉此技能，即可扩展规则集：活动技能根目录中任何名称匹配 deep-review-* 的同级技能目录（例如 .agents/skills/deep-review-cloud/）都是扩展包。

• 扩展包包含格式相同的 dimensions/*.md 文件；以内置维度命名的文件会对其进行扩展（两者都加载），新名称则会新增一个维度。
• 如果扩展文件声明了 extends: <name>，但不存在相应的内置维度（通常是因为包装仓库固定使用了较旧的子模块提交），则该文件会作为独立维度使用。因此，此类文件必须包含自己的 id_prefix / verify / skip_when，以确保无论哪种情况都可使用；如果存在对应的内置维度，则以其 frontmatter 为准。
• 两种模式都必须在启动时检查扩展包，并加载所有现有内容。没有扩展包属于正常情况——此技能本身完备。
• 扩展包可能包含不应放入此开源仓库的规则；切勿将其内容复制到此目录下的文件中。

Light mode procedure

如果用户消息已经是一个实例化的轻量审查提示词，你就是审查者——请遵循该提示词，不要重新进入此流程。

1. 严格按照深度模式步骤 0 确定审查范围（参阅环境手册中的范围规则——从一个未落后于分叉点的基准进行三点差异比较，并纳入子模块差异），但如果上下文已说明变更内容，则跳过额外的背景搜寻。
2. 应用裁剪表；收集保留下来的维度文件及其扩展包对应文件。不要自行阅读检查清单。
3. 使用保留下来的 {dimensions}、{dimension_files}、{scope_summary} 和 {changes} 填充 references/light-review-prompt.md。恰好派发一名独立审查者，并按以下顺序尝试：
   1. 如果本次会话可以向不同厂商的编码 Agent 工具链（而非同一工具链的子 Agent）派发一项自包含任务，请使用该方式。如果派发器提供了专门用于独立代码审查的预设，优先选择该预设。
   2. 否则，生成一个同一工具链的子 Agent。如果生成 API 允许，请禁用上下文继承。
   3. 如果所选方式失败，则尝试下一种方式。如果都不可用，请停止并告知用户原因。不要自行审查差异。
4. 根据证据评估审查结果。在获准的实现任务中，修复已接受、安全且范围内的问题，并运行适当的检查。若要驳回或降低某项结果的级别，请将反证提交给下方的独立验证轮次，而不是自行否定审查者的结论。独立审查请求并未授权修改。
5. 每项审查请求最多进行 一轮后续验证，无论涉及何种维度，都应同时涵盖有争议的结果和修复。将原始结果和反证附加到轻量审查提示词中，并提供当前差异；请独立审查者检查行为变更及可能的回归。如果没有具体证据，不得更正或撤回审查结果，并说明原因。如果验证仍然失败或仍有结果未解决，请如实报告状态，不要再自动进行审查。必要且获准的修复可以继续，但不得声称之后又进行了独立审查。用户明确提出的新审查请求优先于此自动轮次限制。
6. 按照环境中的常规审查格式（而非深度报告模板）报告最终结果和验证状态。将部署前确认事项与缺陷分开列出。

Deep mode procedure

进入此流程前，请先检查上文的 Deep 模式预算。如果已运行过 Deep 模式，且用户未明确要求再次进行 Deep 审查，则使用 Light 流程。

选择适用于当前环境的手册，并从头到尾遵循：

• Claude Code → references/claude-code/main.md
• Codex → references/codex/main.md

如果环境不在列表中，请告知用户当前尚不支持该环境的深度模式，并提供轻量模式作为替代。不要擅自采用其他环境的机制，也不要在主 Agent 中模拟深度审查，或将其压缩为一个审查者（参阅原则 2）。

Keeping this skill sharp

skill-freshness 维度和子 Agent 返回架构中的 workflow_feedback 通道用于将观察反馈到这些文件中。如果审查发现规则漏洞、规则过时或团队反复出现的偏好，请在同一个 PR 或后续 PR 中更新相关维度文件——这样才能保持校准与时俱进。