Back to Details

code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Review Skill

代码评审技能

Provides a systematic approach to conducting code reviews. Focuses on the review process and quality dimensions, not technology-specific patterns.
提供一套系统化的代码评审方法。 重点关注评审流程和质量维度，而非特定技术的模式。

Name

名称

han-core:code-review - Code review a pull request
han-core:code-review - 对Pull Request进行代码评审

Synopsis

概要

/code-review [arguments]
/code-review [arguments]

Scope

适用范围

Use this skill to:
  • Conduct systematic code reviews using a structured process
  • Evaluate code across multiple dimensions (correctness, safety, maintainability)
  • Provide constructive feedback with clear, actionable recommendations
  • Determine approval readiness based on quality standards
使用本技能可以：
  • 遵循结构化流程开展系统化代码评审
  • 从多个维度评估代码（正确性、安全性、可维护性）
  • 提供具有明确可操作建议的建设性反馈
  • 基于质量标准判断是否具备批准条件

NOT for

不适用场景

  • Technology-specific patterns (see appropriate language/framework plugins)
  • Detailed implementation guidance (see discipline-specific agents)
  • 特定技术模式相关内容（请查看对应语言/框架插件）
  • 详细实现指导（请查看特定领域的Agent）

Implementation

实施步骤

Provide a code review for the given pull request.
To do this, follow these steps precisely:
  1. Use a Haiku agent to check if the pull request (a) is closed, (b) is a draft, (c) does not need a code review (eg. because it is an automated pull request, or is very simple and obviously ok), (d) already has a code review from you from earlier, OR (e) is too large (>1000 lines changed) and should be split. If any of these conditions are true, do not proceed.
  2. Use another Haiku agent to give you a list of file paths to (but not the contents of) any relevant CLAUDE.md files from the codebase: the root CLAUDE.md file (if one exists), as well as any CLAUDE.md files in the directories whose files the pull request modified
  3. Use a Haiku agent to view the pull request, and ask the agent to return a summary of the change
  4. Then, launch 5 parallel Sonnet agents to independently code review the change. The agents should work independently without seeing other agents' findings, then return a list of issues and the reason each issue was flagged (eg. CLAUDE.md adherence, bug, historical git context, etc.): a. Agent #1: Audit the changes to make sure they comply with the CLAUDE.md. Note that CLAUDE.md is guidance for Claude as it writes code, so not all instructions will be applicable during code review. b. Agent #2: Read the file changes in the pull request, then do a shallow scan for obvious bugs. Avoid reading extra context beyond the changes, focusing just on the changes themselves. Focus on large bugs, and avoid small issues and nitpicks. Ignore likely false positives. c. Agent #3: Read the git blame and history of the code modified, to identify any bugs in light of that historical context d. Agent #4: Read previous pull requests that touched these files, and check for any comments on those pull requests that may also apply to the current pull request. e. Agent #5: Read code comments in the modified files, and make sure the changes in the pull request comply with any guidance in the comments.
    IMPORTANT: After all 5 agents complete, verify their work using proof-of-work principles:
    • Check each agent's output isn't empty or generic
    • Verify issue descriptions include specific file paths and line numbers
    • Confirm agents didn't all return "no issues found" without actual analysis
    • If verification fails for any agent, note it but proceed with verified results
  5. Deduplicate and score issues: a. First, deduplicate issues from step 4:
    • Group issues by file path and line range (issues within +/-3 lines are considered duplicates)
    • For each group, combine similar descriptions and keep the most detailed version
    • Merge reasoning from all agents that found the same issue
    b. Then, for each unique issue, launch a parallel Haiku agent that takes the PR, issue description, and list of CLAUDE.md files (from step 2), and returns a score to indicate the agent's level of confidence for whether the issue is real or false positive. To do that, the agent should score each issue on a scale from 0-100, indicating its level of confidence. For issues that were flagged due to CLAUDE.md instructions, the agent should double check that the CLAUDE.md actually calls out that issue specifically. The scale is (give this rubric to the agent verbatim):
    • 0: Not confident at all. This is a false positive that doesn't stand up to light scrutiny, or is a pre-existing issue.
    • 25: Somewhat confident. This might be a real issue, but may also be a false positive. The agent wasn't able to verify that it's a real issue. If the issue is stylistic, it is one that was not explicitly called out in the relevant CLAUDE.md.
    • 50: Moderately confident. The agent was able to verify this is a real issue, but it might be a nitpick or not happen very often in practice. Relative to the rest of the PR, it's not very important.
    • 75: Highly confident. The agent double checked the issue, and verified that it is very likely it is a real issue that will be hit in practice. The existing approach in the PR is insufficient. The issue is very important and will directly impact the code's functionality, or it is an issue that is directly mentioned in the relevant CLAUDE.md.
    • 100: Absolutely certain. The agent double checked the issue, and confirmed that it is definitely a real issue, that will happen frequently in practice. The evidence directly confirms this.
  6. Filter out any issues with a score less than 80. If there are no issues that meet this criteria, do not proceed.
  7. Use a Haiku agent to repeat the eligibility check from #1, to make sure that the pull request is still eligible for code review.
  8. Finally, use the gh bash command to comment back on the pull request with the result. When writing your comment, keep in mind to: a. Keep your output brief b. Avoid emojis c. Link and cite relevant code, files, and URLs
Examples of false positives, for steps 4 and 5:
  • Pre-existing issues
  • Something that looks like a bug but is not actually a bug
  • Pedantic nitpicks that a senior engineer wouldn't call out
  • Issues that a linter, typechecker, or compiler would catch (eg. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself -- it is safe to assume that they will be run separately as part of CI.
  • General code quality issues (eg. lack of test coverage, general security issues, poor documentation), unless explicitly required in CLAUDE.md
  • Issues that are called out in CLAUDE.md, but explicitly silenced in the code (eg. due to a lint ignore comment)
  • Changes in functionality that are likely intentional or are directly related to the broader change
  • Real issues, but on lines that the user did not modify in their pull request
Notes:
  • Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
  • Use 
    gh
    to interact with Github (eg. to fetch a pull request, or to create inline comments), rather than web fetch
  • Use TaskCreate to track progress through steps 1-8
  • You must cite and link each bug (eg. if referring to a CLAUDE.md, you must link it)
为给定的Pull Request提供代码评审。
请严格遵循以下步骤操作：
  1. 使用Haiku Agent检查Pull Request是否满足以下任一情况：(a) 已关闭，(b) 为草稿状态，(c) 无需代码评审（例如自动生成的Pull Request，或非常简单且明显无问题的请求），(d) 你之前已对其进行过代码评审，(e) 改动过大（超过1000行）需要拆分。如果满足任一情况，请勿继续。
  2. 使用另一个Haiku Agent获取代码库中所有相关CLAUDE.md文件的文件路径（不包含内容）：包括根目录下的CLAUDE.md（如果存在），以及Pull Request改动文件所在目录中的所有CLAUDE.md文件
  3. 使用Haiku Agent查看Pull Request，并让该Agent返回改动内容的摘要
  4. 启动5个并行的Sonnet Agent，独立对改动内容进行代码评审。这些Agent应独立工作，不查看其他Agent的发现，之后返回问题列表及每个问题的标记原因（例如是否符合CLAUDE.md、是否为Bug、Git历史上下文等）： a. Agent #1：审核改动内容是否符合CLAUDE.md的要求。注意CLAUDE.md是为Claude编写代码提供的指导，并非所有指令都适用于代码评审。 b. Agent #2：读取Pull Request中的文件改动，快速扫描明显的Bug。避免查看改动之外的额外上下文，仅关注改动本身。重点排查严重Bug，忽略小问题和吹毛求疵的细节，排除可能的误报。 c. Agent #3：读取被改动代码的Git blame和历史记录，结合历史上下文识别Bug d. Agent #4：查看之前修改过这些文件的Pull Request，检查其中的评论是否也适用于当前Pull Request e. Agent #5：读取被改动文件中的代码注释，确保Pull Request中的改动符合注释中的指导要求
    重要提示：所有5个Agent完成工作后，使用工作量证明原则验证它们的工作：
    • 检查每个Agent的输出是否为空或过于笼统
    • 验证问题描述是否包含具体的文件路径和行号
    • 确认所有Agent不会在未进行实际分析的情况下都返回“未发现问题”
    • 如果任一Agent的验证未通过，记录该情况但继续使用验证通过的结果
  5. 去重并为问题打分： a. 首先，对步骤4中的问题进行去重：
    • 按文件路径和行范围对问题进行分组（相差±3行以内的问题视为重复）
    • 对每个分组，合并相似的描述并保留最详细的版本
    • 合并所有发现同一问题的Agent的推理依据
    b. 然后，针对每个唯一问题，启动并行的Haiku Agent，传入Pull Request、问题描述和步骤2中获取的CLAUDE.md文件列表，返回一个分数表示该Agent对问题是否为真实问题或误报的置信度。Agent应采用0-100的评分标准，具体评分规则如下（请将此规则原封不动地提供给Agent）：
    • 0：完全不置信。这是经不起推敲的误报，或是预先存在的问题。
    • 25：有些置信。这可能是真实问题，但也可能是误报。Agent无法验证其为真实问题。如果是风格类问题，且相关CLAUDE.md中未明确提及。
    • 50：中等置信。Agent能够验证这是真实问题，但可能是无关紧要的小问题，或在实际中很少出现。相对于整个Pull Request而言，它并不重要。
    • 75：高度置信。Agent已再次检查该问题，确认其很可能是会在实际中出现的真实问题。Pull Request中的现有处理方式存在不足。该问题非常重要，会直接影响代码功能，或是相关CLAUDE.md中明确提及的问题。
    • 100：绝对确定。Agent已再次检查该问题，确认其肯定是会在实际中频繁出现的真实问题，有直接证据可以证明。
  6. 过滤掉分数低于80的问题。如果没有符合条件的问题，请勿继续。
  7. 使用Haiku Agent重复步骤1中的资格检查，确保Pull Request仍然符合代码评审的条件。
  8. 最后，使用gh bash命令在Pull Request上回复评审结果。撰写评论时请注意： a. 内容简洁 b. 避免使用表情符号 c. 链接并引用相关代码、文件和URL
步骤4和5中的误报示例：
  • 预先存在的问题
  • 看似Bug但实际不是Bug的情况
  • 资深工程师不会指出的吹毛求疵的细节
  • 可以由Linter、类型检查器或编译器发现的问题（例如缺失或错误的导入、类型错误、测试失败、格式问题、诸如换行之类的繁琐风格问题）。无需自行运行这些构建步骤——可以假设它们会作为CI的一部分单独运行。
  • 一般代码质量问题（例如缺乏测试覆盖率、一般性安全问题、文档不完善），除非CLAUDE.md中有明确要求
  • CLAUDE.md中提及但代码中明确禁用的问题（例如由于lint忽略注释）
  • 可能是有意为之或与更广泛改动直接相关的功能变更
  • 真实问题，但出现在用户未改动的代码行上
注意事项：
  • 不要检查构建信号，也不要尝试构建或类型检查应用。这些会单独运行，与你的代码评审无关。
  • 使用
    gh
    与Github交互（例如获取Pull Request或创建行内评论），而非网页请求
  • 使用TaskCreate跟踪步骤1-8的进度
  • 必须引用并链接每个Bug（例如提及CLAUDE.md时，必须链接到它）

Review Process Overview

评审流程概述

Phase 1: Pre-Review Preparation

阶段1：评审前准备

Before starting review, gather context

开始评审前，收集上下文信息

  1. Understand the change:
    bash
    # Review the diff
git diff <base-branch>...HEAD

# Check scope of changes
git diff --stat <base-branch>...HEAD
  2. Identify relevant context:
    bash
    # Find similar patterns in codebase
grep -r "similar_pattern" .
  3. Verify business context:
    • Is there a related issue/ticket? Review requirements
    • What domain is impacted?
    • What's the user-facing impact?
  1. 理解改动内容：
    bash
    # 查看差异
git diff <base-branch>...HEAD

# 检查改动范围
git diff --stat <base-branch>...HEAD
  2. 识别相关上下文：
    bash
    # 在代码库中查找相似模式
grep -r "similar_pattern" .
  3. 验证业务上下文：
    • 是否有相关的Issue/工单？查看需求
    • 影响了哪些业务领域？
    • 对用户有什么影响？

Phase 2: Systematic Review

阶段2：系统化评审

Review across these dimensions

从以下维度进行评审

1. Correctness

1. 正确性

  • Does it solve the stated problem?
  • Does business logic align with domain rules?
  • Are edge cases handled appropriately?
  • Do tests verify the expected behavior?
  • 是否解决了所述问题？
  • 业务逻辑是否符合领域规则？
  • 是否妥善处理了边缘情况？
  • 测试是否验证了预期行为？

Check correctness by

如何检查正确性

  • Reading tests first to understand intended behavior
  • Tracing code paths through the change
  • Verifying error scenarios are covered
  • Cross-referencing with requirements
  • 先阅读测试以理解预期行为
  • 跟踪改动中的代码路径
  • 验证错误场景是否被覆盖
  • 与需求进行交叉核对

2. Safety

2. 安全性

  • Does it follow authorization/authentication patterns?
  • Are there breaking changes to APIs or contracts?
  • Could this expose sensitive data?
  • Are data operations safe?
  • Are there potential race conditions or data integrity issues?
  • 是否遵循授权/认证模式？
  • 是否存在对API或契约的破坏性改动？
  • 是否可能暴露敏感数据？
  • 数据操作是否安全？
  • 是否存在潜在的竞态条件或数据完整性问题？

Check safety by

如何检查安全性

  • Verifying access control on operations
  • Running compatibility checks for API changes
  • Checking for proper input validation
  • Reviewing transaction boundaries
  • Validating input sanitization
  • 验证操作的访问控制
  • 对API改动进行兼容性检查
  • 检查是否有适当的输入验证
  • 审查事务边界
  • 验证输入是否经过清理

3. Maintainability

3. 可维护性

  • Does it follow existing codebase patterns?
  • Is the code readable and understandable?
  • Are complex areas documented?
  • Does it follow the Boy Scout Rule? (leaves code better than found)
  • Is naming clear and consistent?
  • 是否遵循代码库中的现有模式？
  • 代码是否可读、易懂？
  • 复杂区域是否有文档说明？
  • 是否遵循童子军规则？（让代码比你接手时更优秀）
  • 命名是否清晰、一致？

Check maintainability by

如何检查可维护性

  • Comparing with similar code in codebase
  • Verifying documentation on complex logic
  • Checking for magic numbers and hard-coded values
  • Ensuring consistent naming conventions
  • Looking for commented-out code (anti-pattern)
  • 与代码库中的相似代码进行比较
  • 验证复杂逻辑是否有文档说明
  • 检查是否存在魔术数字和硬编码值
  • 确保命名约定一致
  • 查找被注释掉的代码（反模式）

4. Testability

4. 可测试性

  • Are there tests for new functionality?
  • Do tests cover edge cases and error scenarios?
  • Are tests clear and maintainable?
  • Is test data setup appropriate?
  • 新功能是否有对应的测试？
  • 测试是否覆盖了边缘情况和错误场景？
  • 测试是否清晰、易于维护？
  • 测试数据的设置是否合适？

Check testability by

如何检查可测试性

  • Reviewing test coverage of changed code
  • Verifying both happy and sad paths are tested
  • Ensuring tests are deterministic and clear
  • Checking for proper test isolation
  • 审查改动代码的测试覆盖率
  • 验证是否同时测试了正常路径和异常路径
  • 确保测试是确定性的、清晰的
  • 检查是否有适当的测试隔离

5. Performance

5. 性能

  • Are there obvious performance issues?
  • Are database queries efficient?
  • Are expensive operations properly optimized?
  • Are resources properly managed?
  • 是否存在明显的性能问题？
  • 数据库查询是否高效？
  • 昂贵的操作是否经过适当优化？
  • 资源是否得到妥善管理？

Check performance by

如何检查性能

  • Identifying N+1 query patterns
  • Checking for missing indexes on queries
  • Reviewing resource allocation and cleanup
  • Verifying appropriate data structures
  • 识别N+1查询模式
  • 检查查询是否缺少索引
  • 审查资源分配和清理情况
  • 验证是否使用了合适的数据结构

6. Standards Compliance

6. 标准合规性

  • Does it follow language-specific best practices?
  • Does it pass all verification checks?
  • Are there linting or type errors?
  • Does it follow agreed coding standards?
  • 是否遵循特定语言的最佳实践？
  • 是否通过了所有验证检查？
  • 是否存在Linting或类型错误？
  • 是否遵循已约定的编码标准？

Check standards compliance by

如何检查标准合规性

  • Running verification suite
  • Checking for standard pattern violations
  • Verifying no bypasses of quality gates
  • 运行验证套件
  • 检查是否违反标准模式
  • 验证是否绕过了质量门控

Phase 3: Confidence Scoring

阶段3：置信度评分

Apply confidence scoring to all findings

为所有发现的问题应用置信度评分

Each identified issue must include a confidence score (0-100) indicating how certain you are that it's a genuine problem:
ScoreConfidence LevelWhen to Use
100Absolutely certainObjective facts: linter errors, type errors, failing tests, security vulnerabilities
90Very high confidenceClear violations of documented standards, obvious correctness bugs
80High confidencePattern violations, missing error handling, maintainability issues
70Moderately confidentPotential issues that need context, possible edge cases
60Somewhat confidentQuestionable patterns, style concerns with codebase precedent
50UncertainPotential improvements without clear precedent
<50Low confidenceSpeculative concerns, personal preferences
CRITICAL FILTERING RULE: Only report issues with confidence >= 80%. Lower-confidence findings create noise and should be omitted.
每个识别出的问题都必须包含置信度评分（0-100），表示你对其为真实问题的确定程度：
分数置信度等级使用场景
100绝对确定客观事实：Linter错误、类型错误、测试失败、安全漏洞
90极高置信度明显违反文档化标准、明显的正确性Bug
80高置信度模式违反、缺失错误处理、可维护性问题
70中等置信度需要上下文信息的潜在问题、可能的边缘情况
60有些置信度有问题的模式、有代码库先例的风格问题
50不确定没有明确先例的潜在改进
<50低置信度推测性问题、个人偏好
关键过滤规则：仅报告置信度**≥80%**的问题。低置信度的发现会产生噪音，应予以忽略。

Confidence Scoring Guidelines

置信度评分指南

High Confidence (90-100) - Report these:
  • Verification failures (linting, tests, types)
  • Security vulnerabilities (SQL injection, XSS, auth bypass)
  • Correctness bugs with clear reproduction
  • Breaking API changes
  • Violations of documented team standards
Medium-High Confidence (80-89) - Report these:
  • Missing tests for new functionality
  • Error handling gaps
  • Performance issues (N+1 queries, missing indexes)
  • Maintainability concerns with clear patterns
  • Boy Scout Rule violations
Medium Confidence (60-79) - DO NOT REPORT:
  • Style preferences without clear codebase precedent
  • Speculative performance concerns
  • Alternative approaches without clear benefit
Low Confidence (<60) - DO NOT REPORT:
  • Personal opinions
  • "Could be better" without specific impact
  • Theoretical edge cases without evidence
高置信度（90-100） - 应报告：
  • 验证失败（Linting、测试、类型检查）
  • 安全漏洞（SQL注入、XSS、认证绕过）
  • 有明确复现步骤的正确性Bug
  • 破坏性API改动
  • 违反文档化团队标准的情况
中高置信度（80-89） - 应报告：
  • 新功能缺失测试
  • 错误处理存在漏洞
  • 性能问题（N+1查询、缺失索引）
  • 有明确模式的可维护性问题
  • 违反童子军规则的情况
中等置信度（60-79） - 请勿报告：
  • 没有明确代码库先例的风格偏好
  • 推测性性能问题
  • 没有明确优势的替代方案
低置信度（<60） - 请勿报告：
  • 个人观点
  • 没有具体影响的“可以更好”的建议
  • 没有证据的理论边缘情况

False Positive Filtering

误报过滤

CRITICAL: Apply these filters to avoid reporting non-issues:
DO NOT REPORT:
  • Pre-existing issues not introduced by this change (check git blame)
  • Issues already handled by linters/formatters
  • Code with explicit lint-ignore comments (respect developer decisions)
  • Style preferences without documented standards
  • Theoretical bugs without evidence or reproduction
  • "Could use" suggestions without clear benefit
  • Pedantic nitpicks that don't affect quality
VERIFY BEFORE REPORTING:
  • Run 
    git diff
    to confirm issue is in changed lines
  • Check if automated tools already catch this
  • Verify against documented project standards (CLAUDE.md, CONTRIBUTING.md, etc.)
  • Confirm the issue actually impacts correctness, safety, or maintainability
Example of False Positive vs. Genuine Issue:
False Positive: "This function could use TypeScript generics for better type safety" (confidence: 60%, style preference, no documented standard)
Genuine Issue: "Function 
processPayment
at 
services/payment.ts:42
performs database operation without transaction protection, risking data inconsistency if an error occurs mid-operation." (confidence: 90%, documented pattern violation, clear impact)
关键：应用以下过滤器以避免报告非问题：
请勿报告：
  • 并非本次改动引入的预先存在的问题（检查git blame）
  • 已由Linters/格式化工具处理的问题
  • 带有明确lint忽略注释的代码（尊重开发者的决定）
  • 没有文档化标准的风格偏好
  • 没有证据或复现步骤的理论Bug
  • 没有明确优势的“可以使用”的建议
  • 不影响质量的吹毛求疵的细节
报告前请验证：
  • 运行
    git diff
    确认问题出现在改动的代码行中
  • 检查自动化工具是否已发现该问题
  • 对照文档化的项目标准（CLAUDE.md、CONTRIBUTING.md等）进行验证
  • 确认问题确实影响正确性、安全性或可维护性

Phase 4: Feedback & Decision

误报与真实问题示例

Provide structured feedback

—
  1. Summary: High-level assessment
  2. Strengths: What's done well (positive reinforcement)
  3. Issues: Organized by severity with confidence scores:
    • Critical (confidence >= 90): Blocks approval (security, correctness, breaking changes)
    • Important (confidence >= 80): Should be addressed (maintainability, best practices)
  4. Actionable next steps: Specific changes with file:line references
  5. Decision: Approve, Request Changes, or Needs Discussion
Note: Suggestions/nice-to-haves are intentionally omitted. Focus only on high-confidence, actionable feedback.
误报：“这个函数可以使用TypeScript泛型来提升类型安全性”（置信度：60%，风格偏好，无文档化标准）
真实问题：“
services/payment.ts:42
处的
processPayment
函数在未使用事务保护的情况下执行数据库操作，如果操作中途发生错误，可能会导致数据不一致。请将该操作包裹在事务中以确保原子性。参考数据库设计的ACID原则。”（置信度：90%，违反文档化模式，影响明确）

Approval Criteria

阶段4：反馈与决策

Approve When

提供结构化反馈

  • All verification checks pass (linting, tests, types, etc.)
  • Business logic is correct and complete
  • Security and authorization patterns followed
  • No breaking changes (or properly coordinated)
  • Code follows existing patterns
  • Complex logic has clear documentation
  • Tests cover happy paths, edge cases, and error scenarios
  • Changes align with requirements
  • Code is maintainable and clear
  • Boy Scout Rule applied (code improved, not degraded)
  1. 摘要：高层次评估
  2. 优点：做得好的地方（积极反馈）
  3. 问题：按严重程度组织，并标注置信度评分：
    • 严重（置信度≥90）：阻碍批准（安全、正确性、破坏性改动）
    • 重要（置信度≥80）：需要解决（可维护性、最佳实践）
  4. 可操作的下一步：带有文件:行号引用的具体改动建议
  5. 决策：批准、请求改动或需要讨论
注意：有意省略建议/锦上添花的内容。仅关注高置信度、可操作的反馈。

Request Changes When

批准标准

—

可批准的情况

  • Critical issues: Security holes, correctness bugs, breaking changes
  • Important issues: Pattern violations, missing tests, unclear code
  • Verification failures not addressed
  • Business logic doesn't match requirements
  • Insufficient error handling
  • 所有验证检查通过（Linting、测试、类型检查等）
  • 业务逻辑正确且完整
  • 遵循安全和授权模式
  • 无破坏性改动（或已妥善协调）
  • 代码遵循现有模式
  • 复杂逻辑有清晰的文档说明
  • 测试覆盖了正常路径、边缘情况和错误场景
  • 改动符合需求
  • 代码可维护且清晰
  • 遵循童子军规则（代码得到改进，而非退化）

Needs Discussion When

需要请求改动的情况

  • Architectural concerns
  • Unclear requirements
  • Trade-off decisions needed
  • Pattern deviation requires justification
  • Performance implications uncertain
  • 严重问题：安全漏洞、正确性Bug、破坏性改动
  • 重要问题：违反模式、缺失测试、代码不清晰
  • 未解决验证失败问题
  • 业务逻辑不符合需求
  • 错误处理不足

Common Review Pitfalls

需要讨论的情况

Reviewers often miss

—
  1. Authorization bypasses: Operations without proper access control
  2. Breaking changes: Not checking compatibility
  3. Error handling gaps: Only reviewing happy paths
  4. Test quality: Tests exist but don't actually test edge cases
  5. Domain logic errors: Not understanding business rules
  6. Commented-out code: Leaving dead code instead of removing
  7. Magic numbers: Unexplained constants without names
  8. Over-clever code: Complex when simple would work
  9. Boy Scout Rule violations: Making code worse, not better
  • 架构问题
  • 需求不明确
  • 需要进行权衡决策
  • 偏离模式需要理由说明
  • 性能影响不确定

Red Flags (Never Approve)

常见评审陷阱

These always require changes

评审者常忽略的问题

  • Commented-out code -> Remove it (git preserves history)
  • Secrets or credentials in code -> Use secure configuration
  • Breaking changes without compatibility verification
  • Tests commented out or skipped -> Fix code, not tests
  • Verification failures ignored -> Must all pass
  • No tests for new functionality -> Tests are required
  • Hard-coded business logic -> Should be configurable
  • Error handling missing -> Must handle edge cases
  • Obvious security vulnerabilities -> Must fix immediately
  1. 授权绕过：未进行适当访问控制的操作
  2. 破坏性改动：未检查兼容性
  3. 错误处理漏洞：仅评审正常路径
  4. 测试质量：存在测试但未覆盖边缘情况
  5. 领域逻辑错误：不理解业务规则
  6. 被注释掉的代码：保留死代码而非删除
  7. 魔术数字：未命名的不明常量
  8. 过度复杂的代码：能用简单实现却用了复杂方式
  9. 违反童子军规则：让代码变得更糟，而非更好

Integration with Development Workflow

危险信号（绝不能批准）

Code review fits in Phase 2: Implementation

这些情况始终需要改动

text
Implementation -> Verification Suite -> Code Review -> Approval -> Merge
                 (automated checks)   (this skill)    (human)
  • 被注释掉的代码 -> 删除它（git会保留历史记录）
  • 代码中包含密钥或凭证 -> 使用安全配置
  • 未进行兼容性验证的破坏性改动
  • 被注释掉或跳过的测试 -> 修复代码，而非测试
  • 忽略验证失败 -> 必须全部通过
  • 新功能没有测试 -> 必须有测试
  • 硬编码业务逻辑 -> 应可配置
  • 缺失错误处理 -> 必须处理边缘情况
  • 明显的安全漏洞 -> 必须立即修复

Review happens AFTER verification

与开发工作流的集成

—

代码评审属于阶段2：实现

  1. Developer runs verification suite
  2. ALL automated checks must pass
  3. Code review skill applied for quality assessment
  4. Issues identified and fixed
  5. Re-verify after fixes
  6. Human reviews and approves for merge
Review is NOT a substitute for verification. Both are required.
text
实现 -> 验证套件 -> 代码评审 -> 批准 -> 合并
                 (自动化检查)   (本技能)    (人工)

Output Format

评审在验证之后进行

For your final comment, follow the following format precisely (assuming for this example that you found 3 issues):
  1. 开发者运行验证套件
  2. 所有自动化检查必须通过
  3. 应用代码评审技能进行质量评估
  4. 识别并修复问题
  5. 修复后重新验证
  6. 人工评审并批准合并
评审不能替代验证。两者都是必需的。

Code review

输出格式

Found 3 issues:
  1. <brief description of bug> (CLAUDE.md says "<...>")
<link to file and line with full sha1 + line range for context, note that you MUST provide the full sha and not use bash here, eg. https://github.com/anthropics/claude-code/blob/1d54823877c4de72b2316a64032a54afc404e619/README.md#L13-L17>
  1. <brief description of bug> (some/other/CLAUDE.md says "<...>")
<link to file and line with full sha1 + line range for context>
  1. <brief description of bug> (bug due to <file and code snippet>)
<link to file and line with full sha1 + line range for context>
Generated with Claude Code
<sub>- If this code review was useful, please react with thumbs up. Otherwise, react with thumbs down.</sub>
  • Or, if you found no issues:
最终评论请严格遵循以下格式（假设发现了3个问题）：

Code review

代码评审

No issues found. Checked for bugs and CLAUDE.md compliance.
Generated with Claude Code
  • When linking to code, follow the following format precisely, otherwise the Markdown preview won't render correctly: https://github.com/anthropics/claude-cli-internal/blob/c21d3c10bc8e898b7ac1a2d745bdc9bc4e423afe/package.json#L10-L15
    • Requires full git sha
    • You must provide the full sha. Commands like 
      https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar
      will not work, since your comment will be directly rendered in Markdown.
    • Repo name must match the repo you're code reviewing
    • #
      sign after the file name
    • Line range format is L[start]-L[end]
    • Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if you are commenting about lines 5-6, you should link to 
      L4-7
      )
发现3个问题：
  1. <Bug的简要描述>（CLAUDE.md中提到："<...>"）
<链接到文件和行号，包含完整sha1和行范围以提供上下文，注意必须提供完整sha，不能使用bash命令，例如https://github.com/anthropics/claude-code/blob/1d54823877c4de72b2316a64032a54afc404e619/README.md#L13-L17>
  1. <Bug的简要描述>（some/other/CLAUDE.md中提到："<...>"）
<链接到文件和行号，包含完整sha1和行范围以提供上下文>
  1. <Bug的简要描述>（Bug原因：<文件和代码片段>）
<链接到文件和行号，包含完整sha1和行范围以提供上下文>
由Claude Code生成
<sub>- 如果本次代码评审对你有帮助，请点赞；否则请点踩。</sub>
  • 如果未发现问题：

Constructive Feedback Principles

代码评审

When providing feedback

—
  1. Be specific: Point to exact lines, not vague areas
  2. Explain why: Don't just say "this is wrong," explain the impact
  3. Provide direction: Suggest approaches or patterns
  4. Balance critique with praise: Note what's done well
  5. Prioritize issues: Critical vs. important vs. suggestions
  6. Be respectful: Code is not the person
  7. Assume competence: Ask questions, don't accuse
  8. Teach, don't just correct: Help developers grow
未发现问题。已检查Bug和CLAUDE.md合规性。
由Claude Code生成
  • 链接代码时，请严格遵循以下格式，否则Markdown预览将无法正确渲染：https://github.com/anthropics/claude-cli-internal/blob/c21d3c10bc8e898b7ac1a2d745bdc9bc4e423afe/package.json#L10-L15
    • 需要完整的git sha
    • 必须提供完整sha。诸如
      https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar
      的命令将无效，因为你的评论会直接以Markdown渲染。
    • 仓库名称必须与你正在评审的仓库一致
    • 文件名后加
      #
      号
    • 行范围格式为L[起始行]-L[结束行]
    • 至少提供目标行前后各1行的上下文，以目标行为中心（例如评论第5-6行时，应链接到
      L4-7
      ）

Example of constructive feedback

建设性反馈原则

—

提供反馈时

Good: "In 
services/payment_service:45
, processing payments without transaction protection could lead to data inconsistency if an error occurs mid-operation. Wrap the operation in a transaction to ensure atomicity. Consider the ACID principles from database design."
Bad: "Use transactions here."
  1. 具体明确：指向确切的行号，而非模糊的区域
  2. 解释原因：不要只说“这是错的”，要解释影响
  3. 提供方向：建议处理方法或模式
  4. 平衡批评与表扬：指出做得好的地方
  5. 优先处理问题：严重问题 > 重要问题 > 建议
  6. 保持尊重：针对代码而非个人
  7. 假设能力：提出问题，而非指责
  8. 传授知识：不仅纠正，还要帮助开发者成长

Quality Philosophy

建设性反馈示例

Code review ensures

—
  • Correctness: Solves the actual problem
  • Safety: Protects data and follows security patterns
  • Maintainability: Future developers can understand and modify
  • Consistency: Follows established patterns
  • Quality: Meets standards
好：“在
services/payment_service:45
处，处理支付时未使用事务保护，如果操作中途发生错误，可能会导致数据不一致。请将该操作包裹在事务中以确保原子性。参考数据库设计的ACID原则。”
差：“这里要用事务。”

Remember

质量理念

—

代码评审确保

  • Reviews are about code quality, not personal critique
  • Goal is to improve code AND developer skills
  • Balance thoroughness with pragmatism
  • Perfection is not the standard; "good enough" that meets quality bar is
  • Boy Scout Rule: Leave code better than you found it
  • 正确性：解决实际问题
  • 安全性：保护数据并遵循安全模式
  • 可维护性：未来开发者可以理解和修改
  • 一致性：遵循已建立的模式
  • 质量：符合标准
—

请记住

—
  • 评审关注的是代码质量，而非个人批评
  • 目标是提升代码质量和开发者技能
  • 在彻底性和务实性之间取得平衡
  • 完美不是标准；达到质量要求的“足够好”即可
  • 童子军规则：让代码比你接手时更优秀