deep-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Review

深度审查

Multi-dimensional PR review orchestrator. Replaces ad-hoc "please review this PR" with a structured dispatch of specialized reviewers.

多维度PR审查协调器。将临时的“请审查这个PR”替换为结构化的专业审查人员分派机制。

When to Use

使用场景

User explicitly invokes
```
/deep-review
```
or asks for a "deep review" / "formal review" / "thorough review"
PR is transitioning from Draft to Ready for Review
A high-risk change needs independent verification before merge

Don't use for: quick sanity checks (just do it yourself), typo fixes, or single-line changes.

用户明确调用
```
/deep-review
```
或要求进行“深度审查”/“正式审查”/“全面审查”
PR从草稿状态转为待审查状态
高风险变更在合并前需要独立验证

请勿用于： 快速 sanity 检查（直接自行完成即可）、拼写错误修复或单行变更。

Prerequisites

前置条件

```
gh
```
CLI is authenticated (
```
gh auth status
```
)
Target PR is identified — either the current branch's PR or an explicit PR number
You have
```
git
```
/
```
gh
```
read access to the repo

```
gh
```
CLI已完成认证（执行
```
gh auth status
```
验证）
已确定目标PR —— 要么是当前分支对应的PR，要么是明确指定的PR编号
你拥有该仓库的
```
git
```
/
```
gh
```
读取权限

Steps

步骤

Step 1: Fetch the diff and PR metadata

步骤1：获取差异和PR元数据

bash

gh pr view --json number,title,body,baseRefName,headRefName
gh pr diff

Extract: PR number, title, body, base branch, head branch, full diff.

bash

gh pr view --json number,title,body,baseRefName,headRefName
gh pr diff

提取：PR编号、标题、正文、基准分支、头部分支、完整差异。

Step 2: Classify the change — apply tags (multi-select)

步骤2：对变更进行分类 —— 添加标签（可多选）

Read the diff and assign one or more tags:

logic
— code logic changes (functions, algorithms, control flow, data handling)
ui
— CLI / TUI / web / mobile UI changes (user-facing interaction surfaces)
frontend-perf
— frontend or mobile performance-sensitive changes (rendering, bundle, network, memory)
structure
— new files, module reorganization, dependency graph changes

Also judge: is this trivial (single-line tweak, pure config/doc) or non-trivial (any code logic change)?

读取差异并分配一个或多个标签：

logic
—— 代码逻辑变更（函数、算法、控制流、数据处理）
ui
—— CLI/TUI/网页/移动端UI变更（用户交互界面）
frontend-perf
—— 前端或移动端性能敏感型变更（渲染、包体积、网络、内存）
structure
—— 新增文件、模块重组、依赖关系图变更

同时判断：这是** trivial**（单行调整、纯配置/文档变更）还是** non-trivial**（任何代码逻辑变更）？

Step 3: Dispatch required reviewers (always, in parallel)

步骤3：分派必备审查人员（始终并行执行）

Launch these three as read-only subagents in parallel (single message, multiple Agent tool calls, no isolation needed since read-only):

Reviewer	Focus
Correctness	Does it implement the requirement correctly? Any logic errors?
Consistency	Does it follow existing project patterns, naming, structure?
Documentation sync	Do changes cause README, CLAUDE.md, API docs, etc. to drift? Remove stale/redundant descriptions — no docs is better than wrong docs. Code is documentation; don't add redundant prose describing code behavior.

Each reviewer receives:

PR diff (full)
Relevant project spec docs (if any, e.g.,
```
docs/
```
topic files)
Explicit output format requirement (see "Output format" below)

启动这三个只读子Agent并行执行（单条消息，多次Agent工具调用，无需隔离，因为是只读操作）：

审查人员	关注点
正确性审查员	是否正确实现了需求？是否存在逻辑错误？
一致性审查员	是否遵循现有项目的模式、命名规范和结构？
文档同步审查员	变更是否导致README、CLAUDE.md、API文档等出现偏差？移除过时/冗余的描述 —— 没有文档比错误文档更好。代码即文档；不要添加描述代码行为的冗余文字。

每位审查员会收到：

完整的PR差异
相关的项目规范文档（如有，例如
```
docs/
```
下的主题文件）
明确的输出格式要求（见下文“输出格式”）

Step 4: Dispatch conditional reviewers (by tag)

步骤4：分派条件审查人员（按标签）

Tag	Reviewer	Focus
`logic`	Security	Injection, XSS, auth bypass, secret leakage, unsafe deserialization
`logic`	Edge cases	Exception inputs, concurrency, resource cleanup, error paths
`ui`	UX (consider independent Agent, optionally with `playwright-cli` )	Dead ends, no feedback after action, misclick risk, redundant operations, invisible state — review from a user's perspective
`frontend-perf`	Performance	Rendering (unnecessary re-renders, unvirtualized large lists, animation jank); bundle size (untreeshaken deps, uncompressed assets); network (redundant requests, no caching, waterfall loading); memory (leaks, unreleased listeners/timers). Mobile: startup time, offscreen rendering, main thread blocking
`structure`	Engineering structure	Are new files in correct directories per existing layering/packaging? Circular dependencies? Cross-layer direct calls? Are shared-module changes assessed for blast radius? Reimplementation of existing reusable modules?

Launch these in parallel with the required three (same message).

标签	审查人员	关注点
`logic`	安全审查员	注入攻击、XSS、认证绕过、密钥泄露、不安全反序列化
`logic`	边缘情况审查员	异常输入、并发、资源清理、错误路径
`ui`	UX审查员（可考虑独立Agent，可选搭配 `playwright-cli` ）	死胡同、操作后无反馈、误触风险、冗余操作、不可见状态 —— 从用户视角进行审查
`frontend-perf`	性能审查员	渲染（不必要的重渲染、未虚拟化的大型列表、动画卡顿）；包体积（未摇树优化的依赖、未压缩资源）；网络（冗余请求、无缓存、瀑布式加载）；内存（泄漏、未释放的监听器/定时器）。移动端：启动时间、离屏渲染、主线程阻塞
`structure`	工程结构审查员	新文件是否放置在符合现有分层/打包规则的目录中？是否存在循环依赖？是否存在跨层直接调用？共享模块变更是否评估了影响范围？是否重复实现了现有可复用模块？

与必备的三位审查员并行启动这些审查人员（同一条消息）。

Step 5: Dispatch general reviewer (if non-trivial)

步骤5：分派通用审查人员（若为非微小变更）

For any non-trivial change, additionally dispatch:

Maintainability — naming, structure, over-abstraction vs. under-abstraction, comment quality

对于任何非微小变更，额外分派：

可维护性审查员 —— 命名规范、结构、过度抽象与抽象不足、注释质量

Step 6: Synthesize findings into a punch list

步骤6：将审查结果整合为任务清单

Aggregate all reviewer outputs into a single report:

undefined

将所有审查员的输出汇总为一份报告：

undefined

Deep Review: PR #<n> — <title>

深度审查：PR #<n> — <标题>

Tags: <logic|ui|...> | Reviewers dispatched: <list>

标签: <logic|ui|...> | 分派的审查人员: <列表>

Blocking issues

阻塞性问题

file:line — <one-line finding> (<reviewer>)

<文件:行号> — <单行描述>（<审查人员>）

Non-blocking suggestions

非阻塞性建议

file:line — <one-line finding> (<reviewer>)

<文件:行号> — <单行描述>（<审查人员>）

Architectural observations

架构观察

<observation and recommended tracking action>


**Classification rule**:
- **Blocking** = correctness bug, security vulnerability, breaks existing tests/contracts
- **Non-blocking** = maintainability / style / minor perf
- **Architectural** = decay worth tracking as a separate issue (don't bundle risky, out-of-scope changes into a review-cycle PR)

<观察结果及建议的跟踪措施>


**分类规则**:
- **阻塞性** = 正确性bug、安全漏洞、破坏现有测试/契约
- **非阻塞性** = 可维护性/风格/轻微性能问题
- **架构性** = 值得单独跟踪的架构腐化问题（不要将高风险、超出审查范围的变更纳入当前PR的审查周期）

Output Format (for each dispatched reviewer)

输出格式（针对每位分派的审查员）

Every reviewer subagent must be told how to report back. Do not rely on defaults — subagents will otherwise dump raw context.

Default prompt contract for each reviewer:

Return a summary of at most 300 words followed by a bullet list of findings. Each finding:
<file>:<line> — <one-line description> — [severity: blocking | non-blocking]
. Do not include code excerpts longer than 5 lines. Do not restate the diff. If no issues found, return exactly:
"No findings."

Adjust the word budget or format per reviewer as needed (e.g., Security may justify a longer explanation for a single high-severity finding).

必须告知每位子审查员如何反馈结果。不要依赖默认设置 —— 否则子Agent会输出原始上下文信息。

每位审查员的默认提示约定：

返回最多300字的摘要，后跟发现问题的项目符号列表。每个问题格式为：
<文件>:<行号> — <单行描述> — [严重程度: blocking | non-blocking]
。不要包含超过5行的代码片段。不要重述差异内容。如果未发现问题，请返回：
"No findings."

可根据审查员的需求调整字数限制或格式（例如，安全审查员针对单个高严重度问题可适当延长解释内容）。

Runtime: subagent vs independent Agent

运行时：子Agent vs 独立Agent

Default: in-conversation subagent (read-only, parallel-safe)
Use independent Agent when:
- UX review benefits from zero-context fresh eyes
- Cross-model blind spot coverage is valuable (dispatch a different-family reviewer — e.g., Codex reviewing Claude-written code, or Claude reviewing Codex-written code — so the reviewer doesn't share the writer's blind spots)
- Architectural trade-offs require the strongest reasoning model the runtime offers at
```
xhigh
```
  effort
Never required: committing
```
.claude/agents/
```
files. Subagent configuration is runtime, per-dispatch.

默认方式: 对话内子Agent（只读、并行安全）
使用独立Agent的场景:
- UX审查需要无上下文的全新视角
- 需要跨模型盲区覆盖（分派不同类型的审查员 —— 例如，用Codex审查Claude编写的代码，或用Claude审查Codex编写的代码 —— 这样审查员不会与开发者有相同的盲区）
- 架构权衡需要运行时提供的最强推理模型（
```
xhigh
```
  算力级别）
无需执行: 提交
```
.claude/agents/
```
文件。子Agent配置为运行时的按需分派设置。

Follow-up

后续操作

After synthesis:

Small fixes in current PR — architectural decay caught by review can be fixed in this PR if it doesn't affect test results
High-risk issues — remind the human partner to create an issue for tracking; don't bundle risky changes into a review-cycle PR
Document new patterns — if the review surfaces a recurring anti-pattern worth codifying, note it for the next workflow iteration

整合结果后：

当前PR中的小修复 —— 审查发现的架构腐化问题如果不影响测试结果，可在当前PR中修复
高风险问题 —— 提醒人类合作者创建跟踪议题；不要将高风险变更纳入当前PR的审查周期
记录新模式 —— 如果审查发现了需要规范化的重复反模式，将其记录下来用于下一次工作流迭代

Anti-patterns (don't do this)

反模式（请勿执行）

❌ Dispatching subagents without specifying output format → context flood
❌ Serializing reviewers that are independent → wastes time
❌ Parallel subagents editing the same file → use
```
isolation: "worktree"
```
or assign to one reviewer
❌ Asking subagents to coordinate with each other mid-review → no current CLI runtime (Claude Code, Codex CLI, etc.) has an agent-to-agent channel. If one reviewer's finding affects another's scope, serialize (A → main Agent → B) instead
❌ Reviewing Draft PRs formally — draft is for informal early feedback; wait for Ready

❌ 未指定输出格式就分派子Agent → 上下文泛滥
❌ 串行执行独立的审查员 → 浪费时间
❌ 并行子Agent编辑同一文件 → 使用
```
isolation: "worktree"
```
或分配给单个审查员
❌ 要求子Agent在审查过程中相互协调 → 当前CLI运行时（Claude Code、Codex CLI等）没有Agent间通信渠道。如果一位审查员的发现影响另一位的审查范围，请改为串行执行（A → 主Agent → B）
❌ 对草稿PR进行正式审查 —— 草稿用于非正式早期反馈；等待PR转为待审查状态

Example invocation

调用示例

User: /deep-review
Assistant:
  1. gh pr view + gh pr diff
  2. Tags: logic, structure
  3. Dispatches 6 reviewers in parallel:
     - Required: correctness, consistency, docs-sync
     - Conditional (logic): security, edge-cases
     - Conditional (structure): engineering-structure
     - Non-trivial: maintainability
  4. Each reviewer returns ≤300-word summary + findings
  5. Synthesizes punch list, categorizes blocking vs non-blocking
  6. Reports to user

用户: /deep-review
助手:
  1. 执行 gh pr view + gh pr diff
  2. 标签: logic, structure
  3. 并行分派6位审查员:
     - 必备：正确性、一致性、文档同步
     - 条件分派（logic）：安全、边缘情况
     - 条件分派（structure）：工程结构
     - 非微小变更：可维护性
  4. 每位审查员返回≤300字的摘要 + 问题列表
  5. 整合为任务清单，分类阻塞性与非阻塞性问题
  6. 向用户汇报结果