code-review-playbook

代码审查手册

本技能提供一套全面的框架，帮助通过有效的代码审查提升代码质量、分享知识并促进协作。无论你是提供反馈的审查者，还是准备代码以供审查的作者，本手册都能确保审查全面、一致且具有建设性。

概述

• 审查拉取请求或合并请求
• 准备代码以供审查（自我审查）
• 为团队制定代码审查标准
• 培训新开发者掌握审查最佳实践
• 解决有关代码质量的分歧
• 改进审查流程和效率

上游内容覆盖范围（请勿重复说明）

此技能是一个轻量封装。通用审查技巧已在其他一方文档中说明； 这里只记录 OrchestKit 自己的决策。读取 Read("references/ork-delta.md") 以了解从已弃用文件中保留下来的内部规则。

主题	请转到此处
审查理念、速度、语气、PR 规模	https://google.github.io/eng-practices/review/
Conventional Comments 标签和装饰标记	references/conventional-comments.md、https://conventionalcomments.org/
OWASP Top 10 审查检查项	rules/security-baseline.md、https://owasp.org/Top10/
通用语言和框架审查检查清单	rules/typescript-quality.md、rules/python-quality.md、rules/linting-biome-rules.md
审查报告格式和多 Agent 完整 PR 审查	ork:review-pr
将审查结果应用到工作树	/code-review --fix、/simplify（见下文）
对当前分支进行纯安全审查	/security-review
GitHub 审查操作（批准、请求更改、行内评论）	https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests

---

Conventional Comments

issue [blocking]: Missing error handling for API call
If the API returns a 500 error, this will crash. Add try/catch.

security [blocking]: API endpoint is not authenticated
The /api/admin/users endpoint is missing auth middleware.

读取 Read("references/conventional-comments.md")，了解完整格式、标签（表扬、小问题、建议、问题、疑问、安全、缺陷、破坏性变更）、装饰标记（[blocking]、[non-blocking]、[if-minor]）和示例。

---

审查流程

1. 审查前

了解背景：

• 阅读 PR/MR 描述
• 理解目的和范围
• 查看关联的工单或问题
• 检查 CI/CD 流水线状态

验证自动化检查：

• 测试通过
• Lint 检查无错误
• 类型检查通过
• 代码覆盖率达到目标
• 没有合并冲突

安排时间：

• 小型 PR（< 200 行）：15-30 分钟
• 中型 PR（200-500 行）：30-60 分钟
• 大型 PR（> 500 行）：1-2 小时（或请作者拆分）

2. 审查期间

遵循以下模式：

1. 高层审查（5-10 分钟）

   • 阅读 PR 描述并理解意图
   • 浏览所有变更文件，了解整体情况
   • 确认方案在架构上合理
   • 检查变更是否符合所述目的

2. 详细审查（20-45 分钟）

   • 逐行审查代码
   • 检查逻辑、边界情况和错误处理
   • 验证测试是否覆盖新增代码
   • 查找安全漏洞
   • 确保代码遵循团队规范

3. 测试注意事项（5-10 分钟）

   • 测试是否全面？
   • 测试是否验证了正确的内容？
   • 是否覆盖了边界情况？
   • 测试数据是否贴近实际？

4. 文档检查（5 分钟）

   • 复杂部分是否添加了注释？
   • 公共 API 是否有文档说明？
   • 是否注明了破坏性变更？
   • 是否需要更新 README？

3. 审查后

明确给出决定：

• ✅ 批准：代码已可合并
• 💬 评论：已提供反馈，无需采取行动
• 🔄 请求更改：必须先解决问题才能合并

回复作者：

• 及时回答问题
• 完成修改后重新审查
• 问题解决后予以批准
• 感谢作者处理反馈

---

审查检查清单

通用代码质量

• 可读性：代码易于理解
• 命名：变量和函数名称清晰且具有描述性
• 注释：对复杂逻辑进行说明
• 格式：代码遵循团队风格指南
• DRY：没有不必要的重复
• SOLID 原则：在适用情况下遵循 SOLID 原则
• 函数长度：函数专注于单一职责，且少于 50 行
• 圈复杂度：函数的复杂度小于 10

安全性

• 身份验证：受保护的端点需要身份验证
• 授权：用户只能访问自己的数据
• 输入清理：防止 SQL 注入和 XSS
• 密钥管理：没有硬编码的凭据或 API 密钥
• 加密：静态和传输中的敏感数据均已加密
• 速率限制：保护端点免受滥用

---

快速入门指南

审查者：

1. 阅读 PR 描述并理解其意图
2. 检查自动化检查是否通过
3. 进行高层次审查（架构、方案）
4. 进行详细审查（逻辑、边缘情况、测试）
5. 使用规范的评论进行清晰沟通
6. 给出决定：批准、评论或请求修改

作者：

1. 撰写清晰的 PR 描述
2. 请求审查前进行自我审查
3. 确保所有自动化检查均通过
4. 让 PR 聚焦且规模适中（少于 400 行）
5. 及时、尊重地回应反馈
6. 按要求进行修改，或说明理由

---

CC 内置审查命令（2.1.152+）

本手册提供的是手动框架；Claude Code 内置了可自动完成其中部分工作的命令：

• /code-review — 审查当前差异，查找正确性缺陷以及复用、简化和效率方面的改进点。
• /code-review --fix（CC 2.1.152+）— 运行审查，然后将审查结果应用到工作树中（查找错误的审查，涵盖正确性以及复用、简化和效率）。
• /code-review --comment — 将审查结果作为 PR 行内评论发布。
• /simplify — CC 2.1.154 对此命令进行了更改：现在它只运行清理类审查（复用、简化、效率、架构层次），并应用修复；不再调用完整的 /code-review --fix 错误排查。整理代码时使用 /simplify，查找并修复错误时使用 /code-review --fix。

使用内置命令快速审查指定差异；使用 ork:review-pr 进行多 Agent、完整 PR 审查（安全性 + 测试 + 架构）。

---

技能版本：2.0.0 最后更新：2026-01-08 维护者：OrchestKit

相关技能

• ork:architecture-patterns - 在代码审查期间落实测试和架构最佳实践
• ork:security-patterns - 身份验证、输入验证和 OWASP 模式，补充手动审查
• ork:testing-unit - 用于审查时验证的单元测试模式

规则

每个类别的规则都位于 rules/ 中，并按需加载：

类别	规则	影响	关键模式
TypeScript 质量	rules/typescript-quality.md	HIGH	不使用 any、Zod 验证、穷尽式 switch、React 19
Python 质量	rules/python-quality.md	HIGH	Pydantic v2、ruff、严格 mypy、异步超时
安全基线	rules/security-baseline.md	CRITICAL	不包含密钥、端点需身份验证、输入验证
Lint	rules/linting-biome-setup.md	HIGH	Biome 配置、ESLint 迁移、渐进式采用
Lint	rules/linting-biome-rules.md	HIGH	Biome 配置、类型感知规则、CI 集成

总计：4 个类别中的 5 条规则

可用脚本

• scripts/review-pr.md - 自动获取 GitHub 数据，动态审查 PR

  • 自动获取：PR 标题、作者、状态、变更文件、差异统计信息、评论数
  • 用法：review-pr [PR-number]
  • 需要：GitHub CLI (gh)
  • 使用 $ARGUMENTS 和 !command 获取实时 PR 数据

• assets/pr-template.md - PR 描述模板

此处有意不提供审查报告模板；ork:review-pr 负责该输出格式。请参阅 references/ork-delta.md。