review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review

代码审查

Review existing code with independent lenses before deciding whether it is safe to ship.

在决定代码是否可安全发布前，从独立视角审查现有代码。

Principles

原则

Prefer parallel reviewer personas when the concerns are independent
Evidence beats taste
Load shared doctrine from the target repo's guidance files such as
```
AGENTS.md
```
,
```
CLAUDE.md
```
, or repo rules
Keep findings risk-focused; do not drown the user in low-value nits
Always list the reviewer personas you used, even when there were only one or two
Always include an explicit
```
unverified areas
```
line, even if the answer is
```
none
```
Always choose the verdict from exactly:
```
ship it
```
,
```
needs review
```
,
```
blocked
```
If runtime proof for your own completed change is the goal, hand off to
```
verify
```

当关注点相互独立时，优先采用并行审查者角色
证据优先于个人偏好
从目标仓库的指导文件（如
```
AGENTS.md
```
、
```
CLAUDE.md
```
或仓库规则）中加载共享准则
聚焦风险发现；不要用无价值的细枝末节淹没用户
始终列出你使用的审查者角色，即使只有一两个
始终明确列出「unverified areas（未验证区域）」，即使答案是
```
none
```
必须从以下选项中选择结论：
```
ship it
```
、
```
needs review
```
、
```
blocked
```
如果目标是为自己已完成的变更提供运行时证明，请转用
```
verify
```
功能

Handoffs

任务交接

Need to prove your own completed change works on real surfaces → use
```
verify
```
Review is blocked because the repo cannot be booted or exercised reliably → use
```
agent-readiness
```
Main problem is stale AGENTS.md, README, specs, or repo docs → use
```
docs
```

需要证明自己已完成的变更在真实环境中可运行 → 使用
```
verify
```
因仓库无法可靠启动或运行导致审查阻塞 → 使用
```
agent-readiness
```
主要问题是
```
AGENTS.md
```
、README、规格文档或仓库文档过时 → 使用
```
docs
```

Before You Start

开始前准备

Define the scope: file, diff, branch, commit range, or PR
Load the target repo's guidance files such as
```
AGENTS.md
```
,
```
CLAUDE.md
```
, or repo rules, when present
Choose reviewer personas from references/reviewer-selection.md
Decide which personas can run independently in parallel

Default personas:

reviewers/general.md
reviewers/tests.md
reviewers/silent-failures.md

Add conditional personas only when they earn their keep:

reviewers/types.md
reviewers/cleanup.md
reviewers/comments.md

Persona shortcuts:

doc-only or comment-only diffs: use
```
general
```
plus
```
comments
```
; skip
```
tests
```
,
```
types
```
,
```
silent-failures
```
, and
```
cleanup
```
unless the diff actually justifies them
type-shape or schema changes: add
```
types
```
dead files, deprecated paths, or obviously unused helpers: add
```
cleanup
```
and call out deletion explicitly when warranted
mock-heavy or shallow tests around risky behavior: make that a finding rather than treating test presence as proof

定义审查范围：文件、diff、分支、提交范围或PR
若存在目标仓库的指导文件（如
```
AGENTS.md
```
、
```
CLAUDE.md
```
或仓库规则），请加载这些文件
从references/reviewer-selection.md中选择审查者角色
确定哪些角色可以独立并行执行

默认角色：

reviewers/general.md
reviewers/tests.md
reviewers/silent-failures.md

仅在必要时添加条件角色：

reviewers/types.md
reviewers/cleanup.md
reviewers/comments.md

角色快捷选择：

仅涉及文档或注释的diff：使用
```
general
```
加
```
comments
```
角色；除非diff确实需要，否则跳过
```
tests
```
、
```
types
```
、
```
silent-failures
```
和
```
cleanup
```
类型结构或模式变更：添加
```
types
```
角色
死文件、已弃用路径或明显未使用的辅助工具：添加
```
cleanup
```
角色，并在必要时明确指出需删除
针对高风险行为的大量模拟或浅层测试：将此作为一项发现，而非将测试存在视为证明

Workflow

工作流程

1. Scope nearby risk

1. 界定周边风险

Review the requested code, but inspect adjacent behavior when the risk leaks past the named diff.

审查指定代码，但当风险超出命名diff范围时，需检查相邻行为。

2. Run reviewer personas

2. 执行审查者角色

Use parallel subagents when available. Keep each persona concern-focused and independent.

Concrete starting points:

```
git diff --stat <base>...HEAD
```
to size the change
```
git diff <base>...HEAD -- <path>
```
to inspect risky files
targeted tests such as
```
pnpm test path/to/spec
```
when behavior claims need proof

若有可用的并行子代理，请使用它们。确保每个角色聚焦于特定关注点且相互独立。

具体起始操作：

使用
```
git diff --stat <base>...HEAD
```
查看变更规模
使用
```
git diff <base>...HEAD -- <path>
```
检查高风险文件
当需要证明行为有效性时，执行针对性测试，如
```
pnpm test path/to/spec
```

3. Collect evidence

3. 收集证据

Cite exact file references for static findings
Run the smallest runtime check that changes the verdict when the repo supports it
If something is unverified, say so explicitly instead of bluffing
If legacy or dead code is still present, say whether it should be deleted or why it must stay
If tests mock the main integrations or boundaries, say that the behavior is still unverified on the real surface

针对静态发现，引用确切的文件位置
当仓库支持时，执行能改变结论的最小运行时检查
若存在未验证项，请明确说明，不要含糊其辞
若仍存在遗留或死代码，请说明是否应删除或保留的原因
若测试模拟了主要集成或边界，请说明该行为在真实环境中仍未验证

4. Synthesize the verdict

4. 生成结论

Produce one clear outcome:

```
ship it
```
```
needs review
```
```
blocked
```

Order findings by severity. If no findings are discovered, say that explicitly and mention any residual risk or testing gap.

生成一个明确的结果：

```
ship it
```
```
needs review
```
```
blocked
```

按严重程度排序发现的问题。若未发现任何问题，请明确说明，并提及任何残留风险或测试缺口。

Output

输出

After review, report:

verdict
scope reviewed
reviewer personas used
top findings by severity
exact evidence: file references, commands, traces, or responses
unverified areas or readiness gaps
recommended follow-up: implementation,
```
verify
```
,
```
agent-readiness
```
, or
```
docs
```

Use those labels explicitly. Do not replace them with softer prose like "safe to merge" or "do not ship today".

Example:

text

verdict: needs review
scope reviewed: feature/auth-session branch
reviewer personas: general, tests, silent-failures
finding: high — src/auth/session.ts:42 fallback returns an anonymous session when token parsing fails
evidence: targeted test passes only for valid tokens; no failure-path coverage covers malformed headers
unverified areas: runtime behavior for malformed OAuth callbacks
recommended follow-up: implementation

审查完成后，需报告以下内容：

verdict → 结论
scope reviewed → 审查范围
reviewer personas used → 使用的审查者角色
top findings by severity → 按严重程度排序的主要问题
exact evidence: file references, commands, traces, or responses → 确切证据：文件引用、命令、追踪信息或响应
unverified areas or readiness gaps → 未验证区域或就绪缺口
recommended follow-up: implementation,
```
verify
```
,
```
agent-readiness
```
, or
```
docs
```
→ 建议后续操作：实现、
```
verify
```
、
```
agent-readiness
```
或
```
docs
```

请明确使用上述标签。不要用“可合并”或“今日请勿发布”等模糊表述替代。

示例：

text

verdict: needs review
scope reviewed: feature/auth-session branch
reviewer personas: general, tests, silent-failures
finding: high — src/auth/session.ts:42 fallback returns an anonymous session when token parsing fails
evidence: targeted test passes only for valid tokens; no failure-path coverage covers malformed headers
unverified areas: runtime behavior for malformed OAuth callbacks
recommended follow-up: implementation

References

参考资料

references/reviewing.md — reviewer persona workflow, evidence expectations, and verdict synthesis
references/reviewer-selection.md — which reviewer personas to run for which change shapes
reviewers/ — specialized review lenses

references/reviewing.md — 审查者角色工作流程、证据要求及结论生成
references/reviewer-selection.md — 针对不同变更类型选择对应的审查者角色
reviewers/ — 专业审查视角