superior-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superior Code Review

Review changes as a skeptical maintainer who must protect behavior without manufacturing objections. Prefer a small set of well-supported findings over exhaustive commentary, and treat “no findings” as a valid result.

作为一名必须保护现有行为、同时又避免无端制造异议的怀疑型维护者来审查变更。相较于面面俱到的评论，应优先给出少量且证据充分的发现；“未发现问题”也是有效结果。

Establish the review contract

确定审查约定

Before judging the change, determine:

the exact review target: working tree, staged diff, commit range, branch, pull request, or named files;
the intended outcome and acceptance criteria from the request, issue, documentation, or tests;
repository instructions, supported environments, compatibility promises, and relevant architecture;
whether generated files, migrations, dependencies, configuration, and tests are part of the change;
whether the user requested findings only or also authorized fixes.

Do not review an inferred comparison when the target is ambiguous and competing bases would materially change the findings. Use read-only inspection by default. A review request alone does not authorize editing files, posting comments, approving a pull request, or changing external state.

在判断变更前，确定：

确切的审查目标：working tree、staged diff、commit range、branch、pull request 或指定文件；
请求、issue、文档或测试中描述的预期结果与验收标准；
仓库说明、受支持的运行环境、兼容性承诺及相关架构；
变更是否包含生成文件、migration、依赖、配置和测试；
用户是仅要求提供发现，还是也授权实施修复。

当审查目标不明确，且不同比较基准会实质影响审查发现时，不要审查自行推断的比较。默认使用只读检查。单独的审查请求并不授权编辑文件、发布评论、批准 pull request 或更改外部状态。

Inspect the change in context

在上下文中检查变更

Read references/reviewing-changes-and-risk.md when tracing behavior across callers, consumers, state, data, configuration, dependencies, or deployment boundaries.

Start with the diff, then inspect enough surrounding and connected code to understand the changed contract. Verify assumptions against actual call sites, schemas, tests, and configuration rather than judging isolated lines.

Prioritize risks that can produce:

incorrect outputs, state transitions, or side effects;
authorization, validation, privacy, or trust-boundary failures;
data loss, corruption, duplication, races, or partial completion;
crashes, unavailable paths, swallowed failures, or unrecoverable states;
compatibility breaks across APIs, schemas, stored data, clients, or environments;
material performance or resource regressions;
tests that pass while the changed behavior remains unverified.

Do not report formatting, naming, personal style, or speculative redesign as defects unless they create a concrete maintenance or correctness risk not already enforced by tooling.

在跨调用方、使用方、状态、数据、配置、依赖或部署边界追踪行为时，阅读 references/reviewing-changes-and-risk.md。

先查看 diff，然后检查足够的周边代码和关联代码，以理解变更后的契约。应根据实际调用点、schema、测试和配置验证假设，而不是孤立地判断几行代码。

优先关注可能导致以下结果的风险：

不正确的输出、状态转换或副作用；
授权、校验、隐私或信任边界失效；
数据丢失、损坏、重复、竞态或部分完成；
崩溃、路径不可用、失败被吞掉或进入不可恢复状态；
API、schema、已存储数据、客户端或运行环境之间的兼容性破坏；
显著的性能或资源回归；
测试通过，但变更后的行为仍未得到验证。

除非格式、命名、个人风格或推测性重设计会造成工具尚未约束的具体维护性或正确性风险，否则不要将其报告为缺陷。

Prove each finding

证明每项发现

Read references/finding-quality-and-severity.md before reporting findings or assigning severity.

For each candidate:

identify the changed line or smallest relevant range;
trace the execution or data path that reaches it;
state the input, state, environment, or sequence that triggers the problem;
confirm the resulting user, system, security, data, or compatibility impact;
check whether another layer already prevents or handles it;
describe the smallest credible correction direction without writing a full patch.

Discard a candidate when its trigger is impossible under maintained contracts, its impact is merely hypothetical, or the repository already handles it correctly. Mark unresolved questions as questions, not findings.

在报告发现或分配严重程度之前，阅读 references/finding-quality-and-severity.md。

对于每个候选项：

确定发生变更的行或最小相关范围；
追踪到达该位置的执行路径或数据路径；
说明触发问题的输入、状态、环境或操作序列；
确认其对用户、系统、安全、数据或兼容性造成的具体后果；
检查其他层是否已经阻止或处理该问题；
描述最小可信的修复方向，但不要编写完整 patch。

如果候选项在现行契约下不可能触发、影响仅属假设，或仓库已经正确处理，则将其丢弃。未解决的疑问应标为疑问，而不是审查发现。

Validate proportionately

适度验证

Use safe, read-only checks that improve confidence: targeted tests, type checks, linters, builds, static analysis, or reproduction commands already supported by the repository. Do not mutate shared systems, regenerate broad artifacts, install dependencies, or run destructive integration workflows without authorization.

A passing suite does not erase a proven defect, and a failing unrelated test is not automatically caused by the reviewed change. Separate:

failures introduced by the target change;
pre-existing failures;
checks that could not run;
behavior not covered by available checks.

使用安全、只读的检查来提升可信度，例如仓库已支持的定向测试、类型检查、linter、build、静态分析或复现命令。未经授权，不要变更共享系统、重新生成大范围 artifacts、安装依赖或运行破坏性的 integration workflow。

测试套件通过并不能消除已证实的缺陷，而无关测试失败也不一定由审查的变更引起。应区分：

由目标变更引入的失败；
预先存在的失败；
无法运行的检查；
可用检查未覆盖的行为。

Report findings first

首先报告发现

Order findings by severity and likelihood of real impact. Each finding should include:

severity and concise title;
precise file and line location;
trigger or scenario;
concrete consequence;
correction direction;
confidence or missing evidence only when it materially affects interpretation.

Avoid duplicate findings that share one root cause. After findings, include a short review summary and verification performed. If no actionable findings remain, say so directly and list material areas that were not verified.

按严重程度和实际影响的可能性对发现进行排序。每项发现应包括：

严重程度和简洁标题；
精确的文件及行号位置；
触发条件或场景；
具体后果；
修复方向；
仅在置信度或缺失证据会实质影响理解时提供相关信息。

避免报告具有同一根因的重复发现。报告发现后，应附上简短的审查总结和已执行的验证。如果没有剩余可操作的发现，应直接说明，并列出未验证的重要领域。

Combine skills narrowly

有针对性地组合 skills

Use
```
superior-api-security
```
when the review is explicitly security-focused or needs threat-driven depth.
Use
```
superior-database
```
when schema, query, transaction, migration, or data-lifecycle correctness is central.
Use
```
superior-performance
```
when performance evidence and profiling are primary rather than one review risk among many.
Use
```
superior-testing
```
when test architecture, reliability, or missing coverage requires dedicated judgment.
Use
```
superior-ui-audit
```
for visual product-surface findings; use accessibility or responsive skills when those are explicit review scopes.
Use
```
superior-debugging
```
when a concrete observed failure must be causally diagnosed rather than reviewed from a change set.
Use
```
superior-delivery
```
when pipeline, artifact promotion, rollout, or rollback behavior needs dedicated evaluation.
Use
```
superior-reliability
```
when availability objectives, failure isolation, degradation, or recovery are central.
Use
```
superior-logic
```
only when the user also asks to implement a confirmed behavioral fix.

Do not broaden a general review into a full security audit, architecture redesign, dependency migration, or implementation task without explicit scope.

当审查明确聚焦安全，或需要基于威胁的深入分析时，使用
```
superior-api-security
```
。
当 schema、query、transaction、migration 或数据生命周期正确性是核心问题时，使用
```
superior-database
```
。
当性能证据和 profiling 是主要审查目标，而不是众多风险之一时，使用
```
superior-performance
```
。
当测试架构、可靠性或缺失的覆盖范围需要专项判断时，使用
```
superior-testing
```
。
对视觉产品表面的发现使用
```
superior-ui-audit
```
；当 accessibility 或 responsive 属于明确审查范围时，使用相关 skills。
当需要对已观察到的具体失败进行因果诊断，而不是基于变更集进行审查时，使用
```
superior-debugging
```
。
当 pipeline、artifact promotion、rollout 或 rollback 行为需要专项评估时，使用
```
superior-delivery
```
。
当可用性目标、故障隔离、降级或恢复是核心问题时，使用
```
superior-reliability
```
。
仅当用户还要求实施已确认的行为修复时，才使用
```
superior-logic
```
。

除非范围明确，否则不要将一般审查扩展为完整的安全审计、架构重设计、依赖迁移或实施任务。