comprehensive-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comprehensive Review

全面代码审查

Overview

概述

Review code against 7 criteria before considering it complete.

Core principle: Self-review catches issues before they reach others.

HARD REQUIREMENT: Review artifact MUST be posted to the GitHub issue. This is enforced by hooks.

Announce at start: "I'm performing a comprehensive code review."

在认为代码完成前，需对照7项标准进行审查。

核心原则： 自我审查能在问题传递给他人之前发现问题。

硬性要求： 必须将审查成果发布至GitHub Issue。这一要求由钩子（hooks）强制执行。

开始时需声明： "我正在执行全面代码审查。"

Review Artifact Requirement

审查成果要求

This is not optional. Before a PR can be created:

Complete review against all 7 criteria
Document all findings
Post artifact to issue comment using EXACT format below
Address all findings (fix or defer with tracking issues)
Update artifact to show "Unaddressed: 0"

The

review-gate

skill and

PreToolUse

hook will BLOCK PR creation without this artifact.

此项要求为强制项。 在创建PR之前：

对照全部7项标准完成审查
记录所有发现的问题
使用以下精确格式将审查成果发布至Issue评论区
处理所有发现的问题（修复或通过跟踪Issue延期处理）
更新审查成果，显示“未处理问题：0”

若未提交该审查成果，

review-gate

skill和

PreToolUse

钩子将阻止创建PR。

The 7 Criteria

7项审查标准

1. Blindspots

1. 盲点检查

Question: What am I missing?

Check	Ask Yourself
Edge cases	What happens at boundaries? Empty input? Max values?
Error paths	What if external services fail? Network issues?
Concurrency	Multiple users/threads? Race conditions?
State	What if called in wrong order? Invalid state?
Dependencies	What if dependency behavior changes?

typescript

// Blindspot example: What if items is empty?
function calculateAverage(items: number[]): number {
  return items.reduce((a, b) => a + b, 0) / items.length;
  // Blindspot: Division by zero when items is empty!
}

// Fixed
function calculateAverage(items: number[]): number {
  if (items.length === 0) {
    throw new Error('Cannot calculate average of empty array');
  }
  return items.reduce((a, b) => a + b, 0) / items.length;
}

问题： 我遗漏了什么？

检查项	自我提问
边缘情况	在边界条件下会发生什么？空输入？最大值？
错误路径	若外部服务故障会怎样？网络问题？
并发情况	多用户/多线程场景？竞态条件？
状态问题	若调用顺序错误会怎样？无效状态？
依赖问题	若依赖项行为变更会怎样？

typescript

// Blindspot example: What if items is empty?
function calculateAverage(items: number[]): number {
  return items.reduce((a, b) => a + b, 0) / items.length;
  // Blindspot: Division by zero when items is empty!
}

// Fixed
function calculateAverage(items: number[]): number {
  if (items.length === 0) {
    throw new Error('Cannot calculate average of empty array');
  }
  return items.reduce((a, b) => a + b, 0) / items.length;
}

2. Clarity/Consistency

2. 清晰度/一致性

Question: Will someone else understand this?

Check	Ask Yourself
Names	Do names describe what things do/are?
Structure	Is code organized logically?
Complexity	Can this be simplified?
Patterns	Does this match existing patterns?
Surprises	Would anything surprise a reader?

问题： 其他人能理解这段代码吗？

检查项	自我提问
命名	命名是否准确描述了功能/事物本身？
结构	代码组织是否逻辑清晰？
复杂度	这段代码能否简化？
模式	是否与现有代码模式一致？
意外情况	是否存在会让读者感到意外的内容？

3. Maintainability

3. 可维护性

Question: Can this be changed safely?

Check	Ask Yourself
Coupling	Is this tightly bound to other code?
Cohesion	Does this do one thing well?
Duplication	Is logic repeated anywhere?
Tests	Do tests cover this adequately?
Extensibility	Can new features be added easily?

问题： 能否安全地修改这段代码？

检查项	自我提问
耦合度	是否与其他代码高度绑定？
内聚性	是否专注完成单一功能？
重复代码	逻辑是否存在重复？
测试	测试是否充分覆盖了这段代码？
可扩展性	是否易于添加新功能？

4. Security Risks

4. 安全风险

Question: Can this be exploited?

Check	Ask Yourself
Input validation	Is all input validated and sanitized?
Authentication	Is access properly controlled?
Authorization	Are permissions checked?
Data exposure	Is sensitive data protected?
Injection	SQL, XSS, command injection possible?
Dependencies	Are dependencies secure and updated?

NOTE: If security-sensitive files are changed (auth, api, middleware, etc.), invoke

security-review

skill for deeper analysis.

问题： 这段代码是否存在被利用的风险？

检查项	自我提问
输入验证	所有输入是否都经过验证和清理？
身份认证	访问控制是否得当？
权限授权	是否检查了权限？
数据暴露	敏感数据是否得到保护？
注入风险	是否存在SQL、XSS、命令注入的可能？
依赖项安全	依赖项是否安全且已更新？

注意： 若修改了安全敏感文件（认证、API、中间件等），需调用

security-review

skill进行深度分析。

5. Performance Implications

5. 性能影响

Question: Will this scale?

Check	Ask Yourself
Algorithms	Is complexity appropriate? O(n²) when O(n) possible?
Database	N+1 queries? Missing indexes? Full table scans?
Memory	Large objects in memory? Memory leaks?
Network	Unnecessary requests? Large payloads?
Caching	Should results be cached?

问题： 这段代码能否横向扩展？

检查项	自我提问
算法	复杂度是否合适？是否存在可用O(n)实现却用了O(n²)的情况？
数据库	是否存在N+1查询？缺少索引？全表扫描？
内存	是否在内存中存储大型对象？是否存在内存泄漏？
网络	是否存在不必要的请求？ payload过大？
缓存	是否应该对结果进行缓存？

6. Documentation

6. 文档

Question: Is this documented adequately?

Check	Ask Yourself
Public APIs	Are all public functions documented?
Parameters	Are parameter types and purposes clear?
Returns	Is return value documented?
Errors	Are thrown errors documented?
Examples	Are complex usages demonstrated?
Why	Are non-obvious decisions explained?

See

inline-documentation

skill for documentation standards.

问题： 文档是否足够充分？

检查项	自我提问
公共API	所有公共函数是否都有文档？
参数	参数类型和用途是否清晰？
返回值	返回值是否有文档说明？
错误	抛出的错误是否有文档说明？
示例	是否展示了复杂用法的示例？
决策依据	非显而易见的决策是否有解释？

文档标准可参考

inline-documentation

skill。

7. Standards and Style

7. 标准与风格

Question: Does this follow project conventions?

Check	Ask Yourself
Naming	Follows project naming conventions?
Formatting	Matches project formatting?
Patterns	Uses established patterns?
Types	Fully typed (no `any` )?
Language	Uses inclusive language?
IPv6-first	Network code uses IPv6 by default? IPv4 only for documented legacy?
Linting	Passes all linters?

See

style-guide-adherence

strict-typing

inclusive-language

ipv6-first

skills.

问题： 是否遵循项目约定？

检查项	自我提问
命名	是否遵循项目命名规范？
格式	是否与项目格式一致？
模式	是否使用已确立的模式？
类型	是否完全类型化（无 `any` ）？
语言	是否使用包容性语言？
IPv6优先	网络代码是否默认使用IPv6？仅在有文档说明的遗留场景下使用IPv4？
代码检查	是否通过所有代码检查工具的校验？

Review Process

审查流程

Step 1: Prepare

步骤1：准备

bash

undefined

bash

undefined

Get list of changed files

git diff --name-only HEAD~1

Get full diff

git diff HEAD~1

Check for security-sensitive files

If matches found, security-review skill is MANDATORY

undefined

undefined

Step 2: Review Each Criterion

步骤2：逐一审查各项标准

For each of the 7 criteria:

Review all changed code
Note any issues found
Determine severity (Critical/Major/Minor)

针对每一项标准：

审查所有变更的代码
记录发现的所有问题
确定严重程度（Critical/Major/Minor）

Step 3: Check Security-Sensitive

步骤3：检查安全敏感文件

If ANY security-sensitive files were changed:

Invoke
```
security-review
```
skill OR
```
security-reviewer
```
subagent
Include security review results in artifact
Mark "Security-Sensitive: YES" in artifact

若任何安全敏感文件被修改：

调用
```
security-review
```
skill 或
```
security-reviewer
```
子Agent
将安全审查结果纳入审查成果
在审查成果中标记“安全敏感：是”

Step 4: Document Findings

步骤4：记录发现的问题

markdown

undefined

markdown

undefined

Code Review Findings

1. Blindspots

Critical: No handling for empty array in
```
calculateAverage()
```
Minor: Missing null check in
```
formatUser()
```

Critical: No handling for empty array in
```
calculateAverage()
```
Minor: Missing null check in
```
formatUser()
```

2. Clarity/Consistency

Major: Variable
```
x
```
should have descriptive name

Major: Variable
```
x
```
should have descriptive name

3. Maintainability

No issues found

No issues found

4. Security Risks

Critical: SQL injection possible in
```
findUser()
```

Critical: SQL injection possible in
```
findUser()
```

5. Performance Implications

Major: N+1 query in
```
getOrdersWithUsers()
```

Major: N+1 query in
```
getOrdersWithUsers()
```

6. Documentation

Minor: Missing JSDoc on
```
processOrder()
```

Minor: Missing JSDoc on
```
processOrder()
```

7. Standards and Style

Passes all checks

undefined

Passes all checks

undefined

Step 5: Address All Findings

步骤5：处理所有发现的问题

Use

apply-all-findings

skill to address every issue.

For findings that cannot be fixed:

Use
```
deferred-finding
```
skill to create tracking issue
Link tracking issue in artifact
"Deferred without tracking issue" is NOT PERMITTED

使用

apply-all-findings

skill处理所有问题。

对于无法修复的问题：

使用
```
deferred-finding
```
skill创建跟踪Issue
在审查成果中关联该跟踪Issue
不允许“未关联跟踪Issue的延期处理”

Step 6: Post Artifact to Issue (MANDATORY)

步骤6：将审查成果发布至Issue（强制要求）

Post review artifact as comment on the GitHub issue:

bash

ISSUE_NUMBER=123
gh issue comment $ISSUE_NUMBER --body "$(cat <<'EOF'
<!-- REVIEW:START -->

将审查成果作为评论发布至GitHub Issue：

bash

ISSUE_NUMBER=123
gh issue comment $ISSUE_NUMBER --body "$(cat <<'EOF'
<!-- REVIEW:START -->

Code Review Complete

Property	Value
Worker	`[WORKER_ID]`
Issue	#123
Scope	[MINOR
Security-Sensitive	[YES
Reviewed	[ISO_TIMESTAMP]

Property	Value
Worker	`[WORKER_ID]`
Issue	#123
Scope	[MINOR
Security-Sensitive	[YES
Reviewed	[ISO_TIMESTAMP]

Criteria Results

#	Criterion	Status	Findings
1	Blindspots	[✅ PASS	✅ FIXED
2	Clarity	[✅ PASS	✅ FIXED
3	Maintainability	[✅ PASS	✅ FIXED
4	Security	[✅ PASS	✅ FIXED
5	Performance	[✅ PASS	✅ FIXED
6	Documentation	[✅ PASS	✅ FIXED
7	Style	[✅ PASS	✅ FIXED

#	Criterion	Status	Findings
1	Blindspots	[✅ PASS	✅ FIXED
2	Clarity	[✅ PASS	✅ FIXED
3	Maintainability	[✅ PASS	✅ FIXED
4	Security	[✅ PASS	✅ FIXED
5	Performance	[✅ PASS	✅ FIXED
6	Documentation	[✅ PASS	✅ FIXED
7	Style	[✅ PASS	✅ FIXED

Findings Fixed in This PR

#	Severity	Finding	Resolution
1	[SEVERITY]	[DESCRIPTION]	[HOW_FIXED]

#	Severity	Finding	Resolution
1	[SEVERITY]	[DESCRIPTION]	[HOW_FIXED]

Findings Deferred (With Tracking Issues)

#	Severity	Finding	Tracking Issue	Justification
1	[SEVERITY]	[DESCRIPTION]	#[ISSUE]	[WHY]

#	Severity	Finding	Tracking Issue	Justification
1	[SEVERITY]	[DESCRIPTION]	#[ISSUE]	[WHY]

Summary

Category	Count
Fixed in PR	[N]
Deferred (with tracking)	[N]
Unaddressed	0

Review Status: ✅ COMPLETE

EOF )"


**CRITICAL:** "Unaddressed" MUST be 0. "Review Status" MUST be "COMPLETE".

Category	Count
Fixed in PR	[N]
Deferred (with tracking)	[N]
Unaddressed	0

Review Status: ✅ COMPLETE

EOF )"


**关键要求：** “未处理问题”必须为0。“审查状态”必须为“COMPLETE”。

Severity Levels

严重程度等级

Severity	Description	Action
Critical	Security issue, data loss, crash	Must fix before merge
Major	Significant bug, performance issue	Must fix before merge
Minor	Style, clarity, small improvement	Should fix before merge

严重程度	描述	处理方式
Critical（严重）	安全问题、数据丢失、程序崩溃	合并前必须修复
Major（主要）	重大bug、性能问题	合并前必须修复
Minor（次要）	风格、清晰度、小改进	合并前应修复

Checklist

检查清单

Integration

集成

This skill is called by:

```
issue-driven-development
```
- Step 9

This skill uses:

```
review-scope
```
- Determine review breadth
```
apply-all-findings
```
- Address issues
```
security-review
```
- For security-sensitive changes
```
deferred-finding
```
- For creating tracking issues

This skill is enforced by:

```
review-gate
```
- Verifies artifact before PR
```
PreToolUse
```
hook - Blocks PR without artifact

This skill references:

```
inline-documentation
```
- Documentation standards
```
strict-typing
```
- Type requirements
```
style-guide-adherence
```
- Style requirements
```
inclusive-language
```
- Language requirements
```
ipv6-first
```
- Network code requirements (IPv6 primary, IPv4 legacy)

本skill由以下模块调用：

```
issue-driven-development
```
- 步骤9

本skill使用以下模块：

```
review-scope
```
- 确定审查范围
```
apply-all-findings
```
- 处理问题
```
security-review
```
- 针对安全敏感变更
```
deferred-finding
```
- 创建跟踪Issue

本skill由以下模块强制执行：

```
review-gate
```
- PR创建前验证审查成果
```
PreToolUse
```
钩子 - 无审查成果时阻止创建PR

本skill参考以下模块：

```
inline-documentation
```
- 文档标准
```
strict-typing
```
- 类型要求
```
style-guide-adherence
```
- 风格要求
```
inclusive-language
```
- 语言要求
```
ipv6-first
```
- 网络代码要求（IPv6优先，IPv4仅用于遗留场景）