Back to Details

code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Review

代码审核

Perform a thorough senior-level code review on recent changes. Focus human review on complex logic, architecture, and edge cases. Delegate style enforcement to automated tools.
Related Skills:
  • kavak-documentation
    - Query for Kavak-specific patterns, logging/metrics standards, GitLab CI templates
  • Use 
    kavak-platform/plati_query
    MCP tool to verify Kavak best practices when reviewing
对近期代码变更进行全面的资深级代码审核。人工审核重点关注复杂逻辑、架构和边缘情况，代码风格检查交由自动化工具完成。
相关技能：
  • kavak-documentation
    - 查询Kavak特定模式、日志/指标标准、GitLab CI模板
  • 使用
    kavak-platform/plati_query
    MCP工具，在审核时验证Kavak最佳实践

Quick Start

快速开始

bash
undefined
bash
undefined

1. Get review range

1. Get review range

BASE_SHA=$(git rev-parse HEAD~1) # or: git merge-base main HEAD HEAD_SHA=$(git rev-parse HEAD)
BASE_SHA=$(git rev-parse HEAD~1) # or: git merge-base main HEAD HEAD_SHA=$(git rev-parse HEAD)

2. See what changed

2. See what changed

git diff --stat $BASE_SHA..$HEAD_SHA git diff --name-only $BASE_SHA..$HEAD_SHA --diff-filter=ACMR
git diff --stat $BASE_SHA..$HEAD_SHA git diff --name-only $BASE_SHA..$HEAD_SHA --diff-filter=ACMR

3. After review, run quality gates (detect project type)

3. After review, run quality gates (detect project type)


**Quality gate commands by language:**
| Language | Lint | Build | Test |
|----------|------|-------|------|
| Go | `golangci-lint run` | `go build ./...` | `go test ./...` |
| Node/TS | `npm run lint` | `npm run build` | `npm test` |
| Python | `ruff check .` | `python -m py_compile` | `pytest` |
| Java | `./mvnw checkstyle:check` | `./mvnw compile` | `./mvnw test` |

**按语言分类的质量门禁命令：**
| 编程语言 | Lint | 构建 | 测试 |
|----------|------|-------|------|
| Go | `golangci-lint run` | `go build ./...` | `go test ./...` |
| Node/TS | `npm run lint` | `npm run build` | `npm test` |
| Python | `ruff check .` | `python -m py_compile` | `pytest` |
| Java | `./mvnw checkstyle:check` | `./mvnw compile` | `./mvnw test` |

When to Self-Review (Automated)

何时进行自我审核（自动化）

Mandatory triggers:
  • After completing each task in multi-step development
  • After implementing a major feature
  • Before merging to main branch
Valuable triggers:
  • When stuck (fresh perspective on own code)
  • Before refactoring (baseline check)
  • After fixing complex bugs
强制触发场景：
  • 完成多阶段开发中的每个任务后
  • 实现主要功能后
  • 合并到main分支前
建议触发场景：
  • 遇到瓶颈时（以新视角审视自己的代码）
  • 重构前（进行基线检查）
  • 修复复杂漏洞后

Review Mindset

审核心态

  • Thorough, not rushed - Read all related code before concluding
  • Evidence-based - Trace execution paths, don't assume bugs exist
  • Fix, don't just flag - Identify issues AND resolve them
  • Small scope - Review <400 lines at a time for effectiveness
  • 全面细致，勿仓促 - 得出结论前通读所有相关代码
  • 基于证据 - 追踪执行路径，不主观假设存在漏洞
  • 修复而非仅标记 - 识别问题并解决问题
  • 小范围审核 - 每次审核不超过400行代码以保证有效性

Workflow

工作流程

1. Scope the Diff

1. 确定差异范围

Identify all changed files:
bash
git diff --name-only HEAD~1 --diff-filter=ACMR
For each file in the list, skip any that produces no actual diff hunks.
识别所有变更文件：
bash
git diff --name-only HEAD~1 --diff-filter=ACMR
对于列表中的每个文件，跳过无实际差异块的文件。

2. Understand Intent & Requirements

2. 理解意图与需求

Before reviewing code, understand what it should do:
  • Original task/issue: What was requested?
  • Product impact: What does this deliver for users?
  • Acceptance criteria: What defines "done"?
Ask: "Does the implementation satisfy the requirements?"
审核代码前，先明确代码应实现的功能：
  • 原始任务/需求：需要实现什么？
  • 产品影响：这将为用户带来什么价值？
  • 验收标准：什么是“完成”的定义？
思考：“实现是否满足需求？”

3. Review Each File

3. 审核每个文件

For each changed file and each diff hunk, evaluate in context of the existing codebase.
MANDATORY: Trace Complete Execution Before Flagging Critical/Major
Before classifying any issue as Critical or Major, you MUST:
  1. Read the complete code path - not just the suspicious line
  2. Trace what actually happens - follow execution from start to end
  3. Verify the issue exists - confirm there is no defensive code preventing it
  4. Consider all scenarios - including error paths, cancellation, edge cases
针对每个变更文件和差异块，结合现有代码库上下文进行评估。
强制要求：标记严重/重大问题前必须完整追踪执行流程
将任何问题归类为严重（Critical）或重大（Major）前，必须：
  1. 通读完整代码路径 - 而非仅关注可疑行
  2. 追踪实际执行过程 - 从开始到结束跟进执行流程
  3. 验证问题确实存在 - 确认没有防御性代码阻止该问题
  4. 考虑所有场景 - 包括错误路径、取消操作、边缘情况

4. Review Categories

4. 审核分类

CategoryWhat to Check
Design & ArchitectureFits system patterns, avoids coupling, clear separation
Complexity & MaintainabilityFlat control flow, low complexity, DRY, no dead code
Functionality & CorrectnessValid/invalid inputs handled, edge cases covered
Readability & NamingIntent-revealing names, comments explain WHY
Best PracticesLanguage/framework idioms, SOLID principles
Test CoverageSuccess + failure paths tested
StandardizationStyle guide conformance, zero new lint warnings
SecurityInput validation, secrets management, OWASP Top 10
PerformanceNo N+1 queries, efficient I/O, no memory leaks
LoggingState machine pattern, proper tense, actionable context
MetricsNo cardinality explosions, proper naming, documented
Automation tip: Delegate style/formatting to linters (ESLint, Prettier). Focus human review on logic, architecture, and edge cases.
分类检查内容
设计与架构是否符合系统模式，避免耦合，职责分离清晰
复杂度与可维护性控制流程扁平，复杂度低，遵循DRY原则，无死代码
功能与正确性处理有效/无效输入，覆盖边缘情况
可读性与命名命名能体现意图，注释解释“为什么”而非“怎么做”
最佳实践遵循语言/框架惯用写法，SOLID原则
测试覆盖率覆盖成功与失败路径
标准化符合风格指南，无新增lint警告
安全性输入验证，密钥管理，OWASP Top 10
性能无N+1查询，高效I/O，无内存泄漏
日志遵循状态机模式，时态正确，上下文可操作
指标无基数爆炸，命名规范，有文档说明
自动化小贴士：将代码风格/格式检查交由linter工具（ESLint、Prettier）处理。人工审核重点关注逻辑、架构和边缘情况。

4.1 Logging Review

4.1 日志审核

Check✓ Good✗ Bad
Length50-200 chars>200 (truncation)
MultilineSingle lineMultiple lines
Start"Syncing orders" (progressive)"Sync orders"
End OK"Orders synced" (past)"Syncing complete"
End Fail"Failed to sync orders""Error"
Context"DB timeout after 30s""Database error"
检查项✓ 良好✗ 不佳
长度50-200字符>200（会被截断）
行数单行多行
开头"Syncing orders"（进行时态）"Sync orders"
成功结尾"Orders synced"（过去时态）"Syncing complete"
失败结尾"Failed to sync orders""Error"
上下文"DB timeout after 30s""Database error"

4.2 Metrics Review

4.2 指标审核

Check✓ Good✗ Bad (CRITICAL)
Labels
status=2xx
, 
method=GET
user_id
, 
order_id
Naming
api.request.total
apiRequestTotal
TypeCounter (events), Histogram (latency)Gauge for everything
CRITICAL: High-cardinality labels (user_id, request_id, timestamp) cause monitoring system crashes.
检查项✓ 良好✗ 严重问题
标签
status=2xx
, 
method=GET
user_id
, 
order_id
命名
api.request.total
apiRequestTotal
类型计数器（事件）、直方图（延迟）所有指标都用仪表盘（Gauge）
严重问题：高基数标签（user_id、request_id、timestamp）会导致监控系统崩溃。

5. Check Project Rules

5. 检查项目规则

MANDATORY: Check and enforce rules from:
  • .claude/CLAUDE.md
    or 
    CLAUDE.md
    (root)
  • .cursor/rules/
    folder
  • AGENTS.md
  • Follow ALL patterns and conventions defined there
强制要求：检查并执行以下来源的规则：
  • .claude/CLAUDE.md
    或 
    CLAUDE.md
    （根目录）
  • .cursor/rules/
    文件夹
  • AGENTS.md
  • 遵循其中定义的所有模式与规范

6. Report & Fix Issues

6. 报告并修复问题

For each validated issue:
  • File: 
    <path>:<line-range>
  • Issue: One-line summary
  • Fix: Concise suggested change
Severity levels:
  • Critical (P0): Security vulnerabilities, data loss, crashes
  • Major (P1): Significant bugs, performance issues, architectural violations
  • Minor (P2): Code style, minor improvements
  • Enhancement (P3): Nice-to-have improvements
MANDATORY: Fix all issues immediately after identifying them.
  1. Start with highest priority (Critical → Major → Minor)
  2. For each issue:
    • Fix the code
    • Verify fix doesn't break anything
    • CHECKPOINT COMMIT: 
      git add -A && git commit -m "fix: brief description"
  3. Continue until ALL issues are resolved
针对每个已验证的问题：
  • 文件：
    <路径>:<行号范围>
  • 问题：一行摘要
  • 修复方案：简洁的建议修改
严重程度分级：
  • 严重（P0）：安全漏洞、数据丢失、系统崩溃
  • 重大（P1）：严重bug、性能问题、架构违规
  • 次要（P2）：代码风格、小改进
  • 优化建议（P3）：锦上添花的改进
强制要求：识别问题后立即修复所有问题。
  1. 从最高优先级开始（严重→重大→次要）
  2. 针对每个问题：
    • 修复代码
    • 验证修复不会破坏现有功能
    • 检查点提交：
      git add -A && git commit -m "fix: 简要描述"
  3. 持续直到所有问题解决

7. Run Quality Gates

7. 运行质量门禁

After all issues are fixed, run lint → build → test for project type (see Quick Start table).
If any gate fails, fix immediately and commit the fix.
修复所有问题后，根据项目类型运行lint → 构建 → 测试（见快速开始表格）。
如果任何门禁失败，立即修复并提交修复。

8. Final Report

8. 最终报告

Provide structured output:
markdown
undefined
提供结构化输出：
markdown
undefined

Strengths

优势

[What's well done - be specific with file:line references]
[做得好的地方 - 需具体到文件:行号]

Issues Found & Fixed

发现并修复的问题

  • Critical: [count] - [brief list]
  • Major: [count] - [brief list]
  • Minor: [count] - [brief list]
  • 严重：[数量] - [简要列表]
  • 重大：[数量] - [简要列表]
  • 次要：[数量] - [简要列表]

Quality Gates

质量门禁

  • Lint: ✓/✗
  • Typecheck: ✓/✗
  • Build: ✓/✗
  • Tests: ✓/✗
  • Lint: ✓/✗
  • 类型检查: ✓/✗
  • 构建: ✓/✗
  • 测试: ✓/✗

Assessment

评估

Ready to proceed? [Yes / Yes with notes / No - needs fixes] Reasoning: [1-2 sentence technical assessment]

If no issues: "Code review complete. No issues found. All quality gates pass. Ready to proceed."
是否可继续推进？ [是 / 是（附说明） / 否 - 需修复] 理由: [1-2句技术评估]

如果无问题：“代码审核完成。未发现问题。所有质量门禁通过。可继续推进。”

References

参考资料

ReferencePurpose
references/checklist.md
Detailed review checklist
references/severity-guide.md
How to classify issue severity
references/common-issues.md
Common issues (TypeScript/Node)
references/common-issues-go.md
Common issues (Go)
references/security-owasp.md
OWASP Top 10 security checklist
references/feedback-guide.md
How to give constructive feedback
references/self-review-workflow.md
Automated self-review during development
参考资料用途
references/checklist.md
详细审核清单
references/severity-guide.md
问题严重程度分类指南
references/common-issues.md
常见问题（TypeScript/Node）
references/common-issues-go.md
常见问题（Go）
references/security-owasp.md
OWASP Top 10安全清单
references/feedback-guide.md
如何给出建设性反馈
references/self-review-workflow.md
开发过程中的自动化自我审核流程

Best Practices

最佳实践

  1. No assumptions - Read ALL related code before flagging issues
  2. Fix immediately - Don't just report, fix and commit
  3. Checkpoint commits - Commit each fix separately for easy rollback
  4. Verify first - Trace execution paths before claiming bugs exist
  5. Project rules priority - Always check 
    .cursor/rules/
    and 
    AGENTS.md
  6. Be timely - Review promptly to avoid blocking teammates
  7. Limit scope - Review <400 lines at a time for effectiveness
Principle: Review → Fix → Verify → Commit. A review that only identifies problems without fixing them is incomplete.
  1. 不主观假设 - 标记问题前通读所有相关代码
  2. 立即修复 - 不只是报告问题，还要修复并提交
  3. 检查点提交 - 每次修复单独提交，便于回滚
  4. 先验证 - 追踪执行路径后再确认存在漏洞
  5. 项目规则优先 - 始终检查
    .cursor/rules/
    和
    AGENTS.md
  6. 及时审核 - 及时审核避免阻塞队友
  7. 限制范围 - 每次审核不超过400行代码以保证有效性
原则：审核 → 修复 → 验证 → 提交。仅识别问题而不修复的审核是不完整的。