ai-code-review

ai-code-review

执行严格的代码审查，确保代码符合质量标准。质疑假设，验证正确性，并确保代码简洁、经过测试且易于维护。

适用场景

在以下情况下使用此技能：

• 收到审查拉取请求、差异或一组更改的请求
• 收到审查特定文件或功能实现的请求
• 在向用户提交代码前进行自我审查
• 在执行阶段验证代码质量

说明

步骤 1：运行自动化检查

进行任何人工审查前，先确认自动化质量门禁均已通过。

1. Lint 检查。 运行项目配置的 Lint 工具（例如 eslint、phpcs、phpstan、prettier --check、stylelint）。报告所有违规项。解决或明确说明 Lint 错误之前，不要继续。
2. 类型检查。 如果项目使用静态类型（TypeScript、PHPStan、mypy），运行类型检查器。不允许出现类型错误。
3. 单元测试。 运行测试套件。所有现有测试都必须通过。如果新增代码缺少测试，将其标记为阻塞问题（见步骤 4）。
4. 构建。 如适用，确认项目可以成功编译或构建，且没有错误或警告。

如果任何自动化检查失败，请停止审查并报告失败项。在代码通过所有检查之前，不要继续人工审查。

步骤 2：审查复杂度

评估代码在满足需求的前提下是否尽可能简单。

1. 圈复杂度。 标记分支超过 10 个的函数或方法。建议拆分或简化。
2. 函数长度。 标记超过 40 行的函数。每个函数都应只做一件事。
3. 嵌套深度。 标记嵌套超过 3 层的代码。建议使用提前返回、保护子句或拆分代码。
4. 参数数量。 标记参数超过 4 个的函数。建议使用选项对象、构建器或拆分职责。
5. 认知负担。 假设自己是第一次阅读这段代码。如果需要反复阅读某个代码块才能理解，它就过于复杂。建议重命名、重构；只有作为最后手段时才添加说明性注释。
6. 重复代码。 找出重复逻辑（出现 3 次以上，或重复 5 行以上）。建议提取到共享函数、方法或模块中。

步骤 3：审查正确性

验证代码是否实现了其声称的功能。

1. 边界情况。 找出代码未处理的输入或状态：空值、空集合、边界值、并发访问、错误路径。
2. 错误处理。 验证错误是否被捕获、记录，并得到妥善恢复或有意义地向上传递。不得吞掉异常。不得使用不重新抛出异常的通用捕获逻辑。
3. 副作用。 找出意外的修改、全局状态变更，或隐藏在看似纯函数中的 I/O 操作。
4. 安全性。 检查注入漏洞（SQL、XSS、命令）、未经清理的用户输入、泄露的机密，以及缺失的授权检查。
5. 性能。 标记明显的低效问题：N+1 查询、循环中的不必要分配、缺少分页、内存中无界增长的集合。

步骤 4：审查测试覆盖率

评估代码是否经过充分测试。

1. 新行为必须有测试。 每个新增的公共函数、方法、端点或行为路径至少需要一个测试。标记缺少测试的项目。
2. 测试质量。 测试必须断言有意义的结果，而不只是确认代码运行时不会崩溃。标记没有断言或只有简单断言的测试。
3. 边界情况覆盖。 测试至少应覆盖：正常路径、一种错误或失败路径，以及一种边界条件。
4. 测试隔离。 测试不得依赖执行顺序、共享的可变状态，或未使用模拟替身的外部服务。
5. 命名。 测试名称必须描述场景和预期结果（例如，should return 404 when order does not exist）。

第 5 步：检查设计与规范

确认代码符合代码库的要求，并遵循既定模式。

1. 一致性。 代码是否遵循项目中已有的命名规范、文件结构和模式？指出偏离之处。
2. 关注点分离。 业务逻辑是否与基础设施、表现层或编排代码混杂？指出违反之处。
3. API 设计。 公共接口（函数签名、类 API、HTTP 端点）是否清晰、精简且不易误用？
4. 依赖方向。 依赖是否按照项目架构（例如，六边形架构、分层架构）指向正确方向？
5. SOLID 原则。 指出违反单一职责原则、抽象不合理或使用继承而非组合更合适的类或模块。

第 6 步：质疑工程师

不要只找问题，还要主动质疑设计和方案。

1. 追问“为什么”。 对任何不明显的设计决策，都要求作者说明理由。例如：
   • “为什么要把它做成独立服务，而不是现有聚合上的一个方法？”
   • “这里为什么选择继承而不是组合？”
   • “如果这个外部调用失败会怎样？”
2. 提出替代方案。 发现问题时，不要只指出问题，还要给出具体替代方案并说明理由。
3. 质疑必要性。 对于每个新增的依赖、抽象或层，都要问：“现在真的需要它吗，还是只是在预作设计？”如果只是预作设计，建议移除。
4. 模拟故障。 选择一条关键路径，在脑中（或实际）追踪其失败时的情况。报告任何未处理的故障模式。
5. 要求证明复杂性的必要性。 如果方案很复杂，作者必须证明更简单的方案行不通。不能默认接受复杂性。

第 7 步：生成审查摘要

输出包含明确严重程度级别的结构化审查结果。

## Review Summary

### Blocking (must fix before merge)
- [ ] Issue description — file:line — suggested fix

### Should fix (strongly recommended)
- [ ] Issue description — file:line — suggested fix

### Nitpick (optional improvements)
- [ ] Issue description — file:line — suggested fix

### Questions (need clarification)
- [ ] Question — file:line

### Positive observations
- What was done well

严重程度规则：

• 阻塞： 测试失败、lint 错误、类型错误、新代码缺少测试、安全问题、功能损坏、存在数据丢失风险。
• 应修复： 复杂性问题、命名不佳、缺少错误处理、设计问题、性能问题。
• 小建议： 超出 linter 检查范围的风格偏好、轻微的可读性改进、文档建议。

第 8 步：验证问题是否已解决

如果工程师采纳了你的反馈：

1. 重新运行自动化检查（第 1 步）。
2. 验证每个阻塞问题均已解决。
3. 确认“应修复”项已处理，或已明确说明推迟处理的理由。
4. 仅当所有阻塞问题均已解决且没有引入新问题时，才予以批准。

审查原则

• 严格，但不刻薄。 目标是提升质量，而不是把关刁难。每条反馈都必须可执行且有依据。
• 不敷衍通过。 未经全面审查，绝不批准。“看起来不错”不是有效的审查意见。
• 假设存在缺陷。 以代码中可能存在问题的心态进行审查——你的任务就是找出问题。
• 越简单越好。 有疑虑时，优先主张更简单的方案。
• 代码被阅读的次数多于编写的次数。 优化代码，让下一个阅读它的人受益，而不是只考虑当前编写代码的人。