code-review

代码审查

协调一名精简审查者或几名专注于特定领域的专家，以只读方式审查现有变更集，并产出一份有证据支持的报告。

协调者说明

• 使用 fork_turns="none" 启动每位审查者；验证或解决问题时，切勿重复使用同一位审查者。
• 忽略暂存与未暂存状态。将所有未提交的更改作为整体审查；切勿将暂存状态差异报告为问题。
• 将仓库文件保持为只读。使用协作消息记录审查状态。仓库任务完成验证说明适用于实现工作，而非审查工作。
• 将审查开始时可获取的验证结果记录为 Available validation evidence，包括其确切目标，以及已知的实际状态；如果没有，则使用 Unavailable。将这些证据视为背景信息，而非变更正确的证明。
• 根据共享审查背景、任务分配包、功能背景说明及简要参考、审查者说明、适用的模式说明、指定的审查角色，以及第 1 步收集的适用指南，构建每位审查者的启动说明。若接收者可以委派任务，则加入子 Agent 模型选择。将审查范围内的路由和生命周期元数据保留在任务分配包之外，使任务分配包仅描述审查职责；不要要求审查者重新发现范围。
• 安排专家或分批执行，确保每位专家都能启动所需的子级 Agent，同时不超过可用 Agent 数量上限。
• 报告已检查的范围和实际发现。如果缺少背景信息或专业知识导致审查无法完成，则将审查标记为未完成；否则，在没有发现问题时使用“No issues found.”。

功能背景

• 在步骤 1 中，为整个变更集准备一份简短的 Feature context 简报。涵盖目标和预期行为、主要变更及其关联方式、重要约定和限制，以及待解决的问题。采用高层次要点，而非详细的差异摘要。
• 记录评审目标，并注明需求和已接受决策的来源，例如用户任务、规范或拉取请求说明。将明确提出的需求与观察到的代码行为分开。清楚标记推断出的意图和缺失的上下文。
• 在简报中分享功能事实和需求。将候选问题和评审者结论留在针对具体候选项的消息和报告中。使用简报了解功能；基于代码、需求来源、适用指南和证据独立确认问题。共享上下文不会扩大分配的职责范围或候选项列表。
• 步骤 1 完成后，协调者使用 collaboration.post 在本次评审的频道中发布一次简报，并将该帖子的消息 ID 保存到共享上下文中。在启动上下文中，使用该引用代替完整简报文本。向每位评审者、评审子任务、验证者和解决者提供该引用及这些说明。每位接收者在分析代码前使用 collaboration.read_post 阅读完整简报，并可按需再次阅读。委派任务时传递相同的引用。
• 新的权威上下文改变简报时，协调者应发布完整的更新版简报，并将其新引用传递给受影响的进行中任务和后续任务。保留已完成的复现证据和不受影响的候选项处理结论。如果新上下文改变了已完成结论的依据，则使用步骤 2 恢复流程。
• 如果查看简报和可用来源后仍缺少必要的功能上下文，请使用 collaboration.send_message 向上级发送有针对性的问题。等待答复期间，继续独立完成分配的工作。如果仍无法获得答复，请按照现有的未完成评审或人工评审规则报告缺失的上下文。
• 如果消息看板工具不可用，请将简报保留在共享上下文中，并在每条启动消息（包括嵌套任务）中附上完整文本。使用同一份简报，不继承对话历史。

子代理模型选择

• 将此策略应用于每一项子代理任务，包括规划、评审子任务、验证和解决。保持用户主代理的模型和工作量设置不变。

• 普通任务使用配置的子代理默认设置，包括常规最终验证；启动时省略 model 和 reasoning_effort。预期基准为 gpt-6.1-sol，工作量为 xhigh。常规的跨文件追踪、异步 UI 状态以及夹具或保护条件检查均使用此基准。

• 选择更强的设置前，先收集可用上下文并检查任务。拆分彼此独立、会争夺注意力的职责；但需要联合分析的交互约定应放在同一任务中。

• 根据任务的具体推理难度，从以下自动升级选项中选择：

  模型	工作量	适用情形
  gpt-6.1-sol	max	某项范围明确的任务需要跨文件或状态进行较长且定义清晰的推理链。
  gpt-6-astra	high	现有证据支持多种相互竞争的解释，涉及难以区分的交互约定；或范围明确的 Sol 分析留下了一个可凭现有证据解决的具体推理问题，而更强的专业能力可以解决该问题。

• 直接选择所需级别。在任务范围说明之外的路由元数据中记录所选设置和具体原因，并在每次升级时显式传递 model 和 reasoning_effort。

• 在报告中一并返回所有升级记录，以便协调者记录嵌套任务。

审查者说明

• 开始审查代码前，先浏览所有可用技能的名称和描述，包括全局技能和仓库本地技能，判断其与分配范围是否相关。
• 开始审查前，阅读所有相关技能及其要求的参考资料，然后将相关指导应用于行为、惯例和清理决策。提供的领域技能属于已知的适用指导，但并非完整清单。相关代码涉及其他领域时，应阅读其他相关技能。
• 只审查分配的行为，必要时沿着相关代码追查；忽略无关问题。
• 根据适用的全局和仓库说明、领域实践以及可比代码中的既定模式，检查分配的代码。每个审查角色都必须在自己的范围内完成这项检查，即使代码能够正常运行且测试通过也不例外。
• 区分既定惯例和个人偏好。确认示例用途相同，且适用于当前语言、框架和支持的版本。遵守说明优先级和已记录的例外；不要仅为保持一致而照搬过时模式或已知缺陷。
• 每项发现都要提供准确的代码位置和证据。对于缺陷，说明具体触发条件及其后果。对于实践或一致性违规，引用适用规则或可比代码，并解释偏离之处；已证实的惯例违规无需证明会导致运行时故障。一般最佳实践方面的主张，必须说明其对所分配代码的具体益处或风险，不能仅凭偏好提出。将代码检查无法定论的主张作为待确认候选项，并结合所提供的验证信息。
• 将根本原因相同的候选项合并，给每个候选项分配稳定 ID；不得因优先级低、属于表面问题、与可读性有关或容易修复，就删除有依据的候选项。
• 将发现、未完成的审查和需人工审查的候选项分开。对于需要确认重大决策或项目背景、且仓库中无法获取的情况，使用需人工审查；技术分析尚未完成时，使用未完成审查。需说明位置、缺失的背景、后果和所需的人工操作。

精简版审查者说明

• 直接综合审查所有分配角色和领域技能的内容；不要启动子任务或验证器。
• 将候选项及其证据返回给协调者；如果没有候选项，则返回已检查范围和“No issues found.”。
• 对未完成的职责标记为未完成，并说明缺失的背景或专业知识以及已完成的范围；不要猜测。

专家审查说明

• 为每个子任务指定一个边界更窄、自成一体的内部任务，并提供功能背景说明和简要参考、审查者说明以及适用于其范围的指导；要求其直接开展工作，不要调用代码审查编排。不要传递这些通用专家说明或专家角色；由专家自行控制子任务的提示、范围、证据要求和生命周期。
• 委派一项完整的职责，而不是单独的检查清单项目；将子任务证据合并进候选项清单前，先核实证据。
• 合并后的候选项清单为空时，返回已检查范围和“No issues found.”，不要启动验证器。
• 合并后的候选项清单非空时，使用 fork_turns="none" 启动且仅启动一个新的最终发现验证器。将任务标记为内部任务，并向其提供准确的候选项清单及 ID、代码范围、先前证据和复现结果、功能背景说明和简要参考、适用指导，以及最终发现验证器说明。
• 返回验证器确认的所有发现，并保留其稳定 ID。验证器驳回的候选项不得列为发现；验证器无法定论的候选项应单独作为未完成审查返回。

最终发现验证说明

• 直接执行此内部任务，不要调用代码审查编排。仅审查提供的候选项及用于验证它们的代码；不要搜索新的发现，也不要派生子任务。
• 在检查代码以验证候选项之前，先扫描所有可用技能（包括全局技能和仓库本地技能）的名称和描述，然后阅读所有相关技能及其必需参考资料。确认或驳回发现时，遵循这些指导。提供的指导不能替代此技能检查。
• 根据代码位置和证据，独立确认或反驳每个候选项。对于缺陷，检查触发条件和后果。对于实践或一致性违规，检查相关规则或类似示例、其适用性和例外情况，以及偏离之处。对于已证实的约定违规，不要要求必须出现运行时故障；也不要把个人偏好当作规则。复用提供的证据和复现结果；仅当它们尚未判定某项主张时，才运行一次最小化的新只读复现。
• 保留每个候选项的 ID，并且每项只返回一种判定：Confirmed（附支持证据）、Rejected（附相反证据）或 Unresolved（说明缺少的上下文或所需验证）。
• 不要因为已确认的候选项优先级低、仅涉及外观或可读性，或易于修复，就将其抑制或降级。优先级应在验证后确定。

工作流程

步骤 1：选择审查模式并分配任务

• 使用一个 fork_turns="none" 的子 Agent 完成此内部规划任务，以确定审查来源：分支、提交、拉取请求或未提交的更改。向其提供协调者已获得的适用全局指令和用户指令、可用的功能需求及其来源明确的已接受决策、功能上下文指令，以及子 Agent 模型选择策略。除非用户另有指定，只要存在未提交的更改，就审查所有未提交的更改；否则，获取远程默认分支，并将当前分支的全部内容与其最新的远程跟踪引用进行审查。
• 收集适用于变更代码的指导：全局用户指令、根目录及嵌套仓库指令、相关文档和工具配置，以及领域技能。检查相邻代码和共享辅助函数，了解同类实现中既有的模式。记录每条规则或模式及其来源和适用范围，包括相关例外；根据指令优先级解决冲突。在共享上下文中保留这些指导，并将相关部分传递给审查者、子 Agent、验证者和解决者，而不要依赖继承的对话历史。
• 仅当某项职责明确局部、简单、低风险且独立，一个通才就能依据单个任务包完成审查时，才选择 compact。对于授权、安全、隐私、破坏性或事务性数据变更、并发、迁移、公开或跨系统契约、向后兼容性、基础设施、其他重大风险或分类不确定的情况，选择 specialist。
• 文件数或行数可以成为排除 compact 的理由，但不能成为选择 compact 的理由。
• 为每个适用的审查角色明确指定负责人。对于包含大量测试的大型 UI 或状态变更，应将产品行为和测试保障分别交由专人负责；在适用时，还应单独覆盖前端交互。对于小型、连贯的任务，可合并兼容的角色。
• 返回一份审查计划，其中包含：含审查来源和目标的共享上下文、功能上下文摘要、唯一选定的模式及理由、变更的行为或契约、入口点、可用的验证证据以及适用指导；审查者分配表，将每个任务包映射到指定的审查角色、已知适用的领域技能，以及模型升级及其理由；以及仅包含连贯职责和相关代码或上下文的任务包。
• compact 模式必须恰好包含一个覆盖所有变更的任务包。specialist 模式必须为每位专家提供一个单独命名的任务包；仅在涉及跨目标行为时可重叠。将所选模式保留在共享上下文中。不要将 internal 等嵌套任务分配生命周期标记或直接执行限制复制到一级任务包或分配表中；这些内容仅在子 Agent 或验证者指令明确要求时适用。
• 只返回审查计划。将审查者的启动以及候选发现（包括疑似缺陷）留到步骤 2。

第 2 步：分配审查人员并开展审查

• 对于 compact，根据共享上下文、路由信息和单个数据包构建一个启动信封，然后启动一名全新的 compact 审查人员。如果候选列表非空，则启动一名全新的最终问题验证器，并向其提供准确的候选列表和 ID、数据包代码范围、先前证据、功能上下文说明和简要参考、适用指南以及验证器说明。保留审查人员已完成和未完成的范围。
• 对于 specialist 模式，为每个已路由的数据包构建一个启动信封，并为每位选中的专家启动一个全新的子 Agent；必要时分批启动，以便为专家负责的子 Agent 留出容量。
• 收集已验证的审查报告和复现结果。如果新的上下文或专业知识能够解决未解决的 ID，或新的权威上下文改变了已完成处置的依据，则为每个受影响的候选 ID 分别交给一名全新的解析人员，并设置 fork_turns="none"；同时提供所有先前证据、功能上下文说明和简要参考，以及包含来源、范围和例外情况的适用指南。绝不重新执行审查人员分配、重复已完成的复现，或重新审查未受影响的 ID。用解析人员的结果替换受影响的处置；仍未解决的候选项应作为未完成审查单独列出。

第 3 步：向用户提交最终审查报告

• 根据当前已验证的处置结果建立问题台账；对于稳定 ID，使用解析人员的结果替代先前的处置。只有在已确认的 ID 描述同一根本原因时才合并。如果已验证的报告仍有冲突，则在定稿前，将相互冲突的候选 ID、先前证据、功能上下文说明和简要参考，以及包含来源、范围和例外情况的适用指南交给一名全新的解析人员，并设置 fork_turns="none"。解析人员须遵循最终问题验证器说明。
• 除上述冲突处理流程外，第 3 步期间不得检查代码、重新运行验证或启动 Agent；不得仅因去重而启动解析人员。
• 每个已确认的 ID 都必须且只能计入一次，作为独立的最终问题，或作为明确合并后的最终问题的来源。不得因优先级、重要性、报告长度、可读性或清理难易程度而遗漏已确认的问题；优先级只影响排序和标签。
• 回复前核对问题台账，并提供简洁的统计行，列出已确认的审查问题、最终评论、重复项合并数和遗漏数。遗漏数必须为零。
• 报告审查目标、所选模式、实际使用的审查人员和验证器、模型升级及其原因、问题摘要、每条已确认的详细评论，以及经过核实和去重的 Human review 部分；如果无需人工审查，则填写 None.。

审查角色

行为与契约

审查行为逻辑、状态转换、跨文件行为、回归、API 契约和向后兼容性。

数据与并发

审查数据丢失、无效的生命周期转换、事务边界、幂等性、竞态条件，以及对生产数据的假设。

安全与漏洞

审查具体的攻击路径、授权错误、不安全的数据暴露及其安全后果。

隐私与数据保护

审查隐私违规、数据泄露和不安全的数据处理。

性能与资源使用

审查受支持工作负载下的时间和空间复杂度、算法效率、缓存和资源管理。

测试与回归

审查测试是否能够保护预期契约、在该契约被移除时失败，并覆盖重要的负面场景。检查测试夹具、模拟对象和共享守卫是否覆盖已更改的路径，并确认断言能够区分所要求的行为与看似合理但错误的结果。

浪费与可维护性

• 直接审查分配范围内非风格类的死代码、重复代码、临时代码或推测性代码及相关产物。
• 综合审查员也会直接使用适用的语言、框架和 CSS 技能审查可读性与风格方面的冗余；他们不会派生子审查员。
• 冗余专项审查员将范围划分为非风格类和包含风格的部分，但不会直接审查风格方面的冗余。
• 如果存在非风格类代码，则为合并后的范围派生一名可读性子审查员。提供准确的代码范围、适用的仓库和语言或框架说明，以及代码可读性审查员说明；核实并合并其证据。
• 如果存在包含风格的代码，则为合并后的范围派生一名 CSS 子审查员。提供准确的样式范围、适用的 CSS 技能，以及CSS 冗余审查员说明；核实并合并其证据。

代码可读性审查员说明

• 直接执行此内部任务，不调用代码审查编排流程，也不派生子审查员；仅审查提供的代码范围。
• 遵循提供的仓库说明以及适用的语言或框架说明。
• 查找因表达式过于密集、嵌套、抽象层级混杂、命名误导或不必要的间接层而导致意图或执行顺序明显不清晰的代码。将这些因素视为线索，而非穷尽清单。
• 建议能够保持行为和受支持性能特征的最小修改。即使代码简单，也要报告已证实的规范违规；不要报告个人格式偏好。
• 报告已检查的范围和实际发现，并提供准确位置及支持证据；若没有发现问题，则返回“No issues found.”。

CSS 冗余审查员说明

• 直接执行此内部任务，不调用代码审查编排流程，也不派生子审查员；仅审查提供的样式范围。
• 遵循适用的 CSS 技能以及仓库的浏览器目标、构建配置、重置样式和相邻样式上下文。
• 查找无用或重复的选择器和声明。
• 查找经级联、继承或布局上下文证实无效的声明。
• 查找重复的全局或基础样式，以及声明的浏览器目标之外的兼容性变通方案。
• 报告已检查的范围和实际发现，并提供准确位置及支持证据；若没有发现问题，则返回“No issues found.”。

前端与用户体验

审查用户可见状态、无障碍性、交互行为、布局风险和视觉回归。跟踪键盘焦点和可见反馈在状态变化（包括异步响应和替代控件）过程中的表现。