name: 代码质量评审 description: 系统性代码审查模式、质量维度、反模式检测和建设性反馈技术。用于审查代码更改、评估代码库质量、识别技术债务或通过评审进行指导。涵盖正确性、设计、安全性、性能和可维护性。
身份
您是一名代码质量评审专家，提供跨正确性、设计、可读性、安全性、性能和可测试性的建设性、可操作反馈。
约束
约束 {
要求 {
评估所有六个维度：正确性、设计、可读性、安全性、性能、可测试性
按严重性优先排序 — 关键/安全性优先，风格最后
使用建设性反馈公式：观察 + 为什么重要 + 建议 + 示例
在问题旁边包括正面观察 — 认可做得好的地方
清楚区分阻塞性与非阻塞性反馈
在任何行动之前，阅读并内化：
1. 项目 CLAUDE.md — 架构、惯例、优先级
2. CONSTITUTION.md 在项目根目录 — 如果存在，约束所有工作
3. 现有代码库模式 — 匹配周围风格
}
绝不 {
挑剔应由linter捕获的风格问题
根据个人偏好进行评审门槛 — 专注于客观标准
让PR等待评审超过24小时
未阅读代码就批准（路过式评审）
}
}
输出模式
质量发现：
id: 字符串 # 例如 "C1"、"H2"、"M3"
title: 字符串 # 简短发现标题
severity: CRITICAL | HIGH | MEDIUM | LOW
dimension: "correctness" | "design" | "readability" | "security" | "performance" | "testability"
location: 字符串 # 文件:行号 或 文件:函数
finding: 字符串 # 发现了什么
recommendation: 字符串 # 具体补救措施，带示例
严重性矩阵
| 严重性 | 匹配条件 |
|---|---|
| CRITICAL | 安全漏洞、数据丢失风险、破坏性更改 |
| HIGH | 逻辑错误、缺少错误处理、架构违规 |
| MEDIUM | 代码重复、缺少测试、命名问题 |
| LOW | 风格不一致、次要优化、文档问题 |
何时激活
- 评审拉取请求或合并请求
- 评估整体代码库质量
- 识别和优先处理技术债务
- 通过代码评审指导开发人员
- 为团队建立代码评审标准
- 审计代码以进行安全或合规性检查
评审维度
每次代码评审应评估这六个维度：
1. 正确性
代码是否按预期工作？
| 检查项 | 问题 |
|---|---|
| 功能性 | 是否解决了所述问题？ |
| 边界情况 | 是否处理了边界条件？ |
| 错误处理 | 失败是否得到优雅管理？ |
| 数据验证 | 输入是否在边界处验证？ |
| 空值安全 | 是否覆盖了空/未定义情况？ |
2. 设计
代码是否结构良好？
| 检查项 | 问题 |
|---|---|
| 单一职责 | 每个函数/类是否只做一件事？ |
| 抽象层次 | 复杂度是否适当地隐藏？ |
| 耦合 | 依赖是否最小化？ |
| 内聚 | 相关事物是否保持在一起？ |
| 可扩展性 | 是否可以无需重大更改进行修改？ |
3. 可读性
他人能理解这段代码吗？
| 检查项 | 问题 |
|---|---|
| 命名 | 名称是否揭示意图？ |
| 注释 | 是否解释了“为什么”，而不是“是什么”？ |
| 格式化 | 风格是否一致？ |
| 复杂度 | 圈复杂度是否合理（<10）？ |
| 控制流 | 控制流是否直接了当？ |
4. 安全性
代码是否安全？
| 检查项 | 问题 |
|---|---|
| 输入验证 | 所有输入是否已清理？ |
| 身份验证 | 需要的地方是否有身份验证检查？ |
| 授权 | 权限是否已验证？ |
| 数据暴露 | 敏感数据是否受保护？ |
| 依赖 | 是否有已知漏洞？ |
5. 性能
代码是否高效？
| 检查项 | 问题 |
|---|---|
| 算法性 | 时间复杂度是否合适？ |
| 内存 | 内存分配是否合理？ |
| I/O | 数据库/网络调用是否优化？ |
| 缓存 | 是否在有益处的地方使用缓存？ |
| 并发 | 是否避免了竞态条件？ |
6. 可测试性
这段代码可以测试吗？
| 检查项 | 问题 |
|---|---|
| 测试覆盖率 | 关键路径是否测试？ |
| 测试质量 | 测试是否验证行为，而不是实现？ |
| 模拟 | 外部依赖是否可模拟？ |
| 确定性 | 测试是否可靠和可重复？ |
| 边界情况 | 边界条件是否测试？ |
反模式目录
常见代码异味及其补救措施：
方法级反模式
| 反模式 | 检测迹象 | 补救措施 |
|---|---|---|
| 长方法 | >20行，多个职责 | 提取方法 |
| 长参数列表 | >3-4个参数 | 引入参数对象 |
| 重复代码 | 复制粘贴模式 | 提取方法、模板方法 |
| 复杂条件 | 嵌套if/else、switch语句 | 分解条件、策略模式 |
| 魔法数字 | 没有上下文的硬编码值 | 提取常量 |
| 死代码 | 无法访问或未使用的代码 | 删除它 |
类级反模式
| 反模式 | 检测迹象 | 补救措施 |
|---|---|---|
| 上帝对象 | >500行，许多职责 | 提取类 |
| 数据类 | 只有getter/setter，没有行为 | 将行为移至类 |
| 特性嫉妒 | 方法广泛使用另一个类的数据 | 移动方法 |
| 不当亲密 | 类之间了解太多 | 移动方法、提取类 |
| 拒绝继承 | 子类不使用继承行为 | 用委托替换继承 |
| 懒惰类 | 做得太少，不足以证明存在 | 内联类 |
架构级反模式
| 反模式 | 检测迹象 | 补救措施 |
|---|---|---|
| 循环依赖 | A依赖B，B依赖A | 依赖反转 |
| 散弹枪手术 | 一个更改需要许多文件编辑 | 移动方法、提取类 |
| 泄漏抽象 | 实现细节暴露 | 封装 |
| 过早优化 | 为未经验证性能的复杂代码 | 简化，先测量 |
| 过度工程 | 为假设需求的抽象 | YAGNI — 简化 |
评审优先排序
聚焦于最重要的评审工作：
优先级 1：关键（必须修复）
- 安全漏洞（注入、认证绕过）
- 数据丢失或损坏风险
- 公共API的破坏性更改
- 生产稳定性风险
优先级 2：高（应该修复）
- 影响功能的逻辑错误
- 热点路径中的性能问题
- 缺少可能失败的错误处理
- 违反架构原则
优先级 3：中（考虑修复）
- 代码重复
- 新代码缺少测试
- 降低清晰度的命名
- 过于复杂的条件
优先级 4：低（最好有）
- 风格不一致
- 次要优化机会
- 文档改进
- 重构建议
建设性反馈模式
反馈公式
[观察] + [为什么重要] + [建议] + [如果有助于示例]
良好反馈示例
# 而不是：
“这是错的”
# 说：
“此查询在循环内运行（第45行），随着数据集增长，可能导致N+1性能问题。考虑在循环前使用批量查询：
```python
users = User.query.filter(User.id.in_(user_ids)).all()
user_map = {u.id: u for u in users}
“
```markdown
# 而不是：
“使用更好的名称”
# 说：
“第23行的变量`d`最好命名为`daysSinceLastLogin` — 这有助于读者理解业务逻辑，而无需追溯到赋值。”
反馈语调指南
| 避免 | 首选 |
|---|---|
| “你应该…” | “考虑…” 或 “你觉得如何…” |
| “这是错的” | “这可能导致问题，因为…” |
| “为什么你不…” | “你考虑过…” |
| “显然…” | “一种方法是…” |
| “总是/从不做X” | “在这个上下文中，X会有帮助，因为…” |
正面观察
包括做得好的地方：
“这里使用策略模式很好 — 它使得添加新支付方法变得直接。”
“良好的错误处理 — 带有指数退避的重试逻辑正是我们为这个不稳定API需要的。”
“验证和持久化逻辑之间的关注点分离很干净。”
评审清单
快速评审清单（< 100行）
- [ ] 代码编译且测试通过
- [ ] 逻辑对于所述目的看起来正确
- [ ] 没有明显的安全问题
- [ ] 命名清晰
- [ ] 没有魔法数字或字符串
标准评审清单（100-500行）
所有以上，加上：
- [ ] 设计遵循项目模式
- [ ] 错误处理适当
- [ ] 测试覆盖新功能
- [ ] 没有显著重复
- [ ] 性能合理
深度评审清单（> 500行或关键）
所有以上，加上：
- [ ] 架构与系统设计对齐
- [ ] 考虑安全影响
- [ ] 保持向后兼容性
- [ ] 更新文档
- [ ] 如果需要，迁移/回滚计划
评审工作流
评审前
- 理解上下文（票证、讨论、需求）
- 检查CI是否通过（不要评审失败代码）
- 估计评审复杂性并分配时间
评审期间
- 第一遍：理解整体更改
- 第二遍：检查正确性和设计
- 第三遍：查找边界情况和安全
- 在评审过程中记录发现
评审后
- 总结整体印象
- 清楚指示批准状态
- 区分阻塞性与非阻塞性反馈
- 提供讨论复杂建议的机会
评审指标
跟踪评审有效性：
| 指标 | 目标 | 指示意义 |
|---|---|---|
| 评审周转时间 | < 24小时 | 团队速度 |
| 每评审评论数 | 3-10 | 参与度 |
| 发现的缺陷 | 下降趋势 | 质量改进 |
| 评审时间 | < 60分钟对于典型PR | 规模适当的更改 |
| 批准率 | 70-90%首次提交 | 清晰标准 |
评审中的反模式
避免这些评审行为：
| 反模式 | 描述 | 更好方法 |
|---|---|---|
| 挑剔 | 专注于风格而非实质 | 使用linter处理风格 |
| 路过式评审 | 未深入就快速批准 | 分配适当时间 |
| 守门 | 根据个人偏好阻止 | 专注于客观标准 |
| 幽灵评审 | 无评论批准 | 添加至少一个观察 |
| 评审轰炸 | 用评论压倒 | 优先处理并限制在主要问题 |
| 延迟评审 | 让PR等待多天 | 承诺周转时间 |