code-review-mastery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

激活此技能后，首次回复需以🧢表情开头。

Local Diff Code Review

本地差异代码审查

This skill reviews your local git changes (staged or unstaged) with project-aware analysis. It gathers project context - lint rules, conventions, framework patterns - then produces structured

[MAJOR]

[MINOR]

findings you can work through interactively.

此技能通过项目感知分析来审查你的本地Git变更（暂存或未暂存）。它会收集项目上下文——包括Lint规则、编码规范、框架模式——然后生成结构化的

[MAJOR]

[MINOR]

问题结果，你可以交互式地处理这些问题。

When to use this skill

何时使用此技能

Trigger this skill when the user:

Asks to review their local changes, staged changes, or unstaged changes
Says "review my diff", "check my code", "code review before commit"
Wants a quality check on what they're about to commit or push
Asks "what's wrong with my changes" or "anything I should fix before committing"

Do NOT trigger this skill for:

Reviewing remote PRs or GitHub links (use a PR review tool instead)
Writing or refactoring code from scratch
Architecture discussions not tied to a specific set of changes
General code quality advice without a concrete diff to review

当用户出现以下情况时触发此技能：

要求审查其本地变更、暂存变更或未暂存变更
说出"review my diff"、"check my code"、"code review before commit"
希望对即将提交或推送的代码进行质量检查
询问"我的变更有什么问题"或"提交前我需要修复什么"

请勿在以下场景触发此技能：

审查远程PR或GitHub链接（请使用PR审查工具）
从头编写或重构代码
与特定变更集无关的架构讨论
没有具体差异可审查的通用代码质量建议

Key principles

核心原则

Review the code, not the person - Findings are about the change, not the author. Frame issues as observations, not judgments.
Prioritize by impact - Security > Correctness > Performance > Design > Readability > Convention. Spend most analysis time at the top of this list.
Two-tier severity - Every finding is either
```
[MAJOR]
```
(must fix) or
```
[MINOR]
```
(consider fixing). No ambiguity, no middle ground.
Respect project conventions - Read configs and surrounding code before judging. What looks wrong in isolation may be the project's established pattern.
Present, don't preach - Structured findings with file locations and suggested fixes. Not essays about best practices.

审查代码，而非针对个人 - 问题结果针对的是变更内容，而非作者。将问题表述为观察结论，而非评判。
按影响优先级排序 - 优先级顺序：安全 > 正确性 > 性能 > 设计 > 可读性 > 编码规范。将大部分分析时间放在优先级高的项上。
两级严重程度 - 每个问题结果要么是
```
[MAJOR]
```
（必须修复），要么是
```
[MINOR]
```
（建议修复）。无模糊地带，不设中间级别。
尊重项目规范 - 在评判前先阅读配置文件和周边代码。孤立看有问题的写法，可能是项目既定的规范模式。
客观呈现，而非说教 - 结构化的问题结果需包含文件位置和建议修复方案，而非长篇大论的最佳实践。

[MAJOR] vs [MINOR] definitions

[MAJOR]

与

[MINOR]

定义

Severity	Criteria	Examples
`[MAJOR]`	Must be fixed. Would block a PR in a professional code review.	Bugs, security vulnerabilities, data loss risks, missing error handling for critical paths, violations of explicit project rules (lint configs, CLAUDE.md), missing tests for new behavior
`[MINOR]`	Improves quality but code works without it. Reviewer would approve anyway.	Naming improvements, readability tweaks, minor performance gains, style inconsistencies, documentation gaps, implicit convention deviations

严重程度	判定标准	示例
`[MAJOR]`	必须修复。在专业代码审查中会阻止PR合并。	漏洞、安全隐患、数据丢失风险、关键路径缺失错误处理、违反明确的项目规则（Lint配置、CLAUDE.md）、新行为缺失测试
`[MINOR]`	可提升代码质量，但不修复也不影响功能运行。审查人员仍会批准PR。	命名优化、可读性调整、小幅性能提升、风格不一致、文档缺失、偏离隐含规范

Decision rule

判定规则

Ask: "Would a staff engineer block a PR on this?"

Yes -
```
[MAJOR]
```
No, but they'd leave a comment -
```
[MINOR]
```
No, they wouldn't mention it - Don't report it

When in doubt, downgrade to

[MINOR]

. False positives at

[MAJOR]

erode trust in the review.

问自己："资深工程师会因为这个问题阻止PR合并吗？"

是 - 标记为
```
[MAJOR]
```
否，但会留下评论 - 标记为
```
[MINOR]
```
否，甚至不会提及 - 无需报告

若存在疑问，降级为

[MINOR]

。误标记为

[MAJOR]

会降低审查的可信度。

The review workflow

审查工作流

Execute these four phases in order. Do not skip phases.

按顺序执行以下四个阶段，不得跳过任何阶段。

Phase 1: DETECT

阶段1：检测

Determine what changes exist and what to review.

Run
```
git diff --stat
```
(unstaged) and
```
git diff --cached --stat
```
(staged)
If both have changes, ask the user which set to review (or "both")
If neither has changes, inform the user: "No local changes to review." Stop.
Identify languages from file extensions in the diff
Count files changed, insertions, and deletions for the report header
If the diff exceeds 500 lines, warn the user and suggest focusing on
```
[MAJOR]
```
findings only to keep the review actionable

确定存在哪些变更以及审查范围。

执行
```
git diff --stat
```
（未暂存）和
```
git diff --cached --stat
```
（暂存）
如果两者都有变更，询问用户要审查哪一组（或"全部"）
如果没有任何变更，告知用户："无本地变更可审查。" 然后停止操作。
通过差异中的文件扩展名识别开发语言
统计变更文件数、新增行数和删除行数，用于报告标题
如果差异超过500行，向用户发出警告，并建议仅关注
```
[MAJOR]
```
问题，以确保审查具有可操作性

Phase 2: CONTEXT

阶段2：上下文收集

Gather project context to calibrate the review. See

references/context-detection.md

for the full detection guide.

Read
```
CLAUDE.md
```
,
```
AGENT.md
```
,
```
README.md
```
if they exist in the project root
Read relevant lint and format configs (ESLint, Prettier, Ruff, tsconfig, etc.)
Scan 2-3 existing files in the same directories as changed files to detect naming, import, and error handling conventions
Note the framework and language from config files
Store context mentally - do not output it to the user. Use it to calibrate severity and skip findings that linters already enforce.

收集项目上下文以校准审查标准。完整的检测指南请参阅

references/context-detection.md

。

读取项目根目录下的
```
CLAUDE.md
```
、
```
AGENT.md
```
、
```
README.md
```
（如果存在）
读取相关的Lint和格式化配置文件（ESLint、Prettier、Ruff、tsconfig等）
扫描变更文件所在目录中的2-3个现有文件，以检测命名、导入和错误处理规范
从配置文件中识别框架和开发语言
在脑中存储上下文信息 - 不要向用户输出。用它来校准问题严重程度，并跳过Lint已能检测的问题

Phase 3: ANALYZE

阶段3：分析

Review the actual diff using the review pyramid (bottom-up).

Get the full diff with
```
git diff
```
or
```
git diff --cached
```
For large diffs (>500 lines), process file-by-file with
```
git diff -- <file>
```
Walk through each file's changes with these passes:
1. Security pass - injection, auth, data exposure, secrets
2. Correctness pass - null safety, edge cases, async/await, off-by-one
3. Performance pass - N+1, missing indexes, memory leaks, unbounded queries
4. Design pass - coupling, SRP violations, abstraction levels
5. Readability pass - naming, dead code, magic numbers, nesting depth
6. Convention pass - check against detected project rules and patterns
7. Testing pass - new behavior untested, skipped tests, flaky patterns
For each finding: classify
```
[MAJOR]
```
or
```
[MINOR]
```
, assign a category, note the file and line number

See

references/review-checklist.md

for the detailed per-category checklist.

使用审查金字塔（自底向上）审查实际差异。

通过
```
git diff
```
或
```
git diff --cached
```
获取完整差异
对于大型差异（>500行），使用
```
git diff -- <file>
```
逐个文件处理
按以下步骤检查每个文件的变更：
1. 安全检查 - 注入攻击、认证、数据泄露、敏感信息
2. 正确性检查 - 空值安全、边界情况、async/await、差一错误
3. 性能检查 - N+1查询、缺失索引、内存泄漏、无界查询
4. 设计检查 - 耦合度、单一职责原则违反、抽象层级
5. 可读性检查 - 命名、死代码、魔法值、嵌套深度
6. 规范检查 - 对照检测到的项目规则和模式进行检查
7. 测试检查 - 新行为未测试、跳过测试、不稳定模式
对于每个问题结果：分类为
```
[MAJOR]
```
或
```
[MINOR]
```
，分配类别，记录文件和行号

详细的分类检查清单请参阅

references/review-checklist.md

。

Phase 4: REPORT

阶段4：报告

Present the structured review and offer to fix.

Output the review using the format specification below
After presenting, ask: "Would you like me to fix any of these? Tell me which items or say 'fix all MAJOR' / 'fix all'."

呈现结构化审查结果并提供修复服务。

使用以下格式规范输出审查结果
呈现结果后，询问："你希望我修复其中哪些问题？请告知具体项，或说'修复所有MAJOR'/'全部修复'。"

The review pyramid

审查金字塔

Allocate attention proportionally to impact. Start at the bottom:

         [Convention]       <- least critical; check against project rules
        [Readability]       <- naming, clarity, dead code
      [Design]              <- structure, patterns, coupling
    [Performance]           <- N+1, memory, blocking I/O
  [Correctness]             <- bugs, edge cases, logic errors
[Security / Safety]         <- the most critical layer

A diff with a SQL injection vulnerability does not need a naming discussion - it needs the security fix flagged first.

按影响程度分配注意力。从最底层开始：

         [Convention]       <- 最不关键；对照项目规则检查
        [Readability]       <- 命名、清晰度、死代码
      [Design]              <- 结构、模式、耦合度
    [Performance]           <- N+1查询、内存、阻塞I/O
  [Correctness]             <- 漏洞、边界情况、逻辑错误
[Security / Safety]         <- 最关键层级

如果差异中存在SQL注入漏洞，无需讨论命名问题 - 首先要标记并修复安全问题。

Analysis passes

分析检查步骤

Condensed checklist per pass. See

references/review-checklist.md

for the full version.

各步骤的精简检查清单。完整版本请参阅

references/review-checklist.md

。

Security (all

[MAJOR]

)

安全（全部标记为

[MAJOR]

）

Injection: SQL, HTML/XSS, command injection, path traversal
Auth: missing auth middleware, IDOR, privilege escalation
Data exposure: logging secrets/PII, over-broad API responses
Secrets: API keys, tokens, or credentials in code
CSRF: missing token validation on state-changing endpoints

注入：SQL、HTML/XSS、命令注入、路径遍历
认证：缺失认证中间件、IDOR、权限提升
数据泄露：日志中包含敏感信息/PII、API响应过度暴露
敏感信息：代码中包含API密钥、令牌或凭证
CSRF：状态变更端点缺失令牌验证

Correctness (mostly

[MAJOR]

)

正确性（大多标记为

[MAJOR]

）

Null/undefined safety: unhandled null paths
Edge cases: empty input, zero, negative, boundary values
Async: missing await, unhandled promise rejections, race conditions
Off-by-one: loop bounds, array indices, pagination
Type safety:
```
==
```
vs
```
===
```
, implicit coercion,
```
any
```
casts

空值/未定义安全：未处理空值路径
边界情况：空输入、零、负数、边界值
异步：缺失await、未处理的Promise拒绝、竞态条件
差一错误：循环边界、数组索引、分页
类型安全：
```
==
```
与
```
===
```
、隐式类型转换、
```
any
```
类型转换

Performance (

[MAJOR]

if in hot path,

[MINOR]

otherwise)

性能（热点路径标记为

[MAJOR]

，否则为

[MINOR]

）

N+1 queries: database calls inside loops
Missing indexes: new WHERE/ORDER BY columns without index
Memory leaks: listeners/intervals without cleanup
Unbounded queries: no LIMIT on large table queries
Blocking I/O: synchronous operations in request handlers

N+1查询：循环内调用数据库
缺失索引：新的WHERE/ORDER BY列未加索引
内存泄漏：监听器/定时器未清理
无界查询：大表查询未加LIMIT
阻塞I/O：请求处理程序中的同步操作

Design (

[MINOR]

unless architectural)

设计（除非涉及架构，否则标记为

[MINOR]

）

Tight coupling between unrelated modules
Single Responsibility violations
Mixed abstraction levels within a function
Overly complex conditionals that should be extracted

不相关模块间的紧耦合
违反单一职责原则
函数内混合不同抽象层级
过于复杂的条件判断应提取为独立函数

Readability (

[MINOR]

)

可读性（标记为

[MINOR]

）

Vague names:
```
data
```
,
```
temp
```
,
```
flag
```
, single letters outside tight loops
Dead code: unreachable branches, unused variables, obsolete imports
Magic numbers/strings not extracted to named constants
Deep nesting: more than 3 levels of indentation

模糊命名：
```
data
```
、
```
temp
```
、
```
flag
```
、循环外的单字母变量
死代码：不可达分支、未使用变量、过时导入
未提取为命名常量的魔法数字/字符串
深层嵌套：缩进超过3级

Convention (

[MAJOR]

if explicit rule,

[MINOR]

if implicit pattern)

规范（违反明确规则标记为

[MAJOR]

，违反隐含模式标记为

[MINOR]

）

Violates configured lint rules (ESLint, Ruff, clippy, etc.)
Deviates from naming convention in surrounding files
Import style inconsistent with project pattern
Breaks a rule stated in CLAUDE.md or AGENT.md

违反配置的Lint规则（ESLint、Ruff、clippy等）
偏离周边文件的命名规范
导入风格与项目模式不一致
违反CLAUDE.md或AGENT.md中规定的规则

Testing (

[MAJOR]

for missing tests)

测试（缺失测试标记为

[MAJOR]

）

New behavior without corresponding tests
Tests that don't assert meaningful behavior
Skipped tests without explanation
Test names that don't describe the behavior being verified

新行为未对应测试
未断言有意义行为的测试
无解释的跳过测试
测试名称未描述所验证的行为

Output format specification

输出格式规范

Use this exact structure for the review output:

undefined

审查结果需严格使用以下结构：

undefined

Code Review: [staged|unstaged] changes

代码审查：[暂存/未暂存]变更

Files changed: N | Insertions: +X | Deletions: -Y

变更文件数：N | 新增行数：+X | 删除行数：-Y

[MAJOR] Issues (N)

[MAJOR] 问题（N个）

file.ts:42 [Security] Description of the issue. Suggested fix or approach.
file.ts:87 [Correctness] Description of the issue. Suggested fix or approach.

file.ts:42 [安全] 问题描述。建议修复方案或处理方法。
file.ts:87 [正确性] 问题描述。建议修复方案或处理方法。

[MINOR] Suggestions (N)

[MINOR] 建议（N个）

file.ts:15 [Readability] Description of the suggestion. Suggested improvement.
file.ts:99 [Convention] Description of the deviation. Project convention reference.

file.ts:15 [可读性] 建议描述。建议改进方案。
file.ts:99 [规范] 偏差描述。项目规范参考。

Summary

总结

N major issues to resolve, M minor suggestions to consider. Would you like me to fix any of these? Tell me which items or say "fix all MAJOR" / "fix all".


**Rules for the output:**
- Group all `[MAJOR]` findings first, then all `[MINOR]` findings
- Within each group, order by file path, then line number
- Each finding is a checkbox (`- [ ]`) so the user can track progress
- Each finding includes: file:line, category tag, one-line description, one-line suggested fix
- If there are zero `[MAJOR]` findings, say so explicitly: "No major issues found."
- If there are zero findings at all: "No issues found. Code looks good to commit."
- Always end with the offer to fix

---

需解决N个主要问题，需考虑M个次要建议。你希望我修复其中哪些问题？请告知具体项，或说"修复所有MAJOR"/"全部修复"。


**输出规则：**
- 先分组显示所有`[MAJOR]`问题，再显示所有`[MINOR]`建议
- 同一组内按文件路径、行号排序
- 每个问题结果使用复选框(`- [ ]`)，方便用户跟踪进度
- 每个问题结果需包含：文件:行号、类别标签、一行描述、一行建议修复方案
- 如果没有`[MAJOR]`问题，需明确说明："未发现主要问题。"
- 如果没有任何问题："未发现问题。代码可安全提交。"
- 结尾必须提供修复服务

---

Handling special cases

特殊场景处理

Scenario	How to handle
Large diffs (>500 lines)	Warn the user. Process file-by-file. Focus on `[MAJOR]` only unless user requests full review.
Binary files	Skip with a note: "Skipping binary file: path/to/file"
Generated/lock files	Skip `package-lock.json` , `yarn.lock` , `pnpm-lock.yaml` , `.min.js` , `.generated.*` , and similar. Note skipped files.
No changes	Inform user "No local changes to review." and stop.
Mixed staged/unstaged	Ask user: "You have both staged and unstaged changes. Which would you like me to review? (staged / unstaged / both)"
Merge conflicts	Note conflict markers as `[MAJOR]` and suggest resolving before review.
Only deletions	Review for missing cleanup (dangling references, broken imports, orphaned tests).

场景	处理方式
大型差异（>500行）	向用户发出警告。逐个文件处理。除非用户要求完整审查，否则仅关注 `[MAJOR]` 问题。
二进制文件	跳过并备注："跳过二进制文件：path/to/file"
生成文件/锁文件	跳过 `package-lock.json` 、 `yarn.lock` 、 `pnpm-lock.yaml` 、 `.min.js` 、 `.generated.*` 及类似文件。备注跳过的文件。
无变更	告知用户"无本地变更可审查。" 然后停止操作。
混合暂存/未暂存变更	询问用户："你同时有暂存和未暂存的变更。你希望我审查哪部分？（暂存/未暂存/全部）"
合并冲突	将冲突标记标记为 `[MAJOR]` ，并建议先解决冲突再进行审查。
仅删除操作	审查是否存在遗漏的清理工作（悬空引用、损坏的导入、孤立的测试）。

Anti-patterns

反模式

Avoid these mistakes when producing a review:

Anti-pattern	Why it's wrong	What to do instead
Flagging what linters already catch	Wastes attention if CI enforces the rule	Check if a linter config exists and CI runs it; skip those findings
Ignoring CLAUDE.md / project conventions	Misses the project's actual standards	Always read project configs in Phase 2 before analyzing
Writing essay-length findings	Hard to action, loses signal in noise	One-line description + one-line suggested fix per finding
Marking style preferences as `[MAJOR]`	Erodes trust in severity classification	Only `[MAJOR]` for bugs, security, explicit rule violations, missing tests
Reviewing files not in the diff	Scope creep; confuses the user	Only analyze lines present in the diff output
Inventing project rules	Flagging violations of standards the project doesn't have	Only flag Convention `[MAJOR]` when you found an explicit config/rule
Skipping the offer to fix	Misses the interactive value of this skill	Always end with the fix offer

生成审查结果时需避免以下错误：

反模式	错误原因	正确做法
标记Lint已能检测的问题	如果CI已强制执行该规则，会浪费注意力	检查是否存在Lint配置且CI会运行；跳过这些问题结果
忽略CLAUDE.md/项目规范	不符合项目的实际标准	分析前务必在阶段2读取项目配置文件
撰写长篇大论的问题结果	难以执行，信号易被噪音掩盖	每个问题结果使用一行描述 + 一行建议修复方案
将风格偏好标记为 `[MAJOR]`	会降低严重程度分类的可信度	仅将漏洞、安全问题、违反明确规则、缺失测试标记为 `[MAJOR]`
审查差异中未包含的文件	范围蔓延；会使用户困惑	仅分析diff输出中包含的行
自创项目规则	标记项目未采用的标准违反情况	仅当找到明确的配置/规则时，才标记规范类 `[MAJOR]` 问题
跳过修复服务提议	错失此技能的交互式价值	结尾必须提供修复服务

References

参考资料

For detailed content on specific topics, read the relevant file from

references/

```
references/review-checklist.md
```
- Full per-category review checklist with detailed items for correctness, security, performance, readability, testing, documentation, and convention checks
```
references/context-detection.md
```
- Guide for gathering project context before reviewing: config file detection, framework heuristics, convention sampling, and language-specific focus areas

Load

references/review-checklist.md

when performing a thorough multi-pass review. Load

references/context-detection.md

when the project uses an unfamiliar framework or you need to identify conventions systematically.

如需特定主题的详细内容，请阅读

references/

目录下的相关文件：

```
references/review-checklist.md
```
- 完整的分类审查清单，包含正确性、安全、性能、可读性、测试、文档和规范检查的详细项
```
references/context-detection.md
```
- 审查前收集项目上下文的指南：配置文件检测、框架启发式判断、规范采样、特定语言的重点领域

执行全面的多阶段审查时，请加载

references/review-checklist.md

。当项目使用不熟悉的框架或需要系统识别规范时，请加载

references/context-detection.md

。

code-review-mastery

Original

Translation

Local Diff Code Review

本地差异代码审查

When to use this skill

何时使用此技能

Key principles

核心原则

[MAJOR] vs [MINOR] definitions

[MAJOR]与[MINOR]定义

Decision rule

判定规则

The review workflow

审查工作流

Phase 1: DETECT

阶段1：检测

Phase 2: CONTEXT

阶段2：上下文收集

Phase 3: ANALYZE

阶段3：分析

Phase 4: REPORT

阶段4：报告

The review pyramid

审查金字塔

Analysis passes

分析检查步骤

Security (all [MAJOR])

安全（全部标记为[MAJOR]）

Correctness (mostly [MAJOR])

正确性（大多标记为[MAJOR]）

Performance ([MAJOR] if in hot path, [MINOR] otherwise)

性能（热点路径标记为[MAJOR]，否则为[MINOR]）

Design ([MINOR] unless architectural)

设计（除非涉及架构，否则标记为[MINOR]）

Readability ([MINOR])

可读性（标记为[MINOR]）

Convention ([MAJOR] if explicit rule, [MINOR] if implicit pattern)

规范（违反明确规则标记为[MAJOR]，违反隐含模式标记为[MINOR]）

Testing ([MAJOR] for missing tests)

测试（缺失测试标记为[MAJOR]）

Output format specification

输出格式规范

Code Review: [staged|unstaged] changes

代码审查：[暂存/未暂存]变更

[MAJOR] Issues (N)

[MAJOR] 问题（N个）

[MINOR] Suggestions (N)

[MINOR] 建议（N个）

Summary

总结

Handling special cases

特殊场景处理

Anti-patterns

反模式

References

参考资料

Related skills

相关技能

`[MAJOR]`
与
`[MINOR]`
定义

Security (all
`[MAJOR]`
)

安全（全部标记为
`[MAJOR]`
）

Correctness (mostly
`[MAJOR]`
)

正确性（大多标记为
`[MAJOR]`
）

Performance (
`[MAJOR]`
if in hot path,
`[MINOR]`
otherwise)

性能（热点路径标记为
`[MAJOR]`
，否则为
`[MINOR]`
）

Design (
`[MINOR]`
unless architectural)

设计（除非涉及架构，否则标记为
`[MINOR]`
）

Readability (
`[MINOR]`
)

可读性（标记为
`[MINOR]`
）

Convention (
`[MAJOR]`
if explicit rule,
`[MINOR]`
if implicit pattern)

规范（违反明确规则标记为
`[MAJOR]`
，违反隐含模式标记为
`[MINOR]`
）

Testing (
`[MAJOR]`
for missing tests)

测试（缺失测试标记为
`[MAJOR]`
）