Back to Details

code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Review Skill

代码评审Skill

File paths: All 
references/
and 
scripts/
paths in this skill resolve under 
~/.agents/skills/code-review/
. Do not look for them in the current working directory.
文件路径：本Skill中所有
references/
和
scripts/
路径均指向
~/.agents/skills/code-review/
目录下的文件。请勿在当前工作目录中查找这些文件。

Overview

概述

Perform expert-level code review focusing on security vulnerabilities, correctness, performance implications, and maintainability. Support multiple languages and ecosystems including TypeScript, React, Node.js, Python, Bash, Solidity, and Solana. Apply industry best practices, security standards, and language-specific idioms. Prioritize findings by severity and provide actionable recommendations with evidence-based reasoning. Keep reviews thorough yet pragmatic, distinguishing between critical issues requiring immediate attention and minor improvements that can be addressed later.
执行专业级别的代码评审，重点关注安全漏洞、正确性、性能影响和可维护性。支持多种语言和生态系统，包括TypeScript、React、Node.js、Python、Bash、Solidity和Solana。应用行业最佳实践、安全标准和特定语言的惯用写法。按严重程度优先处理发现的问题，并提供基于证据的可操作建议。评审既要全面又要务实，区分需要立即关注的关键问题和可后续处理的微小改进。

Review Workflow

评审工作流

Before starting: Verify you're in a git repository by running 
git rev-parse --git-dir
. If this fails (exit code 128), inform the user they must run the code review from within a git repository and stop.
Parse arguments from 
$ARGUMENTS
:
  • --fix
    : After presenting findings, automatically apply all suggested fixes without waiting for confirmation. Implement fixes in severity order (CRITICAL → HIGH → MEDIUM → LOW), then report what was changed.
  • Default (no 
    --fix
    ): Present findings and wait for user confirmation before applying changes.
Determine which files to review:
  • If 
    $ARGUMENTS
    contains file paths, patterns, or 
    --all
    , use them. 
    --all
    means uncommitted changes via 
    git diff --name-only --diff-filter=ACMR
    .
  • Otherwise, default to session-modified files (files edited in this chat session).
  • If no session edits exist and no explicit scope was given, inform the user and stop. Do not silently widen scope.
Run 
git diff
on the in-scope files to understand the changes. Examine both the changed lines and surrounding context to understand intent. Identify file types being modified: application code, test files, configuration, database migrations, or documentation.
Assess risk level based on change scope and type. High-risk areas include authentication logic, authorization checks, payment processing, data persistence, external API integrations, and cryptographic operations.
Apply appropriate review strategies per file type. Application code requires deep analysis of logic, error handling, and security. Configuration files need validation of limits, timeouts, and environment-specific values. Test files should verify coverage of edge cases and error scenarios.
开始前：通过运行
git rev-parse --git-dir
验证是否处于git仓库中。如果命令失败（退出码128），告知用户必须在git仓库内执行代码评审并停止操作。
从
$ARGUMENTS
中解析参数：
  • --fix
    ：在展示发现的问题后，自动应用所有建议的修复，无需等待确认。按照严重程度顺序（CRITICAL → HIGH → MEDIUM → LOW）实施修复，然后报告变更内容。
  • 默认（无
    --fix
    参数）：展示发现的问题，等待用户确认后再应用变更。
确定需要评审的文件：
  • 如果
    $ARGUMENTS
    中包含文件路径、匹配模式或
    --all
    ，则使用这些指定的范围。
    --all
    表示所有未提交的变更，通过
    git diff --name-only --diff-filter=ACMR
    获取。
  • 否则，默认评审会话中修改的文件（本次聊天会话中编辑的文件）。
  • 如果既没有会话编辑记录，也没有明确指定范围，告知用户并停止操作。请勿擅自扩大评审范围。
对范围内的文件运行
git diff
以了解变更内容。检查变更行及其上下文以理解代码意图。识别被修改的文件类型：应用代码、测试文件、配置文件、数据库迁移文件或文档。
根据变更范围和类型评估风险等级。高风险领域包括认证逻辑、授权检查、支付处理、数据持久化、外部API集成和加密操作。
针对不同文件类型应用相应的评审策略。应用代码需要深入分析逻辑、错误处理和安全性。配置文件需要验证限制值、超时设置和环境特定的值。测试文件应确认对边缘情况和错误场景的覆盖。

Severity Classification

严重程度分类

Categorize findings by severity to prioritize remediation efforts:
🚨 CRITICAL: Security vulnerabilities enabling unauthorized access, data exfiltration, or code execution. Data loss scenarios including unguarded deletions or destructive migrations without backups. Production outage risks from resource exhaustion, infinite loops, or unhandled exceptions in critical paths. Breaking API changes without versioning or migration paths.
⚠️ HIGH: Logic errors producing incorrect results in core functionality. Performance degradation through inefficient algorithms, N+1 queries, or missing indexes. Error handling gaps where failures cascade or leave systems in inconsistent states. Race conditions in concurrent code. Missing input validation on external data.
💡 MEDIUM: Maintainability issues including tight coupling, god objects, or violation of single responsibility principle. Missing validation on internal boundaries. Incomplete error messages hindering debugging. Code duplication suggesting need for abstraction. Missing transaction boundaries risking partial updates.
ℹ️ LOW: Style inconsistencies not enforced by linters. Documentation gaps in complex logic. Minor naming improvements. Non-critical optimizations with minimal impact.
将发现的问题按严重程度分类，以便优先处理修复工作：
🚨 CRITICAL（关键）：可能导致未授权访问、数据泄露或代码执行的安全漏洞。数据丢失场景，包括无保护的删除操作或无备份的破坏性迁移。资源耗尽、无限循环或关键路径中未处理异常导致的生产环境停机风险。未进行版本控制或提供迁移路径的破坏性API变更。
⚠️ HIGH（高）：核心功能中产生错误结果的逻辑错误。低效算法、N+1查询或缺失索引导致的性能下降。错误处理存在漏洞，导致故障扩散或系统处于不一致状态。并发代码中的竞态条件。外部数据缺失输入验证。
💡 MEDIUM（中）：可维护性问题，包括紧耦合、上帝对象或违反单一职责原则。内部边界缺失验证。不完整的错误信息，阻碍调试。代码重复，表明需要抽象。缺失事务边界，存在部分更新的风险。
ℹ️ LOW（低）：未被代码检查工具（linter）强制执行的风格不一致问题。复杂逻辑中的文档缺失。微小的命名改进。影响极小的非关键优化。

Universal Checklist

通用检查清单

Apply these language-agnostic patterns to every code review:
Security Fundamentals: Check for secrets, API keys, or credentials in code—these belong in environment variables or secure vaults. Examine all input handling for injection vulnerabilities: SQL injection, command injection, path traversal, XSS. Verify authentication checks protect sensitive operations. Confirm authorization validates resource ownership, not just authentication status. Review cryptographic usage for appropriate algorithms, key sizes, and secure random number generation.
Logic Correctness: Analyze null and undefined handling—are all code paths safe? Test boundary conditions: empty arrays, zero values, maximum sizes, negative numbers. Trace error paths to ensure failures are handled gracefully and don't expose internal details. Identify potential race conditions in concurrent code: check-then-act patterns, shared mutable state, missing synchronization. Verify loops terminate and recursion has base cases.
Performance Considerations: Evaluate algorithmic complexity—O(n²) or worse on unbounded inputs is problematic. Check resource cleanup: files closed, connections released, timers cleared, event listeners removed. Assess caching opportunities for expensive computations or external calls. Review lazy loading and pagination for large datasets. Identify synchronous operations blocking event loops or main threads.
Maintainability Standards: Assess coupling—changes should be localized, not rippling across modules. Verify single responsibility—functions and classes should have one reason to change. Check for magic numbers and strings—extract named constants. Review error messages for actionability—include context for debugging.
Naming Quality: Names should reveal intent—verb phrases for functions (
validateOrder
, not 
process
), descriptive nouns for variables (
userCount
, not 
n
), boolean prefixes (
is
, 
has
, 
can
). See 
~/.agents/skills/code-review/references/naming.md
for detailed conventions by language and common anti-patterns.
对每次代码评审应用以下与语言无关的检查项：
安全基础：检查代码中是否包含密钥、API密钥或凭证——这些应存储在环境变量或安全密钥管理服务中。检查所有输入处理是否存在注入漏洞：SQL注入、命令注入、路径遍历、XSS。验证认证检查是否保护敏感操作。确认授权机制验证资源所有权，而非仅验证认证状态。审查加密算法的使用是否恰当，包括算法选择、密钥长度和安全随机数生成。
逻辑正确性：分析空值和未定义值的处理——所有代码路径是否安全？测试边界条件：空数组、零值、最大值、负数。跟踪错误路径，确保故障被优雅处理且不暴露内部细节。识别并发代码中潜在的竞态条件：检查-然后-执行模式、共享可变状态、缺失同步机制。验证循环会终止，递归有基例。
性能考量：评估算法复杂度——在无界输入上使用O(n²)或更差的算法存在问题。检查资源清理：文件是否关闭、连接是否释放、定时器是否清除、事件监听器是否移除。评估昂贵计算或外部调用的缓存机会。审查大型数据集的懒加载和分页实现。识别阻塞事件循环或主线程的同步操作。
可维护性标准：评估耦合度——变更应局限于局部，而非波及多个模块。验证单一职责原则——函数和类应有且仅有一个变更原因。检查魔法数字和字符串——提取为命名常量。审查错误信息的可操作性——包含调试所需的上下文。
命名质量：命名应清晰表达意图——函数使用动词短语（如
validateOrder
，而非
process
），变量使用描述性名词（如
userCount
，而非
n
），布尔值使用前缀（
is
、
has
、
can
）。有关各语言的详细命名规范和常见反模式，请参阅
~/.agents/skills/code-review/references/naming.md
。

Relative Change Analysis

相对变更分析

Distinguish between incremental adjustments and fundamental shifts in system behavior. A timeout changing from 1 second to 2 seconds represents 100% increase but minimal risk. The same timeout changing from 1 second to 60 seconds represents 6000% increase and warrants investigation.
Compare new values against established baselines. When reviewing a connection pool size change from 10 to 100, consider current utilization metrics. Is the system exhausting the pool? What's the saturation pattern? Demand evidence supporting the magnitude of change.
Scale risk assessment with change magnitude. Small adjustments (10-50% variation) may reflect tuning. Medium changes (2-5x) require justification with metrics or load testing results. Large changes (10x or more) demand comprehensive evidence: benchmarks, capacity planning, failure mode analysis.
Apply the risk formula: 
risk = magnitude × blast_radius × reversibility_difficulty
. High magnitude on low-traffic features may be acceptable. Small magnitude on critical path authentication logic still warrants scrutiny. Consider rollback complexity—database schema changes are harder to reverse than configuration adjustments.
区分增量调整和系统行为的根本性转变。超时从1秒改为2秒，增幅为100%但风险极小。而超时从1秒改为60秒，增幅达6000%，需要深入调查。
将新值与既定基准进行比较。当评审连接池大小从10改为100的变更时，考虑当前的利用率指标。系统是否耗尽了连接池？饱和模式如何？要求提供支持变更幅度的证据。
根据变更幅度调整风险评估。小幅调整（10-50%的变化）可能是调优操作。中等变更（2-5倍）需要指标或负载测试结果作为依据。大幅变更（10倍及以上）需要全面的证据：基准测试、容量规划、故障模式分析。
应用风险公式：
风险 = 幅度 × 影响范围 × 回滚难度
。低流量功能上的大幅变更可能是可接受的。关键路径认证逻辑上的小幅变更仍需仔细审查。考虑回滚复杂度——数据库模式变更比配置变更更难回滚。

Environment-Aware Review

环境感知评审

Recognize that development, staging, and production environments often employ different limits and configurations. Aggressive timeouts acceptable in development may cause issues in high-latency production environments. Generous resource allocations in staging may not reflect production constraints.
Evaluate whether risky changes are protected by feature flags allowing gradual rollout and quick rollback. Recommend feature flags for changes affecting critical paths, introducing new algorithms, or modifying established behavior with broad impact.
Consider gradual rollout patterns. Canary deployments test changes on small traffic percentages. Blue-green deployments enable atomic switches with quick rollback. Percentage-based feature flags allow progressive exposure monitoring impact at each stage.
Assess rollback planning. Can changes be reverted safely? Do database migrations have down migrations? Are configuration changes backward compatible? Does the deploy process support rapid rollback to previous versions?
认识到开发、预发布和生产环境通常采用不同的限制和配置。开发环境中可接受的激进超时设置，在高延迟的生产环境中可能导致问题。预发布环境中宽松的资源分配可能无法反映生产环境的约束。
评估风险变更是否由功能标志（feature flags）保护，以支持逐步发布和快速回滚。建议对影响关键路径、引入新算法或修改广泛影响的既定行为的变更使用功能标志。
考虑逐步发布模式。金丝雀发布（Canary deployments）在小流量百分比上测试变更。蓝绿发布（Blue-green deployments）支持原子切换和快速回滚。基于百分比的功能标志允许逐步暴露变更，并在每个阶段监控影响。
评估回滚规划。变更能否安全回滚？数据库迁移是否有回滚脚本？配置变更是否向后兼容？部署流程是否支持快速回滚到之前的版本？

Monitoring Requirements

监控要求

Define specific metrics to track for different change types. Performance optimizations require before/after latency measurements, throughput metrics, and resource utilization. Database changes need query execution time, lock contention, and connection pool saturation. External API integrations require success rates, timeout occurrences, and circuit breaker state transitions.
Establish alerting thresholds before deploying changes. Define acceptable error rate increases, latency percentiles, and throughput degradation. Set thresholds based on historical baselines and business requirements. Alert on anomalies rather than absolute values when traffic patterns vary.
Identify necessary dashboards and observability improvements. New features need monitoring of adoption metrics, error rates, and performance. Refactored code should maintain existing observability or improve it. Infrastructure changes require visibility into resource utilization and saturation.
Assess SLO and SLA impact. Will changes affect availability, latency, or error rate commitments? Do capacity changes risk SLA breaches under peak load? Are there graceful degradation strategies if changes introduce issues?
为不同类型的变更定义具体的跟踪指标。性能优化需要前后延迟测量、吞吐量指标和资源利用率数据。数据库变更需要查询执行时间、锁竞争和连接池饱和情况。外部API集成需要成功率、超时发生次数和断路器状态转换数据。
在部署变更前设置告警阈值。定义可接受的错误率增长、延迟百分位数和吞吐量下降范围。基于历史基准和业务需求设置阈值。当流量模式变化时，针对异常情况告警而非绝对数值。
识别必要的仪表板和可观测性改进。新功能需要监控采用率指标、错误率和性能。重构后的代码应保持或改进现有的可观测性。基础设施变更需要资源利用率和饱和情况的可见性。
评估对SLO和SLA的影响。变更是否会影响可用性、延迟或错误率承诺？容量变更是否会在峰值负载下导致SLA违约？如果变更引入问题，是否有优雅降级策略？

Output Format

输出格式

Structure review findings for maximum clarity and actionability:
Group issues by severity level, presenting CRITICAL findings first, followed by HIGH, MEDIUM, and LOW. Within each severity tier, group related issues together.
Include file paths and line numbers when available. When line numbers are uncertain, cite function names with quoted snippets. Never fabricate line references. Use the format 
path/to/file.ts:42-45
to specify exact locations. Quote relevant code snippets when helpful for context.
Provide evidence-based findings rather than opinions. Reference security standards (OWASP), performance benchmarks, or language best practices. Explain the potential impact and attack vectors for security issues. Quantify performance implications when possible.
Deliver actionable recommendations with specificity. Instead of "improve error handling," suggest "wrap database operations in try-catch and return user-friendly error response." Provide code examples demonstrating fixes when helpful, but avoid rewriting entire functions unless requested.
Acknowledge good practices observed in the code. Highlight effective patterns, thorough test coverage, or well-designed abstractions. Balanced feedback strengthens credibility and encourages continuation of positive practices.
结构化评审结果，以最大程度提升清晰度和可操作性：
按严重程度分组展示问题，先展示CRITICAL（关键）问题，然后是HIGH（高）、MEDIUM（中）和LOW（低）。在每个严重程度层级内，将相关问题分组在一起。
尽可能包含文件路径和行号。当行号不确定时，引用函数名称并附上代码片段。切勿编造行号引用。使用
path/to/file.ts:42-45
格式指定精确位置。必要时引用相关代码片段以提供上下文。
提供基于证据的发现而非主观意见。参考安全标准（如OWASP）、性能基准或语言最佳实践。解释安全问题的潜在影响和攻击向量。尽可能量化性能影响。
提供具体的可操作建议。不要仅说“改进错误处理”，而是建议“将数据库操作包裹在try-catch块中，并返回用户友好的错误响应”。必要时提供代码示例演示修复方法，但除非被要求，否则不要重写整个函数。
认可代码中观察到的良好实践。突出有效的模式、全面的测试覆盖或设计良好的抽象。平衡的反馈能提升可信度，并鼓励持续的良好实践。

Review Template

评审模板

Structure reviews consistently:
  1. Context Questions (if needed): 1-3 clarifying questions about intent or constraints
  2. Findings: Grouped by severity (CRITICAL → HIGH → MEDIUM → LOW)
  3. Suggested Fixes: Code snippets or specific recommendations
  4. Deployment Notes: Rollout strategy, monitoring requirements (when applicable)
  5. Applied Fixes (only when 
    --fix
    is present): concrete list of implemented changes with file references
Important:
  • Default behavior: After presenting findings, wait for the user to confirm which issues to address.
  • With 
    --fix
    : Do not wait for confirmation. Apply all suggested fixes automatically, then provide an implementation summary and any remaining follow-ups.
保持评审结构的一致性：
  1. 上下文问题（如有需要）：1-3个关于意图或约束的澄清问题
  2. 发现的问题：按严重程度分组（CRITICAL → HIGH → MEDIUM → LOW）
  3. 建议修复方案：代码片段或具体建议
  4. 部署说明：发布策略、监控要求（如适用）
  5. 已应用的修复（仅当使用
    --fix
    参数时）：已实施变更的具体列表，包含文件引用
重要提示：
  • 默认行为：展示发现的问题后，等待用户确认要处理哪些问题。
  • 使用
    --fix
    参数时：无需等待确认，自动应用所有建议的修复，然后提供实现摘要和任何剩余的后续工作。

Additional Resources

额外资源

Consult specialized reference documents for in-depth guidance on specific review areas:
  • ~/.agents/skills/code-review/references/configuration.md - Configuration file review patterns including environment-specific validation, secrets management, and limit tuning
  • ~/.agents/skills/code-review/references/security.md - Comprehensive security review covering OWASP Top 10, authentication patterns, authorization models, cryptography, input validation, and secure defaults
  • ~/.agents/skills/code-review/references/typescript-react.md - Frontend and Node.js patterns including React hooks, state management, TypeScript type safety, async handling, and API design
  • ~/.agents/skills/code-review/references/python.md - Python-specific patterns covering type hints, async/await, exception handling, context managers, and common library pitfalls
  • ~/.agents/skills/code-review/references/smart-contracts.md - Blockchain security for Solidity and Solana including reentrancy, integer overflow, access control, and economic attack vectors
  • ~/.agents/skills/code-review/references/shell.md - Bash script review covering quoting, error handling, portability, security risks from command injection and path traversal
  • ~/.agents/skills/code-review/references/data-formats.md - CSV, JSON, and data format handling including parsing safety, schema validation, and encoding issues
  • ~/.agents/skills/code-review/references/naming.md - Naming conventions covering functions, variables, files, classes, and constants with language-specific patterns and common anti-patterns
Reference these documents when reviewing code in their respective domains for detailed checklists and language-specific vulnerabilities.
针对特定评审领域，参考专业的文档获取深入指导：
  • ~/.agents/skills/code-review/references/configuration.md - 配置文件评审模式，包括环境特定验证、密钥管理和限制调优
  • ~/.agents/skills/code-review/references/security.md - 全面的安全评审指南，涵盖OWASP Top 10、认证模式、授权模型、加密、输入验证和安全默认设置
  • ~/.agents/skills/code-review/references/typescript-react.md - 前端和Node.js模式，包括React hooks、状态管理、TypeScript类型安全、异步处理和API设计
  • ~/.agents/skills/code-review/references/python.md - Python特定模式，包括类型提示、async/await、异常处理、上下文管理器和常见库陷阱
  • ~/.agents/skills/code-review/references/smart-contracts.md - Solidity和Solana的区块链安全指南，包括重入攻击、整数溢出、访问控制和经济攻击向量
  • ~/.agents/skills/code-review/references/shell.md - Bash脚本评审指南，包括引号使用、错误处理、可移植性、命令注入和路径遍历的安全风险
  • ~/.agents/skills/code-review/references/data-formats.md - CSV、JSON和数据格式处理指南，包括解析安全、 schema验证和编码问题
  • ~/.agents/skills/code-review/references/naming.md - 命名规范指南，涵盖函数、变量、文件、类和常量，包含特定语言的模式和常见反模式
在评审对应领域的代码时，参考这些文档获取详细的检查清单和特定语言的漏洞信息。

Examples

示例

  • ~/.agents/skills/code-review/references/example-good-review.md - Exemplary review output demonstrating proper structure, severity grouping, and actionable recommendations
  • ~/.agents/skills/code-review/references/example-bad-review.md - Anti-patterns to avoid including fabricated line numbers, vague findings, and opinion without evidence
  • ~/.agents/skills/code-review/references/example-good-review.md - 优秀评审输出示例，展示正确的结构、严重程度分组和可操作建议
  • ~/.agents/skills/code-review/references/example-bad-review.md - 应避免的反模式示例，包括编造行号、模糊的发现和无证据的主观意见