Code Review Playbook(代码评审手册)是一个用于开展和改进代码评审的技能。它面向两类人:给出反馈的评审者,以及准备代码送审的作者,目标是让评审更全面、一致且有建设性。
用途
- 审查拉取请求或合并请求。
- 作者在提交前进行自审。
- 为团队建立代码评审标准。
- 培训新开发者掌握评审最佳实践。
- 处理关于代码质量的分歧。
- 改进评审流程与效率。
评审理念 手册强调评审不只找缺陷,还承担知识共享、保持一致性、指导开发者、建立集体所有权和沉淀讨论记录等作用。原则包括:对代码不对人、假设善意、表扬好方案;反馈要具体可操作,指向具体行、解释原因并给出改进示例;在速度与彻底性之间平衡,目标在 24 小时内反馈,关键评审不赶时间,常规检查交给自动化;区分必须修复与可选改进,用约定式评论标明严重程度,仅对关键问题阻止合并,次要改进可记录到后续任务。
约定式评论 采用“<标签> [修饰]: 主题”加讨论内容的格式。标签包括 praise、nitpick、suggestion、issue、question、thought、chore、note、todo、security、bug、breaking,并说明各自是否阻止合并。修饰符包括 [blocking]、[non-blocking]、[if-minor]。资料给出多个示例,如用 praise 表扬 TypeScript 泛型使用,用 nitpick 建议 const 替代 let,用 issue 指出缺少 API 错误处理,用 security [blocking] 指出管理接口缺少鉴权,用 suggestion [if-minor] 建议提取魔法数字。
评审流程
- 评审前:阅读 PR/MR 描述,理解目的与范围,查看关联工单,检查 CI/CD 状态;确认测试、Lint、类型检查、覆盖率与合并冲突等自动化检查;按规模预留时间,小型 PR(少于 200 行)15–30 分钟,中型(200–500 行)30–60 分钟,大型(超过 500 行)1–2 小时或建议拆分。
- 评审中:先做 5–10 分钟高层浏览,理解意图与架构是否合理;再做 20–45 分钟逐行细查逻辑、边界、错误处理、测试与安全;随后用 5–10 分钟考虑测试是否覆盖正确内容与边界;最后用 5 分钟检查复杂逻辑注释、公开 API 文档、破坏性变更与 README。
- 评审后:给出批准、评论或请求修改的明确结论;及时回答作者问题,修改后复审,问题解决后批准并感谢作者。
检查清单 资料提供多类清单:通用代码质量(可读性、命名、注释、格式、DRY、SOLID、函数规模、圈复杂度)、功能(正确性、边界、错误处理、日志、输入输出校验)、测试(覆盖率、质量、边界与错误路径、隔离、命名)、性能(N+1 查询、缓存、算法效率、资源释放、懒加载)、安全(认证、授权、输入净化、密钥管理、加密、HTTPS、限流)、JavaScript/TypeScript(异步、类型安全、可空性、数组方法、const/let、箭头函数)、Python(PEP 8、类型提示、列表推导、上下文管理器、异常处理、f-string)、API 设计(RESTful、命名一致、HTTP 方法、状态码、错误响应、分页、版本化)、数据库(迁移、索引、事务、级联、约束、N+1)、文档(PR 描述、代码注释、API 文档、README、CHANGELOG)。
反馈模式与反模式 手册用正反例说明如何给出建设性反馈:好反馈要具体、解释影响、给出具体方案和示例代码;坏反馈如“这是错的,改掉”缺少信息且语气生硬。作者侧建议假设善意、不清楚就问、接受合理意见、有分歧时解释理由、及时修改并致谢。反模式包括评审者无价值地挑刺、不理解上下文逐行看、因个人偏好阻止合并、在评论里重写代码、疲劳式盖章批准;作者侧包括超大 PR、无描述、测试失败就送审、防御性对待反馈、评审后强制推送。
模板与指标 资料包含标准 PR 模板(描述、变更类型、测试方式、检查清单、截图、备注)和安全评审模板(认证授权、输入校验、数据保护、依赖、日志监控)。健康指标建议:评审时间少于 24 小时、PR 小于 400 行、首次评审批准率 20–30%、每个 PR 3–10 条评论、1–2 轮往返、批准后 2 小时内合并;警示信号包括超过 3 天无人评审、首次批准率 90% 以上、平均 PR 超过 800 行、每个 PR 15 条以上评论、5 轮以上评审。
智能体集成 资料说明该手册可被代码质量评审智能体使用,按约定式评论与语言检查清单给出结构化反馈;也可供后端架构师检查架构合理性与 API 设计,供前端开发者检查组件结构、可访问性与响应式设计,以及未来的安全评审智能体聚焦安全清单与合规要求。
限制 资料未说明该技能的安装方式、运行环境、收费或价格、具体平台支持情况,这些信息暂未提供。