Self Code Review

代码自审

Quick Start

快速开始

Perform systematic self-review of code changes before commits using a structured 8-step checklist.

Most common use case:

User: "Review my changes before I commit"

→ Run git diff to see changes
→ Execute 8-step review (architecture, quality, tests, docs, anti-patterns, gates)
→ Generate structured report with pass/fail/warnings
→ Fix issues before committing

Result: Clean, quality-validated commit

在提交代码变更前，使用结构化的8步检查表进行系统性自审。

最常见使用场景：

用户：“提交前帮我审核下变更内容”

→ 运行git diff查看变更
→ 执行8步审核（架构、质量、测试、文档、反模式、质量门禁）
→ 生成包含通过/失败/警告的结构化报告
→ 修复问题后再提交

结果：提交经过质量验证的干净代码

When to Use This Skill

何时使用该技能

Mandatory situations:

Before every commit
Before creating pull requests
Before merging to main/master
After completing feature implementation

User trigger phrases:

"review my changes"
"self-review"
"check my code"
"validate before commit"
"code review"
"ready to commit?"

强制使用场景：

每次提交代码前
创建Pull Request前
合并到main/master分支前
功能实现完成后

用户触发短语：

"review my changes"
"self-review"
"check my code"
"validate before commit"
"code review"
"ready to commit?"

What This Skill Does

该技能的作用

Systematic 8-step review process:

Change Discovery - Identify all modified files via git diff
Architectural Review - Validate layer boundaries and dependency rules
Code Quality Review - Check style, logic, performance, security
Test Coverage Review - Ensure comprehensive test coverage
Documentation Review - Validate docstrings, README, comments
Anti-Pattern Detection - Find universal and project-specific anti-patterns
Quality Gates - Run automated checks (mypy, ruff, pytest)
Review Report Generation - Structured pass/fail/warning summary

系统性的8步审核流程：

变更发现 - 通过git diff识别所有修改的文件
架构审核 - 验证分层边界和依赖规则
代码质量审核 - 检查代码风格、逻辑、性能、安全性
测试覆盖率审核 - 确保全面的测试覆盖
文档审核 - 验证文档字符串、README、注释
反模式检测 - 发现通用和项目特定的反模式
质量门禁 - 运行自动化检查（mypy、ruff、pytest）
审核报告生成 - 结构化的通过/失败/警告汇总

Review Process

审核流程

Step 1: Change Discovery

步骤1：变更发现

Identify modified files:

bash

undefined

识别修改的文件：

bash

undefined

See all changes

查看所有变更文件

git diff --name-only

See detailed changes

查看详细变更内容

git diff

See staged changes

查看已暂存的变更

git diff --staged


**Output:** List of modified files for review

git diff --staged


**输出：** 待审核的修改文件列表

Step 2: Architectural Review

步骤2：架构审核

Check layer boundaries (Clean Architecture projects):

Domain layer has no external dependencies
Application layer doesn't import from infrastructure
Infrastructure implements interfaces from domain
Interface layer depends only on application/infrastructure

Use validate-architecture skill if available

Checklist:

No circular dependencies between layers
Domain layer imports only from domain
Application imports from domain only
Infrastructure implements domain protocols
No business logic in interface layer

检查分层边界（整洁架构项目）：

领域层无外部依赖
应用层不导入基础设施层代码
基础设施层实现领域层定义的接口
接口层仅依赖应用层/基础设施层

若有validate-architecture技能可配合使用

检查清单：

分层之间无循环依赖
领域层仅导入领域层内部代码
应用层仅导入领域层代码
基础设施层实现领域层协议
接口层无业务逻辑

Step 3: Code Quality Review

步骤3：代码质量审核

Step 4: Test Coverage Review

步骤4：测试覆盖率审核

Required test types:

Unit tests - Test business logic in isolation
Integration tests - Test with real dependencies (if applicable)
E2E tests - Test through public interface (if applicable)

Coverage checklist:

Happy path tested
Edge cases tested (empty, null, boundary values)
Error cases tested (failures, exceptions)
All public methods/functions tested
Coverage 80%+ for new code

Run tests:

bash

pytest tests/ -v --cov=src --cov-report=term-missing

必需的测试类型：

单元测试 - 孤立测试业务逻辑
集成测试 - 结合真实依赖测试（如适用）
端到端测试 - 通过公共接口测试（如适用）

覆盖检查清单：

测试了正常流程
测试了边缘情况（空值、null、边界值）
测试了错误场景（失败、异常）
所有公共方法/函数都有测试
新代码覆盖率达80%以上

运行测试：

bash

pytest tests/ -v --cov=src --cov-report=term-missing

Step 5: Documentation Review

步骤5：文档审核

Docstrings:

All public functions/classes have docstrings
Docstrings describe purpose (not implementation)
Complex logic has inline comments explaining "why" not "what"
No redundant docstrings (don't repeat what code says)

README updates:

New features documented
API changes reflected
Examples updated if needed

文档字符串：

所有公共函数/类都有文档字符串
文档字符串描述用途（而非实现细节）
复杂逻辑有行内注释解释“为什么”而非“做什么”
无冗余文档字符串（不重复代码内容）

README更新：

新增功能已文档化
API变更已体现
示例已按需更新

Step 6: Anti-Pattern Detection

步骤6：反模式检测

Universal anti-patterns:

God Classes - Classes with 10+ methods or 300+ lines
Long Methods - Functions 50+ lines
Deep Nesting - 4+ levels of indentation
Duplicate Code - Same logic in multiple places
Magic Numbers - Unexplained constants
Commented Code - Code commented out instead of deleted
Inconsistent Naming - Mixed conventions (camelCase vs snake_case)
Mutable Defaults (Python) -
```
def func(arg=[])
```
Bare Except -
```
except:
```
without specific exception
Missing Type Hints (Python/TypeScript) - Functions without types

Project-specific anti-patterns (check ARCHITECTURE.md):

Fail-fast violations (try/except around imports)
Missing ServiceResult usage
Direct database access (bypassing repository)
Missing dependency injection
Skipping validation in constructors

通用反模式：

上帝类 - 包含10个以上方法或300行以上代码的类
长方法 - 50行以上的函数
深层嵌套 - 4层以上缩进
重复代码 - 多处存在相同逻辑
魔法数字 - 未解释的常量
注释代码 - 被注释而非删除的代码
命名不一致 - 混合规范（camelCase与snake_case）
可变默认值（Python） -
```
def func(arg=[])
```
裸Except -
```
except:
```
未指定具体异常
缺失类型提示（Python/TypeScript） - 函数无类型定义

项目特定反模式（查看ARCHITECTURE.md）：

违反快速失败原则（导入周围使用try/except）
未使用ServiceResult
直接访问数据库（绕过仓库层）
缺失依赖注入
构造函数中跳过验证

Step 7: Quality Gates

步骤7：质量门禁

Run automated checks:

bash

undefined

运行自动化检查：

bash

undefined

Type checking

类型检查

mypy src/

Linting

代码检查

ruff check src/

Tests

测试

pytest tests/

Coverage

覆盖率

pytest --cov=src --cov-report=term-missing


**Pass criteria:**
- [ ] 0 type errors
- [ ] 0 linting errors (or justified suppressions)
- [ ] All tests passing
- [ ] Coverage 80%+ for new code

pytest --cov=src --cov-report=term-missing


**通过标准：**
- [ ] 0个类型错误
- [ ] 0个代码检查错误（或已合理屏蔽）
- [ ] 所有测试通过
- [ ] 新代码覆盖率达80%以上

Step 8: Review Report Generation

步骤8：审核报告生成

Generate structured report with findings:

Report template:

undefined

生成包含检查结果的结构化报告：

报告模板：

undefined

Code Review Report

代码审核报告

Passed Checks (N/8)

通过的检查项（N/8）

✅ Change Discovery: 5 files modified
✅ Architectural Review: No layer boundary violations
✅ Code Quality: No style/logic issues
✅ Test Coverage: 85% coverage, all cases tested
✅ Documentation: All public APIs documented
✅ Anti-Patterns: No universal anti-patterns detected
✅ Quality Gates: mypy, ruff, pytest all passing

✅ 变更发现：修改了5个文件
✅ 架构审核：无分层边界违规
✅ 代码质量：无风格/逻辑问题
✅ 测试覆盖率：覆盖率85%，所有场景已测试
✅ 文档：所有公共API已文档化
✅ 反模式：未检测到通用反模式
✅ 质量门禁：mypy、ruff、pytest全部通过

Failed Checks (N/8)

未通过的检查项（N/8）

❌ Test Coverage: Missing edge case tests for empty input
❌ Quality Gates: 2 mypy type errors in handlers.py

❌ 测试覆盖率：缺失空输入的边缘情况测试
❌ 质量门禁：handlers.py中存在2个mypy类型错误

Warnings (N)

警告（N）

⚠️ Performance: Potential N+1 query in repository method
⚠️ Documentation: README not updated for new feature

⚠️ 性能：仓库方法中存在潜在的N+1查询
⚠️ 文档：README未更新新增功能

Summary

总结

Status: BLOCKED (2 failures)
Action Required:
1. Add edge case tests for empty input
2. Fix type errors in handlers.py
3. Review N+1 query issue
4. Update README

DO NOT COMMIT until all failures resolved.

undefined

状态： 阻塞（2项未通过）
需执行操作：
1. 添加空输入的边缘情况测试
2. 修复handlers.py中的类型错误
3. 排查N+1查询问题
4. 更新README

未解决所有问题前禁止提交

undefined

Integration with Other Skills

与其他技能的集成

Combine with other validation skills:

validate-architecture - Automated layer boundary checking
run-quality-gates - Comprehensive quality validation
detect-refactor-markers - Find REFACTOR comments and associated ADRs
detect-srp - Find Single Responsibility Principle violations
verify-integration - Ensure components are connected, not just created

Workflow:

Make changes
Run
```
quality-code-review
```
skill (this skill)
If architecture issues found → Use
```
validate-architecture
```
for details
Fix all issues
Run
```
quality-code-review
```
again
Commit when all checks pass

与其他验证技能配合使用：

validate-architecture - 自动化分层边界检查
run-quality-gates - 全面的质量验证
detect-refactor-markers - 查找REFACTOR注释及相关ADR
detect-srp - 查找违反单一职责原则的情况
verify-integration - 确保组件已正确连接而非仅创建

工作流程：

进行代码变更
运行
```
quality-code-review
```
技能（本技能）
若发现架构问题 → 使用
```
validate-architecture
```
获取详细分析
修复所有问题
再次运行
```
quality-code-review
```
所有检查通过后提交

Language-Specific Adaptations

语言特定适配

Python Projects

Python项目

Additional checks:

Type hints on all functions (mypy --strict)
No mutable default arguments
Proper
```
__init__
```
validation
Use
```
Protocol
```
for interfaces
Dataclasses for value objects

额外检查项：

所有函数添加类型提示（mypy --strict）
无可变默认参数
正确的
```
__init__
```
验证
使用
```
Protocol
```
定义接口
数据类作为值对象

JavaScript/TypeScript Projects

JavaScript/TypeScript项目

Additional checks:

TypeScript strict mode enabled
No
```
any
```
types (use proper types)
Proper error handling (no silent failures)
ESLint rules passing
Jest tests with 80%+ coverage

额外检查项：

启用TypeScript严格模式
无
```
any
```
类型（使用正确类型）
正确的错误处理（无静默失败）
通过ESLint规则检查
Jest测试覆盖率达80%以上

Go Projects

Go项目

Additional checks:

Error handling for all errors (no ignored
```
err
```
)
Proper struct naming (exported vs unexported)
Tests in
```
_test.go
```
files
No global state (use dependency injection)

额外检查项：

所有错误都已处理（无忽略的
```
err
```
）
正确的结构体命名（导出与非导出）
测试文件位于
```
_test.go
```
中
无全局状态（使用依赖注入）

Rust Projects

Rust项目

Additional checks:

No
```
unwrap()
```
in production code (handle Results)
Proper error propagation with
```
?
```
Clippy warnings addressed
All tests passing

额外检查项：

生产代码中无
```
unwrap()
```
（处理Results）
使用
```
?
```
正确传播错误
处理Clippy警告
所有测试通过

Expected Outcomes

预期结果

All Checks Passing

所有检查通过

undefined

undefined

Code Review Report

代码审核报告

Passed Checks (8/8)

通过的检查项（8/8）

✅ Change Discovery: 3 files modified
✅ Architectural Review: No violations
✅ Code Quality: Clean code, no issues
✅ Test Coverage: 92% coverage
✅ Documentation: All APIs documented
✅ Anti-Patterns: None detected
✅ Quality Gates: All passing
✅ Report Generated: Review complete

✅ 变更发现：修改了3个文件
✅ 架构审核：无违规
✅ 代码质量：代码整洁，无问题
✅ 测试覆盖率：覆盖率92%
✅ 文档：所有API已文档化
✅ 反模式：未检测到
✅ 质量门禁：全部通过
✅ 报告生成：审核完成

Summary

总结

Status: READY TO COMMIT
Changes: 3 files, 150 lines added, 20 lines deleted
Test Coverage: 92% (target 80%+)
Quality: All gates passing

PROCEED WITH COMMIT

undefined

状态： 可提交
变更： 3个文件，新增150行，删除20行
测试覆盖率： 92%（目标80%+）
质量： 所有门禁通过

可以提交代码

undefined

Checks Failing

检查未通过

undefined

undefined

Code Review Report

代码审核报告

Passed Checks (5/8)

通过的检查项（5/8）

✅ Change Discovery: 5 files modified
✅ Architectural Review: No violations
✅ Documentation: Properly documented

✅ 变更发现：修改了5个文件
✅ 架构审核：无违规
✅ 文档：已正确更新

Failed Checks (3/8)

未通过的检查项（3/8）

❌ Test Coverage: Only 45% coverage (target 80%+)
- Missing tests for error scenarios
- No integration tests
❌ Quality Gates: 3 mypy type errors
- src/handlers.py:45 - Missing return type
- src/models.py:12 - Incompatible types
❌ Anti-Patterns: 2 issues
- God class detected: UserService (18 methods)
- Duplicate code in parse_input() and validate_input()

❌ 测试覆盖率：仅45%覆盖率（目标80%+）
- 缺失错误场景测试
- 无集成测试
❌ 质量门禁：3个mypy类型错误
- src/handlers.py:45 - 缺失返回类型
- src/models.py:12 - 类型不兼容
❌ 反模式：2个问题
- 检测到上帝类：UserService（18个方法）
- parse_input()与validate_input()存在重复代码

Summary

总结

Status: BLOCKED
Action Required:
1. Add tests for error scenarios (increase coverage to 80%+)
2. Fix 3 mypy type errors
3. Refactor UserService (split responsibilities)
4. Extract common parsing logic to shared utility

DO NOT COMMIT - Fix issues first

undefined

状态： 阻塞
需执行操作：
1. 添加错误场景测试（将覆盖率提升至80%+）
2. 修复3个mypy类型错误
3. 重构UserService（拆分职责）
4. 提取公共解析逻辑到共享工具类

禁止提交 - 先修复所有问题

undefined

Troubleshooting

故障排除

Issue: Quality gates failing with many errors

问题：质量门禁出现大量错误

Symptom: mypy/ruff/pytest show 10+ errors

Solution:

Fix one category at a time (start with type errors)
Run incremental checks:
```
mypy src/module.py
```
Use
```
ruff check --fix
```
for auto-fixable issues
Prioritize test failures (may cascade from type issues)

症状： mypy/ruff/pytest显示10个以上错误

解决方案：

逐个类别修复（从类型错误开始）
运行增量检查：
```
mypy src/module.py
```
使用
```
ruff check --fix
```
修复可自动修复的问题
优先处理测试失败（可能由类型问题引发）

Issue: Low test coverage but tests exist

问题：测试覆盖率低但已编写测试

Symptom: Coverage 40-60% despite writing tests

Solution:

Check which lines aren't covered:
```
pytest --cov=src --cov-report=html
```
Open
```
htmlcov/index.html
```
to see missing lines
Add tests for error branches and edge cases
Test all public methods, not just happy path

症状： 尽管编写了测试，覆盖率仍为40-60%

解决方案：

查看未覆盖的代码行：
```
pytest --cov=src --cov-report=html
```
打开
```
htmlcov/index.html
```
查看缺失的覆盖行
为错误分支和边缘情况添加测试
测试所有公共方法，而非仅正常流程

Issue: Architecture violations unclear

问题：架构违规不明确

Symptom: "Layer boundary violation detected" but unsure where

Solution:

Use
```
validate-architecture
```
skill for detailed analysis
Check import statements in flagged files
Review ARCHITECTURE.md for project-specific rules
Compare with existing code in same layer

症状： 提示“检测到分层边界违规”但不清楚具体位置

解决方案：

使用
```
validate-architecture
```
技能获取详细分析
检查标记文件中的导入语句
查看ARCHITECTURE.md中的项目特定规则
与同层现有代码进行对比

Supporting Files

支持文件

references/review-checklist.md - Comprehensive checklists:
- Detailed language-specific checks (Python, JS/TS, Go, Rust)
- Project-specific anti-pattern catalog
- Security checklist (OWASP top 10)
- Performance optimization checklist
- Accessibility checklist (for UI code)
scripts/detect_project_type.sh - Project detection script:
- Runs all quality gates
- Generates coverage report
- Checks git diff
- Outputs structured report

references/review-checklist.md - 综合检查表：
- 详细的语言特定检查（Python、JS/TS、Go、Rust）
- 项目特定反模式目录
- 安全检查表（OWASP top 10）
- 性能优化检查表
- 可访问性检查表（针对UI代码）
scripts/detect_project_type.sh - 项目检测脚本：
- 运行所有质量门禁
- 生成覆盖率报告
- 检查git diff
- 输出结构化报告

Red Flags to Avoid

需避免的红色警示

Skipping review before commits - Technical debt compounds
Ignoring quality gate failures - "I'll fix it later" never happens
Reviewing only happy path - Edge cases cause production bugs
Skipping test coverage check - Untested code will break
Approving own code without checklist - Systematic review catches issues
Committing with failing tests - Breaks CI/CD pipeline
Ignoring architectural violations - Erodes system design over time
Skipping documentation updates - Makes code unmaintainable
Accepting "good enough" code - Quality degrades incrementally
Not using automated tools - Manual review misses issues

Key principle: Systematic review catches issues before they reach production. 10 minutes of review saves hours of debugging.

Remember: Every commit is a checkpoint. Make each one clean, tested, and production-ready.

提交前跳过审核 - 技术债务会不断累积
忽略质量门禁失败 - “以后再修”往往不会实现
仅审核正常流程 - 边缘情况会导致生产环境bug
跳过测试覆盖率检查 - 未测试的代码必然会出问题
不使用检查表就批准自己的代码 - 系统性审核能发现更多问题
测试失败仍提交 - 会破坏CI/CD流水线
忽略架构违规 - 长期会侵蚀系统设计
跳过文档更新 - 会导致代码难以维护
接受“足够好”的代码 - 质量会逐步下降
不使用自动化工具 - 手动审核会遗漏问题

核心原则： 系统性审核能在问题进入生产环境前发现它们。10分钟的审核能节省数小时的调试时间。

谨记： 每次提交都是一个检查点。确保每个提交的代码都是干净、经过测试且可投入生产的。

quality-code-review

Original

Translation

Self Code Review

代码自审

Quick Start

快速开始

When to Use This Skill

何时使用该技能

What This Skill Does

该技能的作用

Review Process

审核流程

Step 1: Change Discovery

步骤1：变更发现

See all changes

查看所有变更文件

See detailed changes

查看详细变更内容

See staged changes

查看已暂存的变更

Step 2: Architectural Review

步骤2：架构审核

Step 3: Code Quality Review

步骤3：代码质量审核

Step 4: Test Coverage Review

步骤4：测试覆盖率审核

Step 5: Documentation Review

步骤5：文档审核

Step 6: Anti-Pattern Detection

步骤6：反模式检测

Step 7: Quality Gates

步骤7：质量门禁

Type checking

类型检查

Linting

代码检查

Tests

测试

Coverage

覆盖率

Step 8: Review Report Generation

步骤8：审核报告生成

Code Review Report

代码审核报告

Passed Checks (N/8)

通过的检查项（N/8）

Failed Checks (N/8)

未通过的检查项（N/8）

Warnings (N)

警告（N）

Summary

总结

Integration with Other Skills

与其他技能的集成

Language-Specific Adaptations

语言特定适配

Python Projects

Python项目

JavaScript/TypeScript Projects

JavaScript/TypeScript项目

Go Projects

Go项目

Rust Projects

Rust项目

Expected Outcomes

预期结果

All Checks Passing

所有检查通过

Code Review Report

代码审核报告

Passed Checks (8/8)

通过的检查项（8/8）

Summary

总结

Checks Failing

检查未通过

Code Review Report

代码审核报告

Passed Checks (5/8)