Claude How To 代码审查检查清单实战指南：以安全、性能、质量、测试四维清单驱动 AI 代码审查

Claude How To 代码审查检查清单实战指南：以安全、性能、质量、测试四维清单驱动 AI 代码审查

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

导读

代码审查最容易犯的错误是"凭感觉走"——看到哪算哪，最终漏掉关键漏洞或性能隐患。claude-howto 仓库在code-review-specialist这个可自动触发的 Skill 中内置了一份结构化的代码审查检查清单，将审查维度收敛为安全、性能、质量、测试四大类共 38 个可勾选项。本文将逐项拆解这份清单的含义、判断标准与修复思路，并演示它与 Skill 主文件、问题记录模板和复杂度分析脚本的组合用法，让你或 Claude Code 能在 Pull Request 审查中不遗漏任何类别。

一、检查清单在项目中的定位

在 claude-howto 仓库中，代码审查能力被打包成一个名为code-review-specialist的 Skill，它的核心结构如下：

03-skills/code-review-specialist/ ├── SKILL.md # Skill 主文件：触发条件与审查输出要求 ├── scripts/ │ ├── analyze-metrics.py # 计算函数数、类数、平均行长、复杂度 │ └── compare-complexity.py # 对比重构前后圈复杂度/认知复杂度 └── templates/ ├── review-checklist.md # 本文讲解的检查清单 └── finding-template.md # 单个问题的记录模板

根据 Skill 主文件 的 frontmatter，该 Skill 在"用户请求代码审查、代码质量评估、Pull Request 审查，或提到安全分析和性能优化"时被自动触发。它的审查能力被划分为四条主线：

• 安全分析：身份验证 / 授权问题、数据泄露风险、注入漏洞、密码学弱点、敏感数据日志记录；
• 性能审查：算法效率（Big O 分析）、内存优化、数据库查询优化、缓存机会、并发问题；
• 代码质量：SOLID 原则、设计模式、命名规范、文档、测试覆盖率；
• 可维护性：代码可读性、函数长度（建议少于 50 行）、圈复杂度、依赖管理、类型安全。

英文版 SKILL.md 明确要求审查时读取检查清单文件并以其为指引，确保审查过程不遗漏任何类别。也就是说，这份清单是审查流程的"防漏网"机制——它是 Skill 的灵魂骨架。

二、安全检查：十道必答题，守住底线

清单的安全检查一节共 10 项，全部围绕 OWASP 常见的注入、认证、授权与敏感信息泄露问题展开。逐项解读如下：

#	检查项	判断要点	常见反例与修复方向
1	没有硬编码的凭据或密钥	代码库、配置文件、注释、提交历史中是否有password、api_key、secret、token字面量	使用环境变量或密钥管理服务（如 Vault）注入；配合 .gitignore 排除.env
2	所有用户输入都做了校验	每个外部输入（表单、URL 参数、请求体、文件上传）是否经过白名单校验	服务端二次校验，不依赖前端校验
3	使用参数化查询，防止 SQL 注入	所有 SQL 是否通过预编译占位符拼接	将字符串拼接 SQL 改为?/$1参数绑定
4	所有会修改状态的操作都有 CSRF 防护	POST/PUT/DELETE 等写操作是否带 CSRF Token	框架内置 CSRF 中间件默认开启
5	使用正确的转义，防止 XSS	输出到 HTML 的内容是否按上下文转义	React 默认转义、模板引擎{{ }}、禁止innerHTML拼接用户输入
6	受保护的端点有身份验证检查	每个受保护路由/接口是否有认证中间件	未认证请求返回 401 而非 200
7	资源访问有授权检查	用户只能访问自己有权访问的资源（越权/IDOR）	对象级授权校验，而非仅登录即可
8	密码使用安全哈希算法（bcrypt、argon2）	密码存储是否使用可调代价因子的哈希算法	弃用 MD5/SHA1 明文哈希，使用bcrypt或argon2id
9	日志中没有敏感数据	日志是否打印令牌、密码、身份证号、信用卡号	日志脱敏，敏感字段打码或仅记录引用 ID
10	强制使用 HTTPS	生产环境是否强制 TLS，是否配置 HSTS	全站 HTTPS + 跳转，禁用不安全的协议

这 10 项与 Skill 主文件中"数据泄露风险、注入漏洞、密码学弱点、敏感数据日志记录"的能力描述一一对应，构成安全审查的最小充分集。值得注意的是，仓库还提供了独立的secure-reviewer子代理（见 04-subagents/secure-reviewer.md），以只读模式专注安全审查——在实际流程中，安全检查可以由该子代理与 Skill 配合完成。

三、性能检查：把复杂度与查询次数作为硬指标

性能问题的判定比安全问题更需要量化依据，清单给出了 10 个可验证的性能检查点：

#	检查项	判断要点	常见反例与修复方向
1	没有 N+1 查询	循环内是否有查询操作（每个用户都发一次查询）	使用 JOIN 或批量查询；检查 ORM 的预加载（eager loading）
2	索引使用合理	查询条件列是否有索引，是否出现全表扫描	为 WHERE/JOIN/ORDER BY 列建立索引，注意联合索引顺序
3	在有价值的地方做了缓存	热点数据、重复计算结果是否有缓存层	Redis 缓存、内存缓存、HTTP 缓存头；注意失效策略
4	主线程上没有阻塞操作	UI 线程/事件循环是否有同步 I/O、重计算	移到异步或后台任务
5	正确使用 async/await	是否有异步函数内部被同步阻塞、.Result/.Wait()死锁	全链路 async，避免 sync-over-async
6	大数据集已经分页	列表接口是否一次性返回全量数据	游标分页/偏移分页，限制单页大小
7	数据库连接已做连接池	是否每次请求都新建连接	使用连接池并合理设置 max 连接数
8	正则表达式已优化	是否存在灾难性回溯（(a+)+$这类嵌套量词）	使用非贪婪匹配、原子组，避免嵌套量词
9	没有不必要的对象创建	循环内是否重复创建昂贵对象、字符串拼接是否用+	复用对象、使用 StringBuilder/join
10	没有内存泄漏	事件监听器、全局引用、定时器是否被正确释放	清理监听器、使用弱引用、检查闭包持有大对象

性能审查的量化支撑来自 Skill 自带的 analyze-metrics.py 脚本。它从四个维度输出量化指标：

python3 scripts/analyze-metrics.py 被审查文件.py

脚本内部通过正则统计def/class数量、平均行长度，并用if/elif/else/for/while/and/or的出现次数估算复杂度分数（见 analyze-metrics.py）。这套"先量化、后判断"的思路，正好对应清单中"函数是否过大、复杂度是否可控"的检查逻辑。

四、质量检查：可读性、可维护性与设计原则

质量检查 10 项解决的是"这段代码三个月后还有人看得懂吗"的问题：

#	检查项	判断要点	常见反例与修复方向
1	函数少于 50 行	函数是否超出 50 行、职责是否单一	拆分函数，每函数只做一件事（也与 SKILL.md 中"函数长度建议少于 50 行"一致）
2	变量命名清晰	命名是否表达意图，而非data、tmp、x	使用业务语义命名；布尔变量用is/has前缀
3	没有重复代码	相同逻辑是否出现多次（DRY）	抽取公共函数/工具类，警惕复制粘贴
4	错误处理合理	异常是否被吞掉（裸except/空 catch）、错误是否有意义	精确捕获、记录上下文、向上抛出可处理错误
5	注释解释的是 WHY，而不是 WHAT	注释是否解释"为什么这样写"而非逐行翻译代码	用注释说明业务约束、权衡和陷阱
6	生产环境中没有 console.log	是否有调试日志残留	改用结构化日志库，配合日志级别
7	有类型检查（TypeScript / JSDoc）	是否利用静态类型或 JSDoc 标注	补全类型定义，开启严格模式
8	遵循 SOLID 原则	单一职责、开闭、里氏替换、接口隔离、依赖倒置	检查类是否职责过多、是否面向抽象编程
9	正确应用设计模式	模式是否解决问题而非炫技	评估模式引入的成本收益
10	代码具备自解释性	不读注释能否大致读懂逻辑	用清晰命名和结构替代注释

质量问题的深度分析可借助仓库中的code-reviewer子代理（04-subagents/code-reviewer.md）完成综合质量评估，审查者负责基于清单逐项判定即可。

五、测试检查：用边界与错误场景衡量覆盖质量

测试检查 8 项，重点不只是"有没有测试"，而是"测试有没有测到点子上"：

#	检查项	判断要点
1	已编写单元测试	核心逻辑是否有对应单测，且可独立运行
2	覆盖了边界情况	空集合、极值、临界值、null/undefined 是否被测试
3	测试了错误场景	非法输入、超时、依赖失败时行为是否符合预期
4	有集成测试	模块间、数据库、外部服务交互是否被覆盖
5	覆盖率大于 80%	行/分支覆盖率是否达标（80% 为清单设定的参考阈值）
6	没有不稳定测试	测试是否依赖时序、网络、共享状态导致偶发失败
7	外部依赖已做 mock	网络、数据库、第三方 API 是否被隔离
8	测试名称清晰	测试名是否描述行为（如should_reject_negative_amount）

仓库本身也体现了这一测试标准：scripts/tests/下包含针对 EPUB 构建、网站构建、交叉引用与 Markdown 渲染等脚本的 pytest 测试套件（见 scripts/tests/），并支持pytest --cov生成覆盖率报告。这说明清单中的"覆盖率 > 80%""测试名称清晰"等条目在该仓库中是真实执行的规范，而非纸面要求。

六、从勾选到报告：检查清单 + 记录模板 + 分析脚本的组合流程

检查清单回答"审什么"，而把发现的问题沉淀成可追踪的报告，需要配合 Skill 中的另外两个组件。

6.1 问题记录模板：把每个发现结构化

对清单中勾出的每一项问题，使用问题记录模板逐个归档。模板要求每个发现必须包含：

• 严重性：Critical（阻塞发布）/ High（合并前应修复）/ Medium（尽快修复）/ Low（可选优化）；
• 类别：Security / Performance / Code Quality / Maintainability / Testing / Design Pattern / Documentation；
• 位置：文件、行号、函数/方法；
• 问题描述：是什么、为什么重要、当前行为、期望行为；
• 代码示例：当前（有问题的）代码与建议修复代码；
• 影响分析：以表格列出对性能、用户体验、可扩展性、可维护性的影响及严重性。

模板中内置了一个 N+1 查询的典型示例：循环内对每个用户发起查询（20 个用户产生 100+ 次查询），修复方式为一次 JOIN 查询批量取回usersWithPosts。这个示例与清单"没有 N+1 查询"条目直接呼应，审查者可以直接复用为输出范例。

6.2 复杂度对比脚本：验证重构是否真正变简单

当审查涉及重构类改动时，Skill 提供了 compare-complexity.py 脚本，对比重构前后两个版本的复杂度：

python3 scripts/compare-complexity.py 重构前.py 重构后.py

脚本基于 McCabe 方法计算圈复杂度（统计if、elif、for、while、except、and、or等判定点，基数从 1 起算，见 compare-complexity.py），同时计算认知复杂度（基于嵌套深度与控制流，衡量代码理解难度）和可维护性指数（0–100，大于 85 为优秀，大于 65 为良好，低于 50 为差，见 compare-complexity.py）。输出会给出前后对比与自动评估结论（"代码更易维护 / 复杂度降低"等）。这正是清单中"函数少于 50 行""代码具备自解释性"等质量条目的量化验证工具。

七、落地工作流：如何在一次 PR 审查中跑完四维清单

将上述组件串起来，一次完整的审查可以按如下流程执行：

1. 量化预热：对变更文件运行analyze-metrics.py，拿到函数数、复杂度分数等基线数据；
2. 四维扫查：打开检查清单，按安全 → 性能 → 质量 → 测试的顺序逐项勾选，任何一项不满足即记录；
3. 问题归档：对每个问题用记录模板填写严重性、位置、影响与修复示例；
4. 重构验证：若改动涉及重构，用compare-complexity.py对比前后复杂度，用数据支撑"是否值得合入"的结论；
5. 汇总输出：按照 SKILL.md 中"审查模板"的要求输出——先给整体质量评分（1–5）、关键发现数量与优先关注区域，再按类别（安全/性能/质量/可维护性）列出发现，关键问题标注文件与行号、影响、严重性并给出修复示例。

需要提醒的是，检查清单是"最小完备集"而非"万能集"：它适合作为每个 PR 的默认兜底，但针对特定领域（如密码学协议、分布式一致性）仍需结合专业子代理（如secure-reviewer、performance-optimizer，见 04-subagents/）做纵深审查。安装该 Skill 到个人环境只需：

# 复制到个人 Skills 目录 cp -r 03-skills/code-review-specialist ~/.claude/skills/

随后在 Claude Code 中提出"请审查这段代码 / 评估这个 PR"，Skill 便会自动加载检查清单并按其框架输出结构化审查报告——四维清单从此成为你每次代码审查的固定流程，而不是可选项。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto