系统性代码审查

边界

• 审查当前本地差异或指定 GitHub PR，默认只分析和报告。
• 审查阶段不修改文件、不提交、不推送；用户已明确授权后续工作时，审查完成后继续对应步骤。
• 发布远端评审仍须用户明确要求；同一范围内已有授权时不重复请求。
• 项目或全局规则定义了交付分档时，常规档由实现者对当前差异自审一轮，高风险档需要独立审查；没有定义时，高风险改动（权限、计费、数据写入或迁移、并发、对外兼容、发布）需要独立审查，简单改动不强制。独立审查交给未参与实现的 Agent 或审查者：客户端支持子代理且规则已授权时直接派生，未授权时说明原因并询问。审查者以需求、原始差异和运行证据独立判断，实现者的总结与结论只作为待核对的声明。一个独立审查者即可，不对同一差异叠加多个模型的对抗审查；多出的预算用在能运行的验证上。
• 多轮审查中，首轮检查完整范围，后续轮次只复核修复及其影响；用户明确要求重新全面审查时除外。没有新增、可复现或有具体证据支持且影响正确性或验收结论的问题时停止，不因措辞、格式或可选增强继续扩展验证框架。任务约定的轮次或时间预算用尽时，报告剩余问题与关键证据缺口，不把达到上限当作审查通过。
• 不要求特定客户端插件。GitHub 操作优先使用已认证的 gh（gh pr view、gh pr diff、gh api），gh 不可用时回退 GitHub 连接器；两者都不可用时仍可审查本地差异，远端操作明确报告未执行。

1. 固定审查快照

先确认仓库、工作区和审查范围：

git rev-parse --git-dir
git status --short
git branch --show-current
git log --oneline -10

工作区中的修改、暂存和未跟踪文件都是用户的工作：可以读取并纳入审查范围，但不移动、隐藏、覆盖或清理。审查 PR 时不切换当前检出，也不用 git switch、git checkout、git stash、git reset --hard、git clean 或 gh pr checkout 准备环境；优先使用 gh pr diff、git fetch origin pull/<n>/head:refs/tmp/pr-<n>、git merge-tree 或临时 worktree。

PR 模式通过 gh（不可用时用连接器）读取编号、基准分支和来源分支、状态、更新时间、完整差异和检查。本地模式读取 git diff HEAD 或明确的 <base>...HEAD。记录实际范围，不基于旧差异或截断差异块下结论。

PR 模式先做准入判断：PR 已关闭或已合并、是草稿、是机器人生成的依赖或格式化更新且改动显然正确，或者当前身份已经对同一个 head 提交发布过审查时，报告原因并停止；用户点名要求审查时照常进行。

收集规则文件：仓库根目录以及每个变更文件所在目录和各级父目录中的 AGENTS.md、CLAUDE.md。某条规则只约束与它同目录或在其子目录下的文件；判断违规前先确认规则的作用范围覆盖该文件。

完整差异、逐文件覆盖、可信上下文、行号定位和反证规则遵循 评审证据协议。

读代码前先按 范围与完整性预判 的“目标与需求”找到需求来源，快速审查也不跳过：需求理解错误、差异与描述不符、权限放错层和接口难用，只读代码发现不了。标准或深入审查再执行该文件的其余部分。

1.1 场景契约与验收范围

如果变更目录或目标项目已有 test-scenarios.md，在深入审查前读取它，把它当作本次行为范围和验收标准的输入，而不是把测试数量当作覆盖证明。

检查：

• 每个受影响的行为是否能映射到场景 ID；
• covered 场景是否有真实测试命令、日志、运行结果或其他证据；
• skipped 场景是否说明原因、影响和后续动作；
• P0/P1、错误路径、兼容性、权限和人工 E2E 场景是否被遗漏；
• 实现、测试和场景契约之间是否出现互相矛盾的预期。

没有场景契约时，不要为了补文档而擅自创建文件。对于非平凡或行为变化的差异，在摘要中记录 scenario contract: none，将其作为覆盖与验收缺口，而不是自动判定为代码缺陷。

审查仍然是只读流程；场景状态和证据的补充由实现者或用户授权的后续步骤完成。

2. 确定深度与专项

• 快速：100 行以内且 1-5 个文件
• 标准：100-500 行，或 6-10 个文件
• 深入：500 行以上、10 个以上文件，或涉及认证、支付、数据写入等高风险路径

只根据本轮变更加载专项：

• 通用正确性、边界、错误处理、测试与复杂度：代码质量
• 所有审查都做轻量复杂度检查；标准、深入审查或用户明确关注简化时，读取 简化审查
• 性能收益声明、基准差异、明确热点、I/O/网络放大、锁或分配风险：性能，按其中的测量校验区分实测结论和静态风险
• 信任边界、鉴权、输入或密钥风险：安全
• 行为、API、配置或示例变化：文档
• .go / go.mod：Go
• .java：Java
• .py：Python
• CI、YAML/JSON 配置或依赖清单：CI 与配置
• 差异命中以下形状时读取 条件审查模式 的对应小节：复发或难以观察的缺陷、按输出文本分支或异步完成、删除与精简、恢复刚删除的内容或把例外改成与同类一致、覆盖用户文件、批量删除或递归匹配、同一规则多处计算、测试是否覆盖真实入口、未发布功能的迁移代码、引用新标识符、依赖与锁文件变化

TS/JS 变更执行轻量语言检查，不因仓库存在某语言就加载无关清单。

3. 架构分路

用户明确要求架构评审，或差异改变模块分层、公共接口、适配器或中间件、状态或任务生命周期、存储、跨服务调用、权限、错误体系、并发与资源管理时，加载 架构审查。

架构结论必须基于当前差异和必要相邻实现。区分必须修复与可选优化，不把理想化分层、个人偏好或未触及历史问题包装成缺陷。

发现集中在同一个根因时（同类缺陷反复打补丁、权限或状态问题源于架构本身、简单问题被做复杂），先给出路线结论：保留、调整、替换或信息不足，再列具体问题。只有替代方案能消除这类问题且迁移代价可接受时才比较；用户已声明路线确定或设计文档已记录该取舍时不重新讨论。

3.1 简化审查

每次审查都检查当前差异是否增加了可以删除的概念、分支、状态、层级或依赖，以及缺陷修复是否只在共享机制上为单个调用方叠加特例而没有修到根因。标准、深入审查或用户明确要求评估复杂度时，按 简化审查 完成专项检查。

简化建议必须落到当前代码：指出复杂度来源，给出适配现有类型和调用方式的替代实现，并说明如何验证错误语义、调用顺序、副作用和兼容性不变。只能描述“可以更优雅”或无法通过当前接口实现的方案，不作为 finding 输出。

3.2 并行分路（深入审查且允许子代理时）

深入审查且客户端支持、规则允许派生子代理时，可以按以下分路并行找候选；标准和快速审查由当前执行者顺序完成同样的检查，不为分路而派生。

• 规则合规两路：各自独立对照上一步收集的规则文件审查差异，只报能引用原文且作用范围覆盖该文件的违规。
• 明显缺陷一路：只看差异本身找编译、解析、未定义引用和与输入无关的逻辑错误，无法仅凭差异确认的不报。
• 引入代码一路：在新增或修改的代码范围内找安全、逻辑和错误处理问题，按需读取调用链。
• 简化一路：按 3.1 检查可删除的概念、重复和薄封装。

每路都拿到 PR 标题、描述和需求来源以理解作者意图，返回每个候选的描述、位置和标记原因（规则合规、缺陷或简化）。汇总后每个候选仍按第 4 步过滤；P0/P1 与规则违规交给独立子代理反驳，只保留被确认的条目。

4. 证据过滤与汇总

对每个候选 finding：

1. 读取定义、调用方、配置和测试等必要上下文；差异块不足时查真实代码。
2. 找能推翻关键事实的反证，有直接反证就删除。
3. 确认问题由当前变更引入或暴露，并定位到当前快照最小连续范围。
4. 内部评估置信度：80+ 才作为问题；50-79 放入待确认；低于 50 不输出。刻度：0 经不起推敲或是既有问题；25 可能真实也可能误报，风格类且项目规则没有点名；50 真实但属于细枝末节或很少触发；75 复核过、实际会触发、现有做法不够，或项目规则直接点名；100 证据直接确认且会频繁发生。机制真实、只是触发条件取决于时序、环境或配置的候选，例如并发竞态、罕见但可达路径上的空值、把零值当作缺失、边界 off-by-one、重试风暴或部分失败，不因“推测性”删除；至少放入待确认并写明确认方法。
   • P0/P1 还要说明现有防护（校验、类型系统、上游捕获、框架默认行为）为什么拦不住；说明不了就降级或删除。
   • 判定为回归前先读对应提交信息和作者意图；维护者有意的改动是决定，不是 finding。
   • 深入审查的 P0/P1 候选做一次独立反驳：重新读取引用的代码，确认问题真实存在、没有在别处处理、不是设计如此、不是只在理论上可达；客户端支持子代理时可以每条交给独立代理反驳。
   • 标注证据等级：已运行（命令、测试或最小脚本复现过）、可达路径（能指出从入口到问题的具体代码路径）、推测。推测 只能进入待确认；一条命令就能证明的候选先运行再定级。
   • 项目规则违规必须引用规则原文和所在文件，并确认规则作用范围覆盖该文件；代码中已用 lint 忽略注释等方式显式豁免的规则不报告。
   • 以下不作为 finding：本次差异之前就存在的问题；看似错误但实际正确的代码；资深工程师不会提出的挑剔意见；编译器、类型检查、linter 或 CI 已经会报出的问题（不为确认它而专门运行 linter）。
5. 按文件和根因去重，再按 P0/P1/P2 排序。
6. 深入审查额外从四个角度找问题：代码默认成立的假设（格式、顺序、范围）不成立时会怎样；与现有系统在并发或部分失败下组合会怎样；哪串合法操作会走到非法状态；第 1000 次请求、发布过程中或两人同时编辑同一资源时会怎样。这些候选同样按第 4 步分流。
7. 标准或深入审查在去重后再做一轮补漏：带着已有清单重读差异和所在函数，只找清单之外的问题，重点看移动或抽取后丢失的校验与锚点、锁范围缩小、带副作用的判断函数、测试 setup 与 teardown 不对称、配置默认值被翻转。没有新问题时不凑数。

若要指出回归由哪个提交或 PR 引入，先用 git log -S/-G、git blame 和关联记录定位候选，再核对该提交的父提交与实际差异是否改变了相关行为。浅克隆、历史裁剪或缺少父提交导致无法核实时，写明“来源未确认”，不要仅凭 blame、提交标题或时间归因；区分代码作者、PR 作者与合并者。

简化候选还需通过可用性检查：替代方案能在当前依赖、类型和接口下实现；示例覆盖关键分支与错误路径；验证命令能够证明行为保持不变。缺少其中任何一项时，先补充上下文或把它降为待确认问题。

对影响范围较大的变更，找出“该变更安全所依赖的一个关键事实”，并尽量用真实代码、最小脚本或针对性测试证明它。只能从源码推理或无法运行验证时，明确标为待确认，不把未证明的安全假设写成结论。

判断兼容性时，以 PR 目标分支在本次变更前已有的行为、数据和调用方为基线。若接口、配置或功能由本 PR 首次引入，同一 PR 内对它的调整不算破坏性变更，也不要求兼容 PR 的中间版本；按最终快照检查正确性、用法和文档。若调整同时影响基线已有的行为、数据或调用方，仍按实际回归评估。

对可能改变开发者或既有功能使用方式的差异，额外检查环境变量和 secret 读取、端口与网络、必需脚本、构建入口、feature gate 和内部权限条件。研究尚未完成时保留未确认项，不用条件猜测替代对后端、调用方或 PR 讨论的核实。

测试相关差异额外检查：

• 关键主流程、失败路径、边界输入、兼容性、权限和并发/异步状态是否有与风险匹配的验证；
• 新增或修复的 bug 是否有可复现的回归场景，而不是只增加无关覆盖率；
• 测试是否依赖执行顺序、共享状态、未提交事务、固定资源名或外部环境；
• 删除、收缩或改写测试时，原有关键约束是否仍被保留；
• 单元测试使用 mock/fake 时，集成/E2E 是否仍覆盖真实协议、数据和最终状态；
• 测试通过、编译通过或中间资源状态是否被错误地报告成完整运行面验证。

严重度：

• P0：确定的正确性、安全或严重并发缺陷
• P1：健壮性、关键测试缺口或明确性能退化
• P2：有实际维护成本的设计、文档或规范问题

不为凑数量报告问题。默认检查是否存在可删除的抽象、依赖和配置层，但安全校验、错误处理、数据保护、可访问性和用户明确需求不算无效复杂度。

审查快照变化时，按 评审证据协议 刷新快照、锚点和受影响结论，不沿用过期证据。

5. 发布评审

只有用户明确要求把结果发布到 GitHub 时：

1. 完成所有适用检查和去重后再发布，避免中途制造多次通知。发到 PR 上的条目只保留高信号问题：代码无法编译或解析（语法、类型、缺少导入、未解析引用），不论输入如何都会得出错误结果，或能引用原文的明确规则违规；依赖特定输入或状态的潜在问题、风格与质量意见、测试覆盖和泛泛的安全建议（项目规则明确要求的除外）只留在终端报告。拿不准是否真实的不发。
2. 发布前先在本地列出准备发的全部评论，逐条确认措辞和位置；这份清单不发布。
3. 使用 gh api 创建待提交评审并提交；gh 不可用时回退支持写入的 GitHub 连接器。
4. 只发布一次不阻塞合并的 COMMENT，不擅自使用 REQUEST_CHANGES。有行内意见时先建待提交评审、逐条添加行内评论，最后一次性提交。
5. 行内评论每个独立问题只发一条，写清问题、影响和修法。只有采纳后即可完整修复、且改动在一处不超过 5 行时才附可直接提交的 suggestion 块；需要后续步骤、跨多处或结构性改动时只描述修法。
6. 评论中引用代码使用带完整提交 SHA 的永久链接：https://github.com/<owner>/<repo>/blob/<完整 SHA>/<path>#L<起>-L<止>，仓库与被审查的仓库一致，前后各留至少一行上下文；不写 $(git rev-parse HEAD) 之类不会被展开的表达式。引用项目规则时链接到该规则文件。
7. 没有发现问题且用户要求发布时，发一条简短总结评论，写明已检查的范围（缺陷与项目规则合规）和“未发现明确问题”。
8. 发布后读回评审，验证目标 PR、正文和事件类型。
9. 没有远端写能力时输出完整评审正文和人工执行说明，不声称已经发布。

输出

## 问题
[P0/P1/P2] <标题> - <文件:行> [置信度: 90] [证据: 已运行/可达路径]
证据: <触发条件、当前代码和影响>
建议: <最小可执行修复>

## 待确认问题
- <缺少的关键证据>

## 可行的简化（存在时才输出）
[P2/建议] <标题> - <文件:行>
复杂度来源: <多余概念、分支、状态、层级或依赖>
替代实现: <适配当前代码的代码片段或具体步骤>
行为证明: <保持的语义与验证方法>

## 摘要
- diff 快照：<range>
- 文件覆盖：<已审查 / 上下文 / 跳过 / 失败>
- 需求来源：<issue/文档/PR 描述/none>; 对照结论：<目标一致/范围漂移/不完整/实现与需求不符>
- 场景契约：<path / none>; 覆盖：<结论>
- 可拆分性与文档债务：<结论>
- 架构专项：<未执行或基于证据的结论>
- 发布：<未请求 / gh / connector / 未执行>

没有高置信问题时明确写“未发现明确问题”，并说明验证和上下文边界。

统一约束

• 验收标准：遵循 ../_shared/common-acceptance.md
• 场景契约只作为审查输入；没有用户授权，不在审查流程中创建或修改它。