评审工具与自动化

• 理解 Gerrit 的 Change 模型
• 掌握 per-change review 的机制
• 认识其对小步提交习惯的塑造

Gerrit 以 Change（而不是 GitHub 的 PR）为评审单元：一个 Change 通常对应一个提交（commit），评审针对单个提交进行，作者通过"amend"在同一 Change 上更新补丁集（patchset）。这种"逐提交评审"（per-change review）模型天然鼓励小步提交——每次提交一个逻辑清晰的小变更，立即评审，快速得到反馈，避免累积成大改动。小步提交+频繁评审降低了评审认知负荷、缩短了反馈周期、让历史可追溯。Gerrit 模型把"小步"内化为工作习惯。

评审单元决定协作粒度。Gerrit 的 Change=单提交，让"提交即评审单元"成为自然，迫使作者把变更拆小。这与 small PR 原则同源，但通过工具强制。

• 理解 Gerrit 的投票体系（+1/+2、Verify）
• 掌握 Code-Review 与 CI 投票的协同
• 认识门禁配置

Gerrit 用投票体系控制合并：Code-Review 标签由评审者打分（+1 认可、+2 最终批准，-1/-2 反对），Verify 标签由 CI 根据构建/测试结果投票（+1 通过、-1 失败）。合并门禁通常是"Code-Review +2 且 Verify +1"同时满足才允许 merge——即"评审者批准"与"CI 验证通过"都成立，缺一不可。协同价值：Code-Review 保证"人审过"，CI 保证"机器验过"，两者结合形成双重门禁，防止"人批了但测试失败"或"CI 过但无人审"的漏洞。门禁级别可配置（如 master 需 +2）。

Gerrit 的投票把"人审"与"机验"分离为两个标签，合并门禁要求两者同时满足。这种"双通道门禁"是 Gerrit 严控质量的机制，比单一批准更可靠。

• 理解 PR 与 Gerrit 评审单元差异
• 掌握对认知负荷的影响
• 认识对可回溯性的影响

GitHub PR 以"一批变更"（一个分支累积的多个提交）为评审单元，评审者面对整个 diff；Gerrit 以"单个 Change/提交"为单元，评审聚焦单次提交。认知负荷上：PR 可能很大、上下文多，认知负荷高；Gerrit 单提交小、聚焦，认知负荷低。可回溯性上：PR 把多个提交的决策混在一起，回溯困难；Gerrit 每个提交独立评审、历史清晰，可回溯性强。差异的根本是"评审粒度"——PR 倾向批量、Gerrit 倾向单步，影响理解深度与决策追溯。Gerrit 更利于小步与追溯，PR 更灵活但粒度大。

评审单元决定"一次看多少"与"事后能追溯多少"。PR 的批量特性放大认知负荷、削弱回溯；Gerrit 的单提交特性降低负荷、增强追溯。两者反映不同协作哲学。

• 理解 CODEOWNERS 的匹配规则
• 掌握最近匹配优先（last-match-wins）语义
• 认识必需 owner 评审门禁

CODEOWNERS 通过规则定义哪些路径/文件由谁负责评审，规则基于目录、文件 glob（如 docs/**、src/foo/*.java），匹配遵循"最近匹配优先"（last-match-wins）——多个规则匹配同一文件时，靠后（更具体）的规则生效。与门禁联动：分支保护开启"需 Code Owner 评审"后，变更触及的文件的 owner 必须对 PR 评审/批准，否则不能合并。这保证"改谁代码谁负责"的归属制。合理配置规则（避免冲突、善用通配）是有效门禁的前提。

CODEOWNERS 把"评审责任"映射到"文件归属"。最近匹配优先让规则可组合（通用+具体覆盖），必需 owner 评审门禁强制"归属者把关"。二者联动是 monorepo 与多团队协作的关键。

• 理解 AI 评审的擅长领域
• 掌握其局限
• 认识 AI 评审的定位

AI 代码评审（LLM 评审 bot）的能力边界明显：擅长风格问题（命名、格式、注释）、明显缺陷（空指针、资源泄漏、常见反模式、明显的逻辑错误）、以及标准规范检查（鉴权、日志、错误处理等易枚举的规则）。拙于架构判断（是否符合系统设计、权衡取舍）、业务语义（是否满足真实业务需求、领域正确性）、上下文敏感的设计决策（需要理解整体系统与历史背景的判断）。AI 评审应定位为"辅助/第一遍过滤器"，输出候选意见供人工确认，而非替代人工评审。其局限源于缺乏对系统上下文与业务意图的完整理解。

AI 评审强弱取决于"可模式化"程度。风格与明显缺陷可模式化，架构与业务语义需要意图与上下文理解，是 AI 的短板。定位为过滤器而非决策者是正确用法。

• 理解 AI 过滤器的定位
• 掌握分工模式
• 认识降噪的价值

AI 评审作为"第一遍过滤器"：先由 AI 对 PR 做初筛，自动标记风格与明显缺陷类问题（甚至自动修复），人工评审者看到的是"已过滤"的变更，可聚焦于设计、语义、架构等高价值判断。分工：AI 处理确定性/低语义问题（降噪），人工处理需上下文的高价值问题（聚焦）。这减少人工在琐碎问题上的注意力消耗，提升评审质量与效率。实践要控制 AI 的误报率（避免 AI 噪音反而增加人工负担），并让 AI 意见可被人工确认/忽略。

过滤器分层的价值是"把机器擅长的事交给机器，人做机器做不到的事"。AI 降噪让"噪声"不再淹没"信号"，人工注意力释放给设计与语义。

• 理解 Crucible 与 FishEye 的功能
• 掌握跨仓库评审的组织定位
• 认识其与 GitHub/GitLab 的差异

Crucible 是 Atlassian 的代码评审工具，FishEye 是其代码仓库可视化/检索工具，两者集成提供仓库浏览、变更追踪与评审工作流。在组织级，它们常被用于"跨仓库评审"——当变更涉及多个仓库、需要统一评审视图时，Crucible/FishEye 能把跨仓库的变更聚合到一次评审中，并提供审计、统计与合规能力。相较于 GitHub/GitLab 的 PR，Crucible 更偏向"评审作为独立工作流"与组织级治理（跨仓库、审计、SLA）。其定位是面向需要统一评审与审计的企业级场景。

Crucible/FishEye 的价值在"组织级评审治理"——跨仓库聚合、审计、统计。对单仓库的轻量团队，GitHub 内建 PR 更简洁；对需要跨仓库与审计的企业，Crucible 更合适。

• 理解评审机器人打标签的机制
• 掌握标签对分流的作用
• 认识标签对 SLA 的支撑

评审机器人根据 PR 特征（行数、文件数、变更类型、是否缺测试）自动打标签：size/S、size/M、size/L（按规模）、needs-test（缺测试）、risk-high（高风险）、needs-reviewer（需分配）。标签作用：分流——按标签决定评审流程（小 PR 快速、大 PR 完整）；SLA 设定——按标签设定不同 SLA（如 size/L 给更多评审时间、告警阈值不同）；资源分配——机器人按标签自动分配 reviewer、提醒超时。自动标签客观、无人工偏差，让评审分流与 SLA 有据可依，提升流程公平与效率。

自动化标签把"PR 特征"客观化，成为分流、SLA 与资源分配的依据。它让评审流程"按风险与规模差异化"，避免一刀切。

• 理解多所有者与实际匹配的关系
• 掌握 last-match-wins 的陷阱
• 认识 monorepo 中的配置问题

monorepo 中 CODEOWNERS 的常见陷阱：多所有者（一个文件可列多个 owner，但"必需 owner 评审"可能要求所有 owner 都批准，导致门禁过严；或列错 owner 导致无关人员被要求评审）；last-match-wins 陷阱（规则顺序导致"本该匹配的 owner 被更靠后的通配规则覆盖"，或通配规则过宽意外匹配到多个目录，导致 owner 归属错误）；目录与文件 glob 冲突（规则不精确导致 owner 混乱）。规避：清晰定义规则层次（先用通用规则再用具体规则覆盖）、精确 glob、测试验证规则实际匹配结果、避免"必需 owner"与多 owner 语义冲突。

monorepo 路径复杂、规则多，last-match-wins 与多 owner 的交互易产生"归属错误"或"门禁过严/过松"。精确的规则设计与验证是避免陷阱的关键。

• 理解 AI 评审的幻觉风险
• 掌握约束设计（仅引用既有规范/代码）
• 认识幻觉对评审可信度的危害

AI 评审的"幻觉"风险指 AI 编造不存在的规范、引用错误的 API、或给出看似合理实则错误的意见，这会误导人工评审、损害可信度。控制手段：约束 AI"仅允许引用既有规范/代码"——即 AI 意见必须基于仓库内真实存在的规范文档、代码、配置（可通过检索/grounding 提供），禁止凭空引用；设计上让 AI 输出"引用来源"（哪条规范、哪个文件），人工可验证；对无法引用的意见标记为"建议"而非"断言"；对高风险意见要求人工确认。约束设计把 AI 从"编造"拉回"事实参照"，降低幻觉危害。

幻觉源于 AI 的自由生成。约束"仅引用既有内容"把生成锚定到可验证的事实，配合"给出来源"让意见可查证，是控制幻觉、提升可信度的关键。

• 理解 GitHub/GitLab 的评审流程
• 掌握其核心机制
• 认识工作流选择

GitHub/GitLab 的评审流程基于 PR/MR：开发者创建 PR/MR（含描述、变更、关联 issue），请求评审者；评审者在 diff 上评论（inline）、讨论（thread）、发表整体意见；评审者给出 review 结论（approve/request changes/comment）；通过分支保护门禁（需批准+CI 绿）后合并。还支持：分配到 reviewer、code owner 强制、评审提醒、自动合并等。GitHub/GitLab 的流程以"PR 为中心"、异步为主，强调讨论线程与审批门禁。工作流选择取决于团队规模与需求（GitHub 生态、GitLab DevOps 集成）。

以 PR/MR 为中心的流程把"评审、讨论、门禁"整合到一个可追溯的界面。内建分支保护与 CI 集成让流程可执行、可审计。

• 理解评审事件数据的来源
• 掌握数据导出机制
• 认识量化分析的价值

评审事件数据流：通过 GitHub/GitLab 的 API/Webhook 或工具集成，把评审事件（PR 创建、评论、review 结论、批准、合并、时延时间戳）自动导出到度量平台（如 Grafana、DataDog、自建数仓），形成结构化数据。技术上：Webhook 实时推送事件 → 存入数据管道 → 清洗聚合 → 生成指标（评论数、时延、批准率、轮次等）。支撑量化分析：评审有效性（逃逸率、密度）、流程瓶颈（时延分布）、团队负载等。自动化导出让评审数据"可度量、可追踪、可改进"，是评审 effectiveness 量化的数据基础。

评审度量需要"数据先自动化"。Webhook/API 把事件流导入度量平台，才能支撑"评审活动 vs 质量结果"的关联分析。自动化是评审数据驱动的前提。

• 理解三种工具的线程能力
• 掌握线程差异对收敛的影响
• 认识工具能力与协作的关系

三种工具的评论线程能力：GitHub 线程（code review thread，可 resolve 折叠）、GitLab discussion（可将评论分组为 discussion，可 resolve）、Gerrit inline（在具体代码行内联评论，多轮评论关联到同一行）。差异对收敛的影响：线程能力强的工具能把"同一问题的多轮讨论"绑定在特定位置，便于追踪与收敛（resolve 标记已完成）；Gerrit 的 inline 与 patchset 关联，评论始终贴在具体行，便于追溯但讨论分散于各版本；GitLab discussion 可把评论组织成讨论组。线程能力越强，讨论越集中、收敛越可控，避免意见散落与重复。

线程能力决定"讨论是否有上下文容器"。绑定在具体位置+可 resolve 的能力，让讨论聚焦、收敛、可跟踪，是评审效率与可追溯性的基础。

• 理解自动评审的手段
• 掌握各工具的分工
• 认识自动评审的定位

自动评审通过 Lint、静态分析与 CI 检查实现：Lint（代码格式、命名、明显的风格/语法问题，如 ESLint、Checkstyle）；静态分析（查找潜在 bug、安全隐患、复杂度过高，如 SonarQube、SpotBugs、ESLint plugin）；CI 检查（构建、单元测试、集成测试、覆盖率、依赖扫描）。这些在 PR 合并前自动运行，作为"机器评审"门禁，拦截确定性问题。自动评审定位是"第一道防线"，处理可判定的规则，与人工评审互补——机器管确定性，人工管语义。自动评审让质量底线自动化、可重复。

自动评审把"可判定规则"交给机器，实现"质量底线自动化"。它覆盖人工易疲劳的确定性问题，让人工聚焦高价值判断。三者分工：lint 风格、静态分析语义 bug、CI 行为验证。

• 理解评审机器人的分配逻辑
• 掌握超时提醒机制
• 认识机器人对评审效率的作用

评审机器人自动分配 reviewer：依据 CODEOWNERS（文件归属）、负载（当前待审数）、技能/历史、round-robin 等规则，为 PR 自动指派合适的评审者，减少人工分配与偏见。超时提醒：当 PR 等待评审超过设定 SLA（如 24h）时，机器人自动提醒 reviewer、升级到团队或重新分配，避免 PR 无限滞留。机器人还支持自动撤销 stale review、合并无异议 PR 等。自动分配+超时提醒降低评审瓶颈、保证评审 SLA，提升流程效率。

机器人的价值是"让评审流程自动化、可预期"。自动分配消除"等谁审"的找人之苦，超时提醒打破"没人审"的沉默，是评审流动性的保障。

• 理解通用与领域清单的分层
• 掌握避免形式化的方法
• 认识清单与设计评审的平衡

分层设计：通用清单（所有变更适用的项：命名、测试、错误处理、边界条件）与领域清单（按技术栈/业务类型加载：SQL 注入、并发安全、缓存一致性）。避免形式化：清单作为"提示"而非"勾选表"——把可判定项下沉给自动化，人工聚焦需判断的项；按变更类型动态加载相关清单，避免长清单；在清单之上保留"设计评审"环节（架构、权衡、语义），防止只核清单而漏设计。清单是辅助记忆的决策支持，设计是核心价值。二者结合避免"清单勾完即完"的陷阱。

清单式评审失效的根源是"勾选替代思考"。分层+自动化下沉+保留设计评审，让清单"提示关键点"而非"定义评审"，从而不掉入形式化。

• 理解 AI 摘要与建议的能力
• 掌握其应用场景
• 认识 AI 辅助的定位

AI 评审辅助的自动摘要与建议：AI 可自动生成 PR 摘要（变更内容、涉及文件、主要改动、动机），帮助评审者快速理解上下文；可对代码提出建议（风格、简化、潜在问题），并给出修改建议（如生成建议的 diff 或代码片段）。应用场景：评审者在读大 PR 前用摘要建立预期；AI 建议作为候选供人工确认。AI 辅助定位是"降低理解成本、提升评审效率"，而非自主决策。摘要质量取决于 AI 对变更上下文的理解，建议需人工验证。

AI 摘要把"读大 PR 的认知负担"转交给 AI 预加工，建议提供"起点"供人工确认。它提升效率但不替代判断，是"辅助"而非"裁决"。

• 理解自托管与 SaaS 的差异
• 掌握三方面的取舍依据
• 认识选型的决策维度

评审工具选型（自托管 vs SaaS）的取舍：数据合规——自托管把代码与评审数据留在本地，适合敏感数据/合规要求严格的场景；SaaS 数据在云端，需评估合规与数据主权。插件生态——SaaS（GitHub/GitLab Cloud）通常有更丰富的插件/集成与快速迭代；自托管需自行维护集成与插件。维护成本——自托管需自建、升级、备份、运维（成本高）；SaaS 免运维、开箱即用（但按订阅计费）。选型依据：结合数据敏感度、团队运维能力、成本预算、生态需求综合决策。合规敏感选自托管，追求低运维与生态选 SaaS。

选型是"合规、生态、成本"的三角权衡。自托管换合规与主权、付运维成本；SaaS 换低运维与生态、租云端。没有绝对优劣，取决于组织约束。