review-diff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review diff — pre-PR code review

代码差异审查 — PR前代码评审

Produce a senior-level review of all changes between the current branch and

origin/main

, organized by severity, with file-and-line references.

以资深开发者视角，对当前分支与

origin/main

之间的所有变更进行评审，按严重程度分类，并标注文件及行号。

Before You Start

开始之前

```
CLAUDE.md
```
— the project's coding conventions and "Things to Know." The review is FROM this perspective.
Any scope-level
```
CLAUDE.md
```
under subdirectories touched by the diff — scope-specific rules override root.
Recent ADRs (
```
docs/adr/
```
,
```
docs/decisions/
```
, or
```
docs/arc42/decisions/
```
) — the why behind recent architectural rules.

```
CLAUDE.md
```
— 项目的编码规范及“须知事项”。评审需以此文件为基准。
差异涉及的子目录下的任何范围级
```
CLAUDE.md
```
— 范围特定规则优先于根目录规则。
近期的ADRs（
```
docs/adr/
```
、
```
docs/decisions/
```
或
```
docs/arc42/decisions/
```
） — 近期架构规则背后的决策原因。

Step 1: gather the diff

步骤1：获取代码差异

bash

git fetch origin main
git diff origin/main...HEAD
git diff origin/main...HEAD --stat
git log origin/main..HEAD --oneline

Read the full diff end to end. Understand every change before reviewing.

bash

git fetch origin main
git diff origin/main...HEAD
git diff origin/main...HEAD --stat
git log origin/main..HEAD --oneline

从头到尾阅读完整的代码差异，在评审前理解每一处变更。

Step 2: read affected CLAUDE.md files

步骤2：阅读受影响的CLAUDE.md文件

For every top-level directory touched by the diff, check for a scope-level

CLAUDE.md

. Example:

bash

git diff origin/main...HEAD --name-only | awk -F/ '{print $1"/"$2}' | sort -u | while read d; do
  [ -f "$d/CLAUDE.md" ] && echo "READ: $d/CLAUDE.md"
done

对于差异涉及的每个顶级目录，检查是否存在范围级

CLAUDE.md

。示例：

bash

git diff origin/main...HEAD --name-only | awk -F/ '{print $1"/"$2}' | sort -u | while read d; do
  [ -f "$d/CLAUDE.md" ] && echo "READ: $d/CLAUDE.md"
done

Step 3: review checklist

步骤3：评审检查清单

Architecture and boundaries

架构与边界

Code is in the correct scope (shared code in the project's designated shared library — common locations are
```
src/lib/
```
,
```
src/shared/
```
, or a monorepo's core package — and scope-specific code in its scope).
No cross-scope imports where the project's rule forbids them (check root
```
CLAUDE.md
```
for the dependency-direction rule).
Layering respected (controller → service → repository or equivalent).
New public APIs match the existing pattern — read an adjacent file for comparison.

代码位于正确的范围（共享代码存放在项目指定的共享库中——常见位置为
```
src/lib/
```
、
```
src/shared/
```
或单体仓库的核心包，范围特定代码存放在对应范围内）。
不存在项目规则禁止的跨范围导入（查看根目录
```
CLAUDE.md
```
中的依赖方向规则）。
分层结构得到遵守（控制器 → 服务 → 仓库或类似结构）。
新的公共API符合现有模式——可参考相邻文件进行对比。

Coding conventions

编码规范

Review against every convention in root

CLAUDE.md

. Pay special attention to rules that linters don't catch:

Use of typed errors vs generic
```
catch (e)
```
.
Dependency-injection conventions.
Async/sync discipline (e.g., no blocking I/O in async code paths).
Naming patterns for new public symbols.

对照根目录

CLAUDE.md

中的每一项规范进行评审。特别注意代码检查工具无法捕获的规则：

类型错误与通用
```
catch (e)
```
的使用。
依赖注入规范。
异步/同步规范（例如，异步代码路径中不存在阻塞I/O）。
新公共符号的命名模式。

Security (OWASP-style pass)

安全性（OWASP式检查）

No string concatenation in SQL, shell, or logging.
Auth and permission checks present on new endpoints.
Secrets are not hardcoded; use the project's secrets mechanism.
Input validated at boundaries (API params, form submissions, webhook payloads).
Untrusted input not interpolated into templates or
```
eval
```
-like constructs.

SQL、Shell或日志中不存在字符串拼接。
新端点包含身份验证与权限检查。
未硬编码密钥；使用项目的密钥管理机制。
在边界处验证输入（API参数、表单提交、Webhook负载）。
不可信输入未插入到模板或类似
```
eval
```
的结构中。

Testing

测试

New code has corresponding tests.
Tests assert something meaningful — not just "no exception."
External services (DB, HTTP APIs, message brokers) are isolated or mocked appropriately.
Test markers/tags (slow, integration, flaky) applied where the project uses them.

新代码有对应的测试。
测试断言有实际意义——不只是“无异常”。
外部服务（数据库、HTTP API、消息队列）已适当隔离或模拟。
已根据项目要求添加测试标记/标签（慢测试、集成测试、不稳定测试）。

Performance (when relevant)

性能（相关时）

No N+1 queries introduced.
No loops with per-iteration network calls where a batch would do.
Hot paths don't allocate unnecessarily.

未引入N+1查询。
在可批量处理的场景下，不存在每次迭代都调用网络的循环。
热点路径无不必要的内存分配。

Step 4: produce the review

步骤4：生成评审报告

Format findings by severity. Be specific: reference

file.ts:42

, not "somewhere in the users code."

markdown

undefined

按严重程度整理发现的问题。需具体：标注

file.ts:42

，而非“用户代码中的某处”。

markdown

undefined

Review of {branch} ({N} files, {+X -Y} lines)

{branch}分支评审（共{N}个文件，{+X -Y}行变更）

Critical (must fix before merge)

严重问题（合并前必须修复）

```
src/api/users.ts:42
```
— SQL injection via
```
getUserByName
```
: user input is concatenated into the query. Use the parameterized
```
db.query(..., [params])
```
form — see
```
src/api/orders.ts:78
```
for the pattern.

```
src/api/users.ts:42
```
—
```
getUserByName
```
存在SQL注入风险：用户输入被拼接到查询语句中。请使用参数化的
```
db.query(..., [params])
```
形式——可参考
```
src/api/orders.ts:78
```
中的示例。

Important (should fix)

重要问题（建议修复）

```
src/services/payment.ts:15
```
— new service does not extend
```
ServiceBase
```
. Convention per root
```
CLAUDE.md
```
is that all services extend it for logging + error-wrapping.

```
src/services/payment.ts:15
```
— 新服务未继承
```
ServiceBase
```
。根据根目录
```
CLAUDE.md
```
的规范，所有服务需继承该类以实现日志记录和错误包装。

Suggestions (nice to have)

建议（优化项）

```
src/lib/utils.ts:22
```
—
```
formatDate
```
duplicates logic already in
```
src/lib/dates.ts:8
```
. Consider re-using or removing the duplicate.

```
src/lib/utils.ts:22
```
—
```
formatDate
```
方法与
```
src/lib/dates.ts:8
```
中的逻辑重复。考虑复用或删除重复代码。

What looks good

亮点

Error handling in
```
src/api/auth.ts
```
correctly uses
```
AppError
```
subclasses.
New tests in
```
tests/integration/users.spec.ts
```
cover both happy path and permission denial.

undefined

```
src/api/auth.ts
```
中的错误处理正确使用了
```
AppError
```
子类。
```
tests/integration/users.spec.ts
```
中的新测试覆盖了正常流程和权限拒绝场景。

undefined

Rules for the review output

评审输出规则

Be specific: file:line, not "somewhere."
Be constructive: state the fix, not just the problem.
Be honest: if the code is good, say so in What looks good.
Skip nitpicks that the formatter or linter catches (principle 03 — don't duplicate tooling).
Don't suggest adding backwards-compatibility unless the user asked.

内容具体：标注文件:行号，而非“某处”。
具有建设性：说明修复方法，而非仅指出问题。
客观诚实：如果代码质量良好，在亮点部分明确说明。
忽略格式化工具或代码检查工具已捕获的细节问题（原则03：不重复工具的工作）。
除非用户要求，否则不建议添加向后兼容代码。

Verify

验证

The review is presented to the user as a markdown report — there's no auto-verification. Sanity checks:

bash

undefined

评审结果以markdown报告形式呈现给用户——无自动验证机制。可进行以下合理性检查：

bash

undefined

Did you miss any files in the diff?

是否遗漏了差异中的某些文件？

git diff origin/main...HEAD --name-only | wc -l

Your review should touch a substantial fraction of these (not necessarily every one —

你的评审应覆盖其中大部分文件（无需全部覆盖——仅格式化变更或纯测试代码添加可能无需标记）。

formatter-only changes and pure test additions may not need flagging).

—

undefined

undefined

Common Mistakes

常见错误

Mistake	Correction
Re-flagging issues the formatter already caught	Skip them — focus on substance. Principle 03: don't duplicate tooling.
Vague "this could be cleaner"	Quote the line, propose the specific change, name a file that already does it right.
Only finding problems, never acknowledging good work	The "What looks good" section matters — it calibrates the reviewer's honesty and helps the author learn what's landing well.
Reviewing against rules from a different project	Re-read `CLAUDE.md` before starting. Every project has its own conventions.

错误	修正方式
重复标记格式化工具已捕获的问题	忽略此类问题——专注于实质性内容。原则03：不重复工具的工作。
模糊表述“此处可优化”	引用具体代码行，提出明确的修改建议，并指出已实现该规范的参考文件。
仅指出问题，未认可优秀代码	亮点部分至关重要——它能体现评审的客观性，帮助开发者了解哪些做法是值得肯定的。
参照其他项目的规则进行评审	评审前重新阅读 `CLAUDE.md` 。每个项目都有自己的规范。