code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Review

代码审查

Mission

任务

Produce the deepest review that is practical for the requested scope. Findings and coverage evidence are the primary output. Praise, style preferences, and broad refactor suggestions are secondary.

The coordinating agent owns scope, final judgment, de-duplication, severity, and the persisted report. Subagents provide bounded analysis; never copy their conclusions into the report without independent synthesis.

针对请求的范围生成尽可能深入的审查结果。审查发现和覆盖证据是主要输出内容。表扬、风格偏好和宽泛的重构建议为次要内容。

协调Agent负责范围界定、最终判断、去重、严重程度划分以及报告留存。子Agent提供有限范围的分析；未经独立整合，不得将其结论直接复制到报告中。

Required Resources

必备资源

Read references/subagent-orchestration.md before delegating review work.
Write the report from references/report-template.md.

Validate generation

with

python3 scripts/validate_review_report.py <report-path>

. Validate generation

with the additional

--parent-report <generation-0-report> --parent-resolution <resolution-report>

arguments.

在委派审查工作前，阅读references/subagent-orchestration.md。
基于references/report-template.md撰写报告。

使用

python3 scripts/validate_review_report.py <report-path>

验证第0代报告。验证第1代报告时，需额外添加

--parent-report <generation-0-report> --parent-resolution <resolution-report>

参数。

Hard Gates

硬性规则

Before substantive review, launch exactly one read-only orchestration-assessment subagent.
Before launching that assessor, inspect only enough Git and request metadata to identify the scope, baseline, changed-file inventory, diff size, and obvious constraints. Do not form findings first.
Let the assessor decide whether specialist subagents add material value. Do not equate depth with agent count.
If the environment has no subagent primitive, record
```
Subagent unavailable
```
and execute the same assessment protocol in the coordinator. Never claim a subagent ran when it did not.
Keep every review subagent read-only. Do not edit files, stage, commit, push, reset, checkout, rebase, or mutate Git state.
Do not make code changes during this skill unless the user explicitly changes the task from review to implementation.
Put every report in a review chain. Use generation
```
0
```
for the frozen initial scope and generation
```
1
```
only for the implementation delta plus affected execution chains after a
```
receiving-code-review
```
resolution.
Treat generation
```
1
```
as terminal: write the report, return remaining findings to the user or product owner, and do not automatically invoke
```
receiving-code-review
```
. Any later work requires an explicit user request and a new generation
```
0
```
chain.
Do not classify a disputed product choice as
```
Blocker
```
,
```
Major
```
, or
```
Minor
```
without an authoritative expected-behavior basis. Use
```
Question
```
when product intent is unconfirmed.

在开展实质性审查前，必须启动一个只读的编排评估子Agent。
在启动该评估Agent前，仅需检查足够的Git和请求元数据，以确定范围、基线、变更文件清单、差异大小和明显约束条件。不得先形成审查发现。
由评估Agent决定专业子Agent是否能带来实质性价值。不得将审查深度等同于Agent数量。
如果环境中没有子Agent基础组件，记录
```
Subagent unavailable
```
并在协调Agent中执行相同的评估流程。不得虚假声称已运行子Agent。
所有审查子Agent保持只读状态。不得编辑文件、暂存、提交、推送、重置、检出、变基或修改Git状态。
除非用户明确将任务从审查改为实现，否则在此技能执行过程中不得修改代码。
将每份报告纳入审查链。第0代用于固定初始范围，第1代仅用于实现增量以及
```
receiving-code-review
```
决议后受影响的执行链。
第1代报告为终端报告：撰写完成后，将剩余发现反馈给用户或产品负责人，不得自动调用
```
receiving-code-review
```
。后续任何工作都需要用户明确请求，并启动新的第0代审查链。
若无权威预期行为依据，不得将有争议的产品选择归类为
```
Blocker
```
、
```
Major
```
或
```
Minor
```
。当产品意图未确认时，使用
```
Question
```
标记。

Scope and Identity

范围与标识

Resolve the requested scope: working tree, staged diff, commit range, branch diff, pull request, file set, or pasted code.
Choose the narrowest reasonable scope when none is explicit. Prefer staged changes when present; otherwise compare the working tree with
```
HEAD
```
.
Record the baseline and target precisely. Use commit SHAs when available.
Create a review chain ID and record generation, trigger, parent resolution ID/path, and scope mode. Generation
```
1
```
must read the complete parent resolution before reviewing.
Compute a scope fingerprint when practical from the baseline, target, changed paths, and normalized diff hash. Record why a fingerprint is unavailable.
Read requirements, issue text, PR description, design notes, migrations, relevant contracts, and settled parent-resolution decisions before judging intent.
Freeze generation
```
0
```
scope. For generation
```
1
```
, review the implementation delta and only the callers, callees, contracts, and execution chains it can affect; do not reopen the full original discovery frontier.
Do not silently widen scope. Mark unrelated context as supporting evidence or a follow-up rather than a finding in the current chain.

明确请求的范围：工作树、暂存差异、提交范围、分支差异、Pull Request、文件集或粘贴的代码。
若未明确指定范围，选择最窄的合理范围。若存在暂存变更，优先选择该范围；否则将工作树与
```
HEAD
```
进行对比。
精确记录基线和目标。若有可用的提交SHA值，优先使用。
创建审查链ID，并记录代次、触发条件、父决议ID/路径和范围模式。第1代审查必须先完整读取父决议内容，再开展审查。
若可行，根据基线、目标、变更路径和标准化差异哈希值计算范围指纹。记录无法生成指纹的原因。
在判断意图前，阅读需求、问题文本、PR描述、设计说明、迁移文档、相关合同以及已确定的父决议。
固定第0代审查范围。对于第1代，仅审查实现增量及其可能影响的调用方、被调用方、合同和执行链；不得重新开启完整的原始发现范围。
不得擅自扩大范围。将无关上下文标记为支持证据或后续跟进项，而非当前审查链中的发现。

Orchestration

编排流程

Give the assessment subagent the scope identity, diff inventory, change statistics, touched subsystems, known requirements, and environment limitations.
Require a structured decision:
```
Single reviewer
```
or
```
Parallel specialists
```
, with rationale, risk dimensions, proposed partitions, overlap plan, and verification needs.
Follow the decision unless concrete new evidence invalidates it. Record any override and reason.
For parallel review, assign bounded, non-identical ownership. Typical angles include:
- correctness, state, data flow, and API contracts
- security, privacy, auth, permissions, and trust boundaries
- tests, regressions, error paths, concurrency, and reliability
- migrations, persistence, compatibility, integrations, performance, and operations
- framework- or domain-specific semantics
Require each specialist to return candidate findings, covered areas, dismissed candidates, uncertainty, and evidence pointers.
Re-read the relevant code and evidence for every candidate that could enter the final report. Resolve conflicts explicitly and assign final
```
F#
```
,
```
T#
```
, and
```
A#
```
IDs only in the coordinator.

向评估子Agent提供范围标识、差异清单、变更统计数据、涉及的子系统、已知需求和环境限制。
要求其给出结构化决策：
```
Single reviewer
```
（单人审查）或
```
Parallel specialists
```
（并行专业审查），并提供理由、风险维度、建议划分方式、重叠处理方案和验证需求。
遵循该决策，除非有具体的新证据证明其无效。记录任何覆改操作及原因。
若采用并行审查，分配有界且不重复的职责范围。典型的审查角度包括：
- 正确性、状态、数据流和API合同
- 安全、隐私、认证、权限和信任边界
- 测试、回归、错误路径、并发和可靠性
- 迁移、持久化、兼容性、集成、性能和运维
- 框架或领域特定语义
要求每位专业审查人员返回候选发现、覆盖领域、已排除的候选项、不确定性和证据指向。
对于每个可能纳入最终报告的候选发现，重新阅读相关代码和证据。明确解决冲突，仅在协调Agent中分配最终的
```
F#
```
、
```
T#
```
和
```
A#
```
标识。

Deep Review Contract

深度审查约定

Review beyond changed lines whenever risk can propagate. Trace far enough to evaluate:

callers, callees, shared utilities, adapters, and alternate entry points
input validation, authorization, trust boundaries, secrets, privacy, and unsafe external effects
state transitions, persistence, migrations, serialization, compatibility, rollback, and data loss
retries, idempotency, ordering, caching, concurrency, races, timeouts, partial failure, and cleanup
public API, CLI, UI, generated output, configuration, dependency, and deployment contracts
positive, negative, boundary, regression, integration, and migration test coverage
runtime behavior through focused, non-destructive commands when it materially changes confidence
requirements and intentional behavior changes so intended changes are not misreported as defects

Establish an expected-behavior basis before accepting a finding:

Prefer explicit current user or product-owner decisions and acceptance criteria.
Then use public contracts, approved design or migration decisions, and security, privacy, compliance, or data-integrity invariants.
Treat tests, current code, and history as behavioral evidence, not product authority by themselves.
When the disagreement is a product choice and no authoritative basis is available, emit an approval-affecting
```
Question
```
with a settlement criterion instead of a defect.
In generation
```
1
```
, inherit
```
Intentional
```
,
```
Disproved
```
,
```
Stale
```
, and
```
Duplicate
```
decisions from the parent resolution. Reopen the same semantic issue only when relevant code, the governing contract, or material evidence changed. Record
```
kind:<code|contract|evidence>; ref:<concrete source>; change:<concrete delta>
```
; placeholder references or changes such as
```
None
```
,
```
unknown
```
, or template text do not authorize reopening.

Use search, history, blame, runtime checks, or targeted tests only when they strengthen evidence. Passing lint, typecheck, or unrelated tests is hygiene evidence, not proof of behavioral safety.

Stop only when every changed review-relevant or unknown-impact area is accounted for, meaningful candidates have been adjudicated, and remaining blind spots are explicit.

只要风险可能传播，审查范围需超出变更代码行。追踪足够远的范围以评估：

调用方、被调用方、共享工具、适配器和备用入口点
输入验证、授权、信任边界、密钥、隐私和不安全的外部影响
状态转换、持久化、迁移、序列化、兼容性、回滚和数据丢失
重试、幂等性、排序、缓存、并发、竞争条件、超时、部分故障和清理
公共API、CLI、UI、生成输出、配置、依赖和部署合同
正向、负向、边界、回归、集成和迁移测试覆盖
当能显著提升信心时，通过聚焦的非破坏性命令验证运行时行为
需求和预期行为变更，避免将预期变更误报为缺陷

在确认审查发现前，需确立预期行为依据：

优先采用当前用户或产品负责人的明确决策和验收标准。
其次使用公开合同、已批准的设计或迁移决策，以及安全、隐私、合规或数据完整性不变量。
将测试、当前代码和历史记录视为行为证据，而非产品权威依据本身。
当分歧属于产品选择且无权威依据时，发布影响审批的
```
Question
```
并附带解决标准，而非标记为缺陷。
在第1代审查中，继承父决议中的
```
Intentional
```
、
```
Disproved
```
、
```
Stale
```
和
```
Duplicate
```
判定。仅当相关代码、管辖合同或关键证据发生变更时，才重新开启同一语义问题。记录
```
kind:<code|contract|evidence>; ref:<concrete source>; change:<concrete delta>
```
；
```
None
```
、
```
unknown
```
或模板文本等占位符引用或变更不得作为重新开启的依据。

仅当能强化证据时，才使用搜索、历史记录、blame、运行时检查或针对性测试。通过lint、类型检查或无关测试属于基础验证证据，而非行为安全性的证明。

仅当所有与审查相关的变更区域或未知影响区域都已覆盖、有意义的候选项已裁决、剩余盲区已明确标记时，才停止审查。

Completeness Contract

完整性约定

Enumerate every distinct finding reasonably discoverable within the reviewed scope, not only the top risks.
Maintain a
```
Review Coverage Ledger
```
with stable
```
A#
```
area IDs. Map every changed review-relevant or unknown-impact area to:
- ```
Finding F#
```
- ```
Reviewed - no issue found
```
- ```
Not review-relevant
```
- ```
Not covered
```
Give every standalone test gap a stable
```
T#
```
ID and severity.
Give every
```
F#
```
and
```
T#
```
a canonical semantic issue key. Use
```
behavior; entry=<semantic entry>; contract=<stable expectation>; effect=<terminal failure>
```
for findings and
```
test-gap; entry=<semantic entry>; contract=<stable expectation>; gap=<missing coverage>
```
for standalone test gaps. Exclude line numbers, report-local IDs, generation, and current implementation symbols. Compute its fingerprint as
```
ifp-sha256:<sha256 of the exact UTF-8 issue key>
```
so the same claim can be recognized across generations.
Record meaningful dismissed or merged candidates in
```
Subagent Candidate Adjudication
```
or the evidence appendix.
Mark the report
```
Incomplete
```
and identify exact uncovered surfaces when context, credentials, runtime, diff size, or other limits prevent complete coverage.
Never present a partial review as complete.

列举在审查范围内可合理发现的每一个独特发现，而非仅列出最高风险项。
维护带有稳定
```
A#
```
区域标识的
```
Review Coverage Ledger
```
（审查覆盖台账）。将每一个与审查相关的变更区域或未知影响区域映射至：
- ```
Finding F#
```
  （审查发现）
- ```
Reviewed - no issue found
```
  （已审查 - 未发现问题）
- ```
Not review-relevant
```
  （与审查无关）
- ```
Not covered
```
  （未覆盖）
为每一个独立的测试缺口分配稳定的
```
T#
```
标识和严重程度。
为每一个
```
F#
```
和
```
T#
```
分配规范的语义问题键。对于审查发现，使用格式
```
behavior; entry=<semantic entry>; contract=<stable expectation>; effect=<terminal failure>
```
；对于独立测试缺口，使用
```
test-gap; entry=<semantic entry>; contract=<stable expectation>; gap=<missing coverage>
```
。排除行号、报告本地标识、代次和当前实现符号。计算其指纹为
```
ifp-sha256:<sha256 of the exact UTF-8 issue key>
```
，以便在不同代次中识别同一问题。
在
```
Subagent Candidate Adjudication
```
（子Agent候选项裁决）或证据附录中记录有意义的已排除或合并候选项。
当上下文、凭据、运行时、差异大小或其他限制导致无法完成全覆盖时，将报告标记为
```
Incomplete
```
（不完整）并明确指出未覆盖的范围。
绝不能将部分审查伪装成完整审查。

Findings and Evidence

审查发现与证据

Count one finding per distinct failure mode, affected contract, security boundary, data risk, or approval decision. Merge repeated manifestations of the same defect; split materially different impacts.

Prioritize:

crashes, incorrect results, stale or lost data, availability failures, and broken edge cases
user-visible, API, CLI, persistence, auth, permission, retry, ordering, caching, and integration regressions
injection, unsafe deserialization, auth bypass, secret exposure, SSRF, XSS, CSRF, overbroad access, and unsafe filesystem or dependency use
missing tests for risky changed behavior, especially fixes, permissions, migrations, concurrency, and failures
maintainability only when it creates a concrete review risk

For every accepted finding:

tie the claim to a location, behavior path, output, missing test, or coverage gap
separate verified facts from inference
state assumptions and reduce confidence when proof is incomplete
include exactly one or two primary code links in
```
Look here first
```
record which reviewer proposed it and how the coordinator verified it
record the structured expected-behavior basis, canonical issue key, and verified semantic issue fingerprint

Do not invent defects. A clean result still requires a full coverage ledger, strongest blind spot, and verification record.

针对每一种独特的故障模式、受影响的合同、安全边界、数据风险或审批决策记录一个审查发现。合并同一缺陷的重复表现形式；拆分影响显著不同的问题。

优先关注：

崩溃、错误结果、数据过期或丢失、可用性故障和边缘用例失效
用户可见的回归问题、API、CLI、持久化、认证、权限、重试、排序、缓存和集成回归
注入攻击、不安全反序列化、认证绕过、密钥泄露、SSRF、XSS、CSRF、过度权限以及不安全的文件系统或依赖使用
针对高风险变更行为的测试缺失，尤其是修复、权限、迁移、并发和故障场景
仅当可带来具体审查风险时，才关注可维护性问题

对于每一个已确认的审查发现：

将声明与代码位置、行为路径、输出、测试缺失或覆盖缺口关联
区分已验证事实与推断内容
当证据不完整时，说明假设并降低置信度
在
```
Look here first
```
（优先查看此处）中包含一到两个主要代码链接
记录提出该发现的审查人员以及协调Agent的验证方式
记录结构化的预期行为依据、规范问题键和已验证的语义问题指纹

不得虚构缺陷。即使审查结果无问题，仍需提供完整的覆盖台账、最大盲区记录和验证记录。

Severity and Recommendation

严重程度与建议

Use

Blocker

Major

Minor

, and

Question

as defined in the report template.

Map unresolved findings and standalone test gaps to the recommendation in this order:

Any
```
Blocker
```
->
```
Block
```
.
Otherwise any
```
Major
```
->
```
Changes requested
```
.
Otherwise any approval-affecting
```
Question
```
->
```
Discuss
```
.
Otherwise any review-relevant or unknown-impact
```
Not covered
```
area ->
```
Discuss
```
.
Otherwise any
```
Minor
```
->
```
Pass with caveat
```
.
Otherwise ->
```
Pass
```
.

Downgrade an unproven suspected blocker rather than retaining a hand-wavy

Blocker

. Do not use

Question

for curiosity that cannot affect approval.

使用报告模板中定义的

Blocker

、

Major

、

Minor

和

Question

级别。

按照以下顺序将未解决的审查发现和独立测试缺口映射至建议：

存在任何
```
Blocker
```
->
```
Block
```
（阻止合并）
否则存在任何
```
Major
```
->
```
Changes requested
```
（需要变更）
否则存在任何影响审批的
```
Question
```
->
```
Discuss
```
（需要讨论）
否则存在任何与审查相关或未知影响的
```
Not covered
```
区域 ->
```
Discuss
```
（需要讨论）
否则存在任何
```
Minor
```
->
```
Pass with caveat
```
（附带条件通过）
否则 ->
```
Pass
```
（通过）

对于未证实的疑似Blocker，应降低其级别，而非保留模糊的

Blocker

标记。不得将不影响审批的好奇心问题标记为

Question

。

Persistence and Handoff

留存与交接

Always write a fresh Markdown report using the canonical
```
code-review
```
report contract.
Generate a unique report ID and filename. Follow an existing repository report convention; otherwise use
```
tmp/reviews/YYYY-MM-DD-code-review-report-<random-id>.md
```
.
Never overwrite an existing report.
Persist scope identity, scope fingerprint, orchestration decision, specialist assignments, candidate adjudication, findings, test gaps, coverage, evidence, and a
```
Receiving Handoff
```
section.
Persist review-chain identity, generation, trigger, parent review and resolution, semantic issue keys and fingerprints, expected-behavior bases, and inherited-settlement reconciliation.
Treat the completed review report as a fixed input artifact. Do not rewrite it during receiving or implementation; record later dispositions and code changes in a separate
```
receiving-code-review
```
resolution report linked by Report ID.
A generation
```
0
```
report may be handed to
```
receiving-code-review
```
. A generation
```
1
```
report must use a terminal handoff and must not be consumed automatically.
Partition every non-Question finding and standalone test gap exactly once into actionable or deferred handoff IDs. List every
```
Question
```
and
```
Not covered
```
area in its matching open-ID field.
Run the validator and fix every error before claiming the report is complete.

始终使用规范的
```
code-review
```
报告约定撰写新的Markdown报告。
生成唯一的报告ID和文件名。遵循现有仓库的报告命名规范；若无规范，使用
```
tmp/reviews/YYYY-MM-DD-code-review-report-<random-id>.md
```
格式。
不得覆盖现有报告。
留存范围标识、范围指纹、编排决策、专业人员分配、候选项裁决、审查发现、测试缺口、覆盖情况、证据以及
```
Receiving Handoff
```
（接收交接）部分。
留存审查链标识、代次、触发条件、父审查和决议、语义问题键和指纹、预期行为依据以及继承决议的协调结果。
将已完成的审查报告视为固定输入工件。在接收或实现阶段不得重写报告；后续处理和代码变更需记录在单独的
```
receiving-code-review
```
决议报告中，并通过报告ID关联。
第0代报告可移交至
```
receiving-code-review
```
流程。第1代报告必须采用终端交接方式，不得自动被后续流程使用。
将每一个非Question类发现和独立测试缺口精确划分至可操作或延迟处理的交接ID中。将每一个
```
Question
```
和
```
Not covered
```
区域列入对应的开放ID字段。
在声称报告完成前，运行验证工具并修复所有错误。

Workflow

工作流程

Resolve review-chain identity, generation, trigger, scope, baseline, target, and minimal diff inventory.
Launch the orchestration-assessment subagent.
Record and execute the single-reviewer or specialist plan.
Build the semantic diff inventory and
```
A#
```
coverage areas.
Trace changed control, data, security, persistence, integration, and test paths.
Run focused verification where it materially improves confidence.
Collect candidate findings and specialist coverage results.
Independently verify, de-duplicate, challenge, and classify every candidate against its expected-behavior basis and inherited settlements.
Assign final
```
F#
```
,
```
T#
```
, and
```
A#
```
IDs plus semantic issue fingerprints.
Derive the recommendation from unresolved items and coverage.
Write the canonical report from the template.
Run
```
scripts/validate_review_report.py
```
and correct all failures.
Return a short summary with report path, recommendation, completion, severity counts, orchestration mode, and top risks.

确定审查链标识、代次、触发条件、范围、基线、目标和最小差异清单。
启动编排评估子Agent。
记录并执行单人审查或专业审查计划。
构建语义差异清单和
```
A#
```
覆盖区域。
追踪变更的控制流、数据流、安全、持久化、集成和测试路径。
开展聚焦验证以显著提升信心。
收集候选发现和专业审查人员的覆盖结果。
针对每个候选发现，结合预期行为依据和继承决议进行独立验证、去重、质疑和分类。
分配最终的
```
F#
```
、
```
T#
```
和
```
A#
```
标识以及语义问题指纹。
根据未解决项和覆盖情况得出审查建议。
基于模板撰写规范报告。
运行
```
scripts/validate_review_report.py
```
并修复所有错误。
返回包含报告路径、建议、完成状态、严重程度统计、编排模式和最高风险项的简短摘要。

Final Self-Check

最终自检

The assessment subagent ran, or the report honestly records the unavailable fallback.
The orchestration decision is supported by scope and risk, not arbitrary agent count.
Every specialist candidate was verified, rejected, merged, or retained with evidence.
Every changed review-relevant or unknown-impact area has an
```
A#
```
row.
Every
```
F#
```
and
```
T#
```
has an authoritative expected-behavior basis or is an explicit
```
Question
```
, plus a unique semantic issue fingerprint.
Generation and handoff are consistent: generation
```
0
```
may allow receiving; generation
```
1
```
is terminal and links its parent resolution.
Every indexed finding has one matching card and every
```
Finding F#
```
area references a real finding.
Every
```
Not covered
```
row has a reason and concrete next step.
Recommendation mapping is exact.
The report validator passes.
Git state is unchanged.

已运行评估子Agent，或报告如实记录了子Agent不可用的替代方案。
编排决策由范围和风险支撑，而非随意的Agent数量。
每个专业审查人员的候选发现都已验证、拒绝、合并或留存并附带证据。
每个与审查相关的变更区域或未知影响区域都有对应的
```
A#
```
条目。
每个
```
F#
```
和
```
T#
```
都有权威的预期行为依据或明确标记为
```
Question
```
，且带有唯一的语义问题指纹。
代次和交接方式一致：第0代可移交至接收流程；第1代为终端报告并关联其父决议。
每个索引的审查发现都有对应的卡片，且每个
```
Finding F#
```
区域都指向真实的审查发现。
每个
```
Not covered
```
条目都有原因和具体后续步骤。
建议映射准确。
报告验证工具通过。
Git状态未发生变更。