code-review

代码审查

确认请求的审查范围是否正确、必要、清晰，并已准备好用于所声明的用途。如果未明确提供文件或先前发现的问题输入，则审查完整变更。先审查；仅在获授权的修复模式下进行修复。

操作、修复与边界

收集证据前，先选择一项操作：

• **全新审查：**评估界定的变更并给出审查结论。
• **定向复核：**重新检查选定的先前发现的问题，不对整体变更作出判断。
• **组合操作：**仅当用户明确请求全新审查并提供先前发现的问题时，才同时执行两者；分别保留两者的输出和结论。

修复与操作相互独立：

• 默认不进行修复。检查并运行安全的本地探测，但不要编辑源代码、测试、配置或文档。
• fix <finding IDs> 仅修复选定的问题；fix-all 在一次有界处理过程中修复所有经验证且在范围内的问题。如果有先前发现的问题，任一模式都只能针对被分类为 still_present 或 changed 的选定问题进行编辑，绝不能针对 resolved、not_retestable 或 skippedOutOfScope 的问题进行编辑。
• 修复模式授权本地编辑和验证，但不授权提交、推送、PR 评论、审查线程变更、部署、发布或修改共享状态。遇到重大产品、架构、安全、兼容性或范围决策时，停止修复。
• 请求保存 JSON 只授权创建指定的问题记录文件，不授权进行修复。
• 精确的文件列表和先前发现的问题 JSON 是附加输入。除非用户提供这些输入，否则它们不会改变未限定范围的审查行为。
• 报告配置文件或阈值只改变呈现方式。应收集并验证映射范围内的完整候选问题集，在规范结果中保留所有有依据的严重级别，并由调用方决定哪些严重级别对外显示。
• 搜索完整的映射范围；不要在发现第一个或最高严重级别的问题后停止。
• 如果宿主支持子 Agent，且审查范围并非微不足道，默认将审查任务分派到不同审查通道。少量变更（例如单个文件中的几行）由本地处理。no-subagents 或等效的用户指示要求整个审查都在本地进行。如果审查分派了通道，在公布通道映射前阅读 references/subagent-lanes.md。通道运行期间，协调者继续处理与通道无关的工作，例如运行项目检查。

安全探测包括已声明的检查、本地构建和服务器、一次性复现、隔离的测试数据、浏览器交互、临时产物，以及可清洁回退的证伪探测。证伪探测会临时引入一项有针对性的错误行为，以证明相关测试或检查会因正确原因而失败。记录初始树状态，优先使用一次性工作树或副本，立即还原改动，将最终树与记录的状态逐字节比较，并报告所做的改动及观察到的失败。如果无法安全地精确还原，则跳过探测并将证据标记为仅限静态分析。清理一次性产物，并报告保留的产物。任何持久性或外部可见副作用都必须先征求许可。

条件引用

满足条件时阅读相应引用：

• 在评审委派各个分工之前，以及发布分工地图之前，阅读 references/subagent-lanes.md。
• 用户提供确切的文件列表时，阅读 references/file-scope.md。
• 用户提供先前的发现时，无论是否要求 JSON 输出，都要阅读 references/prior-findings.md 和 references/revalidation-json.md；它们定义了筛选方式、与文件列表的交集，以及针对性结果契约。
• 用户要求对全新评审输出 JSON 时，阅读 references/findings-json.md。
• 全新评审启用可发现性维度时，阅读 references/discoverability.md。
• 变更涉及身份验证、授权、支付、机密、破坏性或数据丢失行为，或租户隔离时，阅读 references/adversarial-review.md；在工程质量范围内开展受限的绕过路径排查。
• 结构性证据表明存在设计异味，但具体影响或最小修复方案尚不明确时，阅读 references/engineering-smells.md。将其作为调查提示；仓库规范和观察到的影响仍具有决定性。
• 用户选择 fix <finding IDs> 或 fix-all 时，阅读 references/fix-mode.md。

开展全新评审

全新评审或组合评审请使用本节。仅针对性复核时，请改用 prior-findings 引用。

1. 根据适用的项目说明、当前源代码、测试、配置、锁文件，以及贡献或完成契约来开展评审。
2. 确定比较边界：
   • 若用户提供了基准，则使用该基准；
   • 若为拉取请求，则使用其基准分支；
   • 否则，使用与远程默认分支的合并基点。
3. 委派之前，将固定点和 HEAD 确定为具体修订，然后确认可计算有界差异，且差异非空。若任一修订不可用、边界不明确，或变更为空或无关，则停止评审。
4. 纳入已提交、已暂存、未暂存以及相关的未跟踪工作。将脏工作树中的发现与已提交变更中的发现分开。
5. 根据问题、PR、已确认的简版规格、所需行为和提交内容，确定主张。若均不存在，则从变更中重建范围最窄且有依据的主张，并标注为推断。
6. 每次全新评审都启用去重、主张与规格、工程质量维度。仅当变更涉及公共页面、路由、元数据、爬取控制、结构化数据、公共内容或 Web 性能行为时，才启用可发现性维度。在工程质量范围内，涵盖正确性、简化、自文档化、测试价值和运维行为；仅当变更涉及相应方面时，才增加 UI/无障碍性、信任边界、持久化/迁移、并发、兼容性、部署/回滚、可观测性或性能。
7. 衡量发现范围内每个变更文件的代码变动量；若历史记录可以可靠识别，还要衡量每个变更函数、方法、类或模块的代码变动量。跟踪重命名，说明历史记录时间窗口，并记录修改次数和行变动量。使用仓库声明的变动量统计窗口；若未声明，则使用 90 天。优先使用仓库的代码健康工具；否则使用 Git 文件历史和 git log -L 检查稳定符号。符号历史不可用时，标注为文件级回退。

生成证据

在已映射的问题范围内应用这些要求。

• 根据当前证据确定代码库的相关门禁，或运行缺失的检查。在组合工作流中，调用方负责整体门禁。对于内容、命令、环境和覆盖范围相匹配的情况，复用通过的检查和真实接口证据；更改、失败、缺口或未解决的问题出现后，重新运行检查。保留独立的审查判断。不要复述明确的工具故障。
• 通过真实接口重现每项更改后的可观察行为。覆盖预期路径以及影响最重大的失败或边界路径。
• 对于 UI 更改，检查渲染后的界面、状态转换、加载／空／错误状态、无障碍功能和相关视口。对于非 UI 更改，检查真实的 API、CLI、库入口、作业、迁移、打包或部署路径。
• 记录设置、操作或命令、输入、预期结果和观察到的结果。采信返回的结果或相符的存储证据；请求、确认或预期结果不属于观察到的结果。重新运行未返回结果的检查；无法获得结果时标记为 unverified，仅基于源代码得出的结论标记为 static only。
• 验证更改后的测试能否针对相关错误行为失败，并断言结果而非实现细节。不要采信脆弱、过度模拟、偶然或过度依赖快照的覆盖。

审查维度

各维度应保持独立，避免相互掩盖。启用时，可发现性维度以其参考文档中的定义为准。

去重

针对限定的更改及其最少必要的辅助上下文，分别执行以下四项检查：

• **实现：**查找重复的代码、逻辑、测试、夹具、配置、架构、工作流、文档，或对同一概念的相互竞争的表述。
• **工作：**复用当前的问题决策、既往发现、调查和已接受的修复证据，避免重复劳动。如果它们的范围与更改重叠，应重新验证，而不是重新发现。
• **证据：**合并多个检查、日志或工具报告的同一事件，只计一次，同时保留所有来源。
• **输出：**将原因、影响和修复方式相同的候选项合并为一条发现，保留来源信息，并明确协调相互矛盾的证据。

不要将发现的范围扩大到限定的更改之外。仅在辅助上下文中可见的重复内容可以支持范围内的发现，但不能单独作为一条发现。

声明与规范

查找缺失或不完整的要求、错误行为以及未经请求的范围。引用提出该要求的来源，或将该声明标明为推断。

工程质量

• 在适用时追踪变更输入、授权、状态转换、故障、重试、并发、幂等性、删除和副作用。
• 在接受新的辅助工具、模式、格式或抽象之前，先搜索当前检出仓库。对同一概念采用第二种表示或实现属于缺陷，除非仓库说明了其存在理由。
• 优先采用删除、复用、直接控制流和现有依赖。报告死路径、重复、推测性分层、不必要的包装器、只使用一次的间接层，以及平台或依赖已提供的自定义代码。
• 要求名称、类型、边界和接口能体现意图。注释应解释理由、约束或不明显的行为，而不是翻译代码；不要求周边注释密度。
• 将对同一符号或文件的重复变更视为架构风险信号，而非其本身就是缺陷。当测得的变更频率与职责混杂、反复修复或回退、相互竞争的表示、较大的影响范围、不稳定的接口或薄弱的回归覆盖同时出现时，应报告 ARCHITECTURE_RISK 发现。注明时间窗口、触及次数、粒度和伴随信号。
• 通用最佳实践和记忆中的库行为只能作为线索。应根据当前检出的代码、确切的已安装版本以及最新官方文档或源码核实发现。仓库决策优先于通用偏好。

新鲜审查报告

报告术语属于接口：milestone-rush、审查工具和审计等调用方会按字面匹配这些术语，因此改写会破坏交接。车道映射、审查维度、车道状态和角色必须使用以下原词：review-axis-to-lane map；de-duplication、claim and specification、engineering quality、discoverability；complete、incomplete；coordinator、worker。术语后可附简短的通俗解释，但不得替换术语。运行了车道时，应使用映射中的术语标记该部分，并在其中将自己的角色描述为 coordinator。简短报告可以压缩措辞，但必须保留以下所有适用字段。

进行新鲜审查时，先给出结论：APPROVE、APPROVE WITH IMPROVEMENTS 或 REQUEST CHANGES。报告结束本技能步骤。若直接启动，则按交付设置继续；若使用 entry-points: deliver，则将已审查的变更及其已验证发现交给 /deliver，由其修复发现、验证并将变更发布到配置的端点（若没有 ORCHESTRATION.md，则发布至 ready-to-merge）。若使用 stop，则以本报告结束。

请包含：

• 已审查的主张、比较边界、提交和工作区脏状态；
• 已启用和跳过的审查维度，以及每项跳过的原因；
• 涵盖的实质性工程质量问题，以及因变更的运行时路径未触及而跳过的条件性问题；
• 若审查委派了车道，列出包含各车道 complete 或 incomplete 状态的 review-axis-to-lane map、协调者筛除的候选 worker 及筛除原因（与发现分开列出），以及协调者完成的每项后备工作及其原因，或说明无需后备工作；
• 变更频率统计窗口、符号／文件覆盖情况和架构风险热点；
• 确切的探查和检查及观察到的结果；
• 去重覆盖范围、合并的证据来源，以及合并或冲突的候选发现；
• 可执行的发现，格式如下： [CR-N][BLOCKING|IMPORTANT|IMPROVEMENT|NITPICK][CLAIM|QUALITY|ARCHITECTURE_RISK| DISCOVERABILITY] file:line: 证据、影响、收益、不处理的后果、最小修复方案；
• 已验证的主张、仅静态检查或尚未触及的区域，以及保留的探查产物。

所有字面的仓库路径、文件名（包括无扩展名的文件）、变量、函数、方法、类、类型及其他代码标识符，都必须使用行内代码格式。代码跨度之外的内容使用普通文本。 补救建议应告知作者如何更新、提交或发布分支，并应指明仓库文档中规定的机制，而不是泛泛而谈。首先检查项目的 Git 工作流：如果工作流禁止对普通分支执行变基，就写“将基分支合并进来”；只有在确认属于分支栈的分支上，才使用栈命令。对于通过报告发布的评审评论和拉取请求文本，也应遵循同一原则。如果调用方已在拉取请求中记录评审结果，应按拉取请求描述中的指示记录。

BLOCKING 表示无法安全发布。IMPORTANT 表示在正确性、安全性、可运维性、测试价值、可维护性、简化或易理解性方面存在实质性代价。IMPROVEMENT 表示经验证确实值得进行的简化，或与当前实践保持一致。NITPICK 表示影响范围小、局部的润饰问题，且有明确的补救办法，并有仓库惯例或当前代码作为依据；不得体现个人偏好。省略赞扬、对差异的叙述、主观的风格偏好，以及没有具体影响的问题。

每条发现还应陈述以下三项事实，不对是否采取行动作出判断：影响，即该发现对当前代码中的哪些内容或对象造成影响；收益，即修复后会有哪些改善；若不处理，即置之不理会具体导致什么后果。如果仓库有依据这些事实作出决策的政策，应由该政策决定采取哪些行动；对于决定不处理的发现，应视为已解决。

未解决的 BLOCKING 或 IMPORTANT 发现会阻碍就绪。可选的润饰不会阻碍就绪，但无论严重性如何，都必须解决每一处经验证未满足约定要求的差距；降低严重性并不意味着可以免于解决。