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

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

2. See what changed

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)


**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:

Read the complete code path - not just the suspicious line
Trace what actually happens - follow execution from start to end
Verify the issue exists - confirm there is no defensive code preventing it
Consider all scenarios - including error paths, cancellation, edge cases

针对每个变更文件和差异块，结合现有代码库上下文进行评估。

强制要求：标记严重/重大问题前必须完整追踪执行流程

将任何问题归类为严重（Critical）或重大（Major）前，必须：

通读完整代码路径 - 而非仅关注可疑行
追踪实际执行过程 - 从开始到结束跟进执行流程
验证问题确实存在 - 确认没有防御性代码阻止该问题
考虑所有场景 - 包括错误路径、取消操作、边缘情况

4. Review Categories

4. 审核分类

Category	What to Check
Design & Architecture	Fits system patterns, avoids coupling, clear separation
Complexity & Maintainability	Flat control flow, low complexity, DRY, no dead code
Functionality & Correctness	Valid/invalid inputs handled, edge cases covered
Readability & Naming	Intent-revealing names, comments explain WHY
Best Practices	Language/framework idioms, SOLID principles
Test Coverage	Success + failure paths tested
Standardization	Style guide conformance, zero new lint warnings
Security	Input validation, secrets management, OWASP Top 10
Performance	No N+1 queries, efficient I/O, no memory leaks
Logging	State machine pattern, proper tense, actionable context
Metrics	No 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
Length	50-200 chars	>200 (truncation)
Multiline	Single line	Multiple 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`
Type	Counter (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.

Start with highest priority (Critical → Major → Minor)
For each issue:
- Fix the code
- Verify fix doesn't break anything
- CHECKPOINT COMMIT:
```
git add -A && git commit -m "fix: brief description"
```
Continue until ALL issues are resolved

针对每个已验证的问题：

文件：
```
<路径>:<行号范围>
```
问题：一行摘要
修复方案：简洁的建议修改

严重程度分级：

严重（P0）：安全漏洞、数据丢失、系统崩溃
重大（P1）：严重bug、性能问题、架构违规
次要（P2）：代码风格、小改进
优化建议（P3）：锦上添花的改进

强制要求：识别问题后立即修复所有问题。

从最高优先级开始（严重→重大→次要）
针对每个问题：
- 修复代码
- 验证修复不会破坏现有功能
- 检查点提交：
```
git add -A && git commit -m "fix: 简要描述"
```
持续直到所有问题解决

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

参考资料

Reference	Purpose
`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

最佳实践

No assumptions - Read ALL related code before flagging issues
Fix immediately - Don't just report, fix and commit
Checkpoint commits - Commit each fix separately for easy rollback
Verify first - Trace execution paths before claiming bugs exist
Project rules priority - Always check
```
.cursor/rules/
```
and
```
AGENTS.md
```
Be timely - Review promptly to avoid blocking teammates
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.

不主观假设 - 标记问题前通读所有相关代码
立即修复 - 不只是报告问题，还要修复并提交
检查点提交 - 每次修复单独提交，便于回滚
先验证 - 追踪执行路径后再确认存在漏洞
项目规则优先 - 始终检查
```
.cursor/rules/
```
和
```
AGENTS.md
```
及时审核 - 及时审核避免阻塞队友
限制范围 - 每次审核不超过400行代码以保证有效性

原则：审核 → 修复 → 验证 → 提交。仅识别问题而不修复的审核是不完整的。