code-review

完成复杂软件开发任务后的代码审查

对范围内的更改进行结构化审查。两种模式：

• 审查刚完成或被要求修复的工作——先审查，再应用修复并验证。
• 仅被要求审查——给出明确、可执行的反馈后停止，让用户决定采取哪些措施。不要开始编辑。

工作流

1. 在代码库中搜索所有说明代码编写规范的文件。若存在，必须将 CODING_STANDARDS.md 和 CONTRIBUTING.md 列入清单。将清单传递给子 Agent。
2. 并行启动多个子 Agent，按审查维度（见下文）或代码库区域拆分工作，对更改进行严格审查。
3. 将他们的发现整理成简洁的编号列表，并为每项标注严重、一般或轻微。
4. 在报告或处理每项发现前，先对照实际代码进行验证。子 Agent 可能会报告误报；处理虚构的问题只会让代码变得更糟。

应用修复

仅适用于修复模式。如果你只被要求审查，请在第 4 步后停止并报告发现。

1. 修复已确认的问题。
2. 重新运行项目的 lint、测试和构建流程。
3. 阅读每项修复，确认它解决了对应问题，且没有破坏原任务或引入新问题。流程全部通过只能证明机械层面正确。
4. 完成这一次验证后即停止；不要再重新进行一轮完整审查。

如果某项发现特别复杂或反复出现，请使用系统化调试技能查明根本原因。

审查维度

指导子 Agent 从以下维度评估更改。下列问题仅供参考，并非固定清单。应根据代码库的语言、领域和惯例，采用适用的问题，并提出真正重要的关注点：

• 正确性——是否按任务要求实现？是否处理了边界情况（空值、空内容、边界值）和错误路径，而不只是正常情况？测试是否实际覆盖了新增行为？
• 可读性——对于未参与编写的人，名称和控制流是否清晰？能否简化或缩短？每个抽象是否值得其复杂度？
• 架构——是否遵循现有模式和模块边界，还是无充分理由地引入了新模式？是否存在应当共享的重复代码？是否引入了现有技术栈已有支持的新依赖？
• 安全性——是否在边界处验证不可信输入？代码或日志中是否包含机密？是否存在注入问题（SQL、Shell、路径）、缺少授权检查，或在逻辑与输出中不安全地使用外部数据？
• 性能——对于此类代码，哪些操作成本高？是否存在算法复杂度过高、热路径中重复工作或内存分配、N+1 查询、无界抓取、缺少分页、同步行为或关键路径上的阻塞操作？

为自己（或子 Agent）创建检查清单或待办事项，确保审查覆盖全面。

异味基线

除仓库文档中的内容外，可读性和架构两个维度始终包含 Fowler 的这组固定代码异味（重构，第 3 章）。即使仓库没有记录任何自身标准，也适用这组异味。以下两条规则具有约束力：

• 以仓库标准为准。 仓库中有文档记录的标准始终优先；如果标准认可了基线会标记的做法，就抑制相应异味。
• 始终需要判断。 每种异味都是带标签的启发式判断（“可能存在 Feature Envy”），而不是硬性违规。跳过工具已强制执行的内容。

将此列表原样传给子 Agent——他们无法通过其他途径获取。每种异味都按_问题是什么_ → _如何修复_的顺序说明；将其与差异进行比对，并在审查发现中指出异味名称。

• 神秘命名 - 函数、变量或类型的名称无法说明它的用途或所包含的内容。→ 重命名；如果想不出清晰的名称，说明设计本身含糊不清。
• 重复代码 - 更改中的多个代码块或文件出现相同的逻辑结构。→ 提取共用结构，并在两处调用。
• Feature Envy - 某个方法访问其他对象数据的次数多于自身数据。→ 将该方法移到它所依赖的数据所在对象上。
• 数据团块 - 同一组少数几个字段或参数总是一起传递（说明它们需要成为一个类型）。→ 将它们封装成一个类型并传递该类型。
• 基本类型偏执 - 用基本类型或字符串代替本该拥有自身类型的领域概念。→ 为该概念创建一个小型专用类型。
• 重复的分支判断 - 更改中反复出现针对同一类型的 switch／if 级联判断。→ 改用多态，或让两处共用一个映射。
• 霰弹式修改 - 一个逻辑上的更改迫使你在差异中多个文件里零散修改。→ 将相关的可变部分集中到一个模块中。
• 发散式修改 - 修改一个文件或模块的原因彼此无关。→ 拆分模块，使每个模块只因一个原因而修改。
• 投机性通用化 - 为任务并不需要的需求添加抽象、参数或钩子。→ 删除这些内容；内联回去，直到出现真实需求。
• 消息链 - 调用方不应依赖的长串 a.b().c().d() 导航。→ 在第一个对象上封装整个调用链。
• 中间人 - 某个类或函数基本上只是在转发调用。→ 删除它，直接调用真正的目标。
• 拒绝继承 - 子类或实现类忽略或重写了继承内容中的大部分部分。→ 放弃继承，改用组合。

校准

• 标准是“这是否能改进代码库”，而不是“我会不会这样写”。不要为了凑数而凭空编造问题，也不要仅因风格偏好而重写可运行的代码。
• 也不要淡化或认可真正的问题。应直截了当地说明，并尽可能量化影响（“这会让每行多出约 50 ms 的 N+1 查询开销”胜过“这可能会变慢”）。
• 测试通过是必要条件，但并非充分条件。测试无法发现架构、安全或可读性问题，因此仍须审查这些方面。

死代码

重构会留下孤立代码。修改代码后，列出所有因此不再使用的内容（被替换的函数、组件、常量），并在移除前征求同意，而不是悄悄删除或任其腐烂。

子 Agent 指南

适当时使用子 Agent 并行处理工作，减少主对话的上下文膨胀。

• 告知子 Agent，输出应简洁、可操作，并聚焦于你所做的更改，而非细枝末节的风格问题。
• 只提供他们无法从代码本身推断出的上下文。
• 为每个 Agent 划定明确范围，避免职责重叠或审查无关代码。

报告

修复内容或发现的问题就是交付成果，因此请开门见山地说明（简洁的）结果，不要先写铺垫或描述处理过程。

• **仅审查：**按严重程度排列发现的问题，每项包含 file:line、问题和具体修复方法。如果没有发现实质性问题，请用一行说明。
• **修复模式：**先说明修复了什么，再说明未修复的内容及原因。将延期处理或超出范围的问题各用一行列出，供用户决定，并注明流水线结果。

直接说明实际问题，不要使用含糊措辞（如“可以考虑”“或许可以”）；将可选事项标为低优先级，然后继续。将风格方面的小问题合并为一条说明，不要分散列出。结尾不要用总结重复列表内容。简短地指出少数关键问题，胜过用显而易见的内容凑成长篇报告。