review-verification-protocol

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review Verification Protocol

评审验证协议

This protocol MUST be followed before reporting any code review finding. Skipping these steps leads to false positives that waste developer time and erode trust in reviews.

在提交任何代码评审发现前，必须遵循此协议。跳过这些步骤会导致误报，浪费开发者时间并削弱对评审的信任。

Pre-Report Verification Checklist

提交前验证清单

Verification by Issue Type

按问题类型分类的验证

"Unused Variable/Function"

未使用的变量/函数

Before flagging, you MUST:

Search for ALL references in the codebase (grep/find)
Check if it's exported and used by external consumers
Check if it's used via reflection, decorators, or dynamic dispatch
Verify it's not a callback passed to a framework

Common false positives:

State setters in React (may trigger re-renders even if value appears unused)
Variables used in templates/JSX
Exports used by consuming packages

在标记之前，你必须：

搜索代码库中的所有引用（grep/find）
检查它是否已导出并被外部消费者使用
检查它是否通过反射、装饰器或动态调度被使用
验证它不是传递给框架的回调函数

常见误报：

React中的状态设置函数（即使值看似未使用，也可能触发重新渲染）
模板/JSX中使用的变量
被消费包使用的导出

"Missing Validation/Error Handling"

缺少验证/错误处理

Before flagging, you MUST:

Check if validation exists at a higher level (caller, middleware, route handler)
Check if the framework provides validation (Pydantic, Zod, TypeScript)
Verify the "missing" check isn't present in a different form

Common false positives:

Framework already validates (FastAPI + Pydantic, React Hook Form)
Parent component validates before passing props
Error boundary catches at higher level

在标记之前，你必须：

检查验证是否在更高层级存在（调用方、中间件、路由处理器）
检查框架是否提供验证（Pydantic、Zod、TypeScript）
验证“缺失”的检查是否以其他形式存在

常见误报：

框架已进行验证（FastAPI + Pydantic、React Hook Form）
父组件在传递props之前已验证
错误边界在更高层级捕获错误

"Type Assertion/Unsafe Cast"

类型断言/不安全转换

Before flagging, you MUST:

Confirm it's actually an assertion, not an annotation
Check if the type is narrowed by runtime checks before the point
Verify if framework guarantees the type (loader data, form data)

Valid patterns often flagged incorrectly:

typescript

// Type annotation, NOT assertion
const data: UserData = await loader()

// Type narrowing makes this safe
if (isUser(data)) {
  data.name  // TypeScript knows this is User
}

在标记之前，你必须：

确认它确实是断言，而非注解
检查类型是否在运行时检查后被收窄
验证框架是否保证类型（加载器数据、表单数据）

常被错误标记的有效模式：

typescript

// 类型注解，而非断言
const data: UserData = await loader()

// 类型收窄使此操作安全
if (isUser(data)) {
  data.name  // TypeScript知道这是User类型
}

"Potential Memory Leak/Race Condition"

潜在内存泄漏/竞态条件

Before flagging, you MUST:

Verify cleanup function is actually missing (not just in a different location)
Check if AbortController signal is checked after awaits
Confirm the component can actually unmount during the async operation

Common false positives:

Cleanup exists in useEffect return
Signal is checked (code reviewer missed it)
Operation completes before unmount is possible

在标记之前，你必须：

确认清理函数确实缺失（而非仅在其他位置）
检查AbortController信号是否在await之后被检查
确认组件在异步操作期间确实可以卸载

常见误报：

清理函数存在于useEffect的返回值中
已检查信号（代码评审者遗漏了）
操作在卸载前已完成

"Performance Issue"

性能问题

Before flagging, you MUST:

Confirm the code runs frequently enough to matter (render vs click handler)
Verify the optimization would have measurable impact
Check if the framework already optimizes this (React compiler, memoization)

Do NOT flag:

Functions created in click handlers (runs once per click)
Array methods on small arrays (< 100 items)
Object creation in event handlers

在标记之前，你必须：

确认代码运行频率足够高（渲染 vs 点击处理器）
验证优化会产生可衡量的影响
检查框架是否已对此进行优化（React编译器、记忆化）

请勿标记：

点击处理器中创建的函数（每次点击运行一次）
小型数组（<100项）上的数组方法
事件处理器中的对象创建

Severity Calibration

严重程度校准

Critical (Block Merge)

严重（阻止合并）

ONLY use for:

Security vulnerabilities (injection, auth bypass, data exposure)
Data corruption bugs
Crash-causing bugs in happy path
Breaking changes to public APIs

仅用于：

安全漏洞（注入、认证绕过、数据泄露）
数据损坏bug
正常流程中导致崩溃的bug
对公共API的破坏性变更

Major (Should Fix)

主要（应修复）

Use for:

Logic bugs that affect functionality
Missing error handling that causes poor UX
Performance issues with measurable impact
Accessibility violations

用于：

影响功能的逻辑bug
导致不良用户体验的缺失错误处理
有可衡量影响的性能问题
可访问性违规

Minor (Consider Fixing)

次要（考虑修复）

Use for:

Code clarity improvements
Documentation gaps
Inconsistent style (within reason)
Non-critical test coverage gaps

用于：

代码清晰度改进
文档缺口
不一致的风格（合理范围内）
非关键测试覆盖缺口

Do NOT Flag At All

完全请勿标记

Style preferences where both approaches are valid
Optimizations with no measurable benefit
Test code not meeting production standards (intentionally simpler)
Library/framework internal code (shadcn components, generated code)
Hypothetical issues that require unlikely conditions

两种写法都有效的风格偏好
无衡量收益的优化
未达到生产标准的测试代码（有意简化）
库/框架内部代码（shadcn组件、生成代码）
需要不太可能的条件才会出现的假设性问题

Valid Patterns (Do NOT Flag)

有效模式（请勿标记）

TypeScript

Pattern	Why It's Valid
`map.get(key) \|\| []`	`Map.get()` returns `T \| undefined` , fallback is correct
Class exports without separate type export	Classes work as both value and type
`as const` on literal arrays	Creates readonly tuple types
Type annotation on variable declaration	Not a type assertion
`satisfies` instead of `as`	Type checking without assertion

模式	有效原因
`map.get(key)
无单独类型导出的类导出	类可同时作为值和类型使用
字面量数组上的 `as const`	创建只读元组类型
变量声明上的类型注解	不是类型断言
使用 `satisfies` 而非 `as`	无需断言即可进行类型检查

React

Pattern	Why It's Valid
Array index as key (static list)	Valid when: items don't reorder, list is static, no item identity needed
Inline arrow in onClick	Valid for non-performance-critical handlers (runs once per click)
State that appears unused	May be set via refs, external callbacks, or triggers re-renders
Empty dependency array with refs	Refs are stable, don't need to be dependencies
Non-null assertion after check	TypeScript narrowing may not track through all patterns

模式	有效原因
数组索引作为key（静态列表）	在以下情况有效：项不会重新排序、列表是静态的、不需要项标识
onClick中的内联箭头函数	对非性能关键的处理器有效（每次点击运行一次）
看似未使用的状态	可能通过refs、外部回调设置，或触发重新渲染
带refs的空依赖数组	Refs是稳定的，不需要作为依赖
检查后的非空断言	TypeScript收窄可能无法跟踪所有模式

Testing

测试

Pattern	Why It's Valid
`toHaveTextContent` without regex	Handles nested text correctly
Mock at module level	Defined once, not duplicated
Index-based test data	Tests don't need stable identity
Simplified error messages	Test clarity over production polish

模式	有效原因
不带正则的 `toHaveTextContent`	正确处理嵌套文本
模块级mock	定义一次，无需重复
基于索引的测试数据	测试不需要稳定标识
简化的错误消息	测试清晰度优先于生产级完善度

General

通用

Pattern	Why It's Valid
`+?` lazy quantifier in regex	Prevents over-matching, correct for many patterns
Direct string concatenation	Simpler than template literals for simple cases
Multiple returns in function	Can improve readability
Comments explaining "why"	Better than no comments

模式	有效原因
正则中的 `+?` 惰性量词	防止过度匹配，适用于许多模式
直接字符串拼接	对于简单情况比模板字面量更简洁
函数中的多个返回	可提高可读性
解释“原因”的注释	比无注释更好

Context-Sensitive Rules

上下文相关规则

React Keys

Flag array index as key ONLY IF ALL of these are true:

Items CAN be reordered (sortable list, drag-drop)
Items CAN be inserted/removed from middle
Items HAVE stable identifiers available (id, uuid)
The list is NOT completely replaced atomically

仅当所有以下条件都满足时，才标记数组索引作为key：

项可以重新排序（可排序列表、拖拽）
项可以从中间插入/删除
项有可用的稳定标识符（id、uuid）
列表不是完全原子性替换的

useEffect Dependencies

useEffect依赖

Flag missing dependency ONLY IF:

The value actually changes during component lifetime
Stale closure would cause incorrect behavior
The value is NOT a ref (refs are stable)
The value is NOT a stable callback (useCallback with empty deps)

仅当以下条件满足时，才标记缺失的依赖：

值在组件生命周期中实际会变化
过时闭包会导致错误行为
值不是ref（refs是稳定的）
值不是稳定回调（带空依赖的useCallback）

Error Handling

错误处理

Flag missing try/catch ONLY IF:

No error boundary catches this at a higher level
The framework doesn't handle errors (loader errorElement)
The error would cause a crash, not just a failed operation
User needs specific feedback for this error type

仅当以下条件满足时，才标记缺失的try/catch：

没有错误边界在更高层级捕获此错误
框架不处理错误（加载器errorElement）
错误会导致崩溃，而非仅操作失败
用户需要此错误类型的特定反馈

Before Submitting Review

提交评审前

Final verification:

Re-read each finding and ask: "Did I verify this is actually an issue?"
For each finding, can you point to the specific line that proves the issue exists?
Would a domain expert agree this is a problem, or is it a style preference?
Does fixing this provide real value, or is it busywork?
Format every finding as:
```
[FILE:LINE] ISSUE_TITLE
```

If uncertain about any finding, either:

Remove it from the review
Mark it as a question rather than an issue
Verify by reading more code context

最终验证：

重新阅读每个发现并自问：“我是否已验证这确实是一个问题？”
对于每个发现，你能否指出证明问题存在的具体行？
领域专家会同意这是一个问题，还是仅仅是风格偏好？
修复此问题是否能提供实际价值，还是只是无用功？
将每个发现格式化为：
```
[文件:行号] 问题标题
```

如果对任何发现不确定，请：

从评审中移除它
将其标记为疑问而非确定的问题
通过阅读更多代码上下文进行验证