系统化代码审查与 /review 工作流

代理生成代码速度快，但未经独立审查的改动不等于合格交付。系统化审查的价值在于用新鲜上下文、固定清单与结构化分级，发现作者视角下的盲点。本节梳理审查命令、双角色工作流与可执行的审查清单。

一、可用的审查入口

能力	定位
/review	在会话内对当前工作进行代码审查，结合上下文给出问题清单
/code-review	以新鲜子代理（fresh subagent）审查当前差异（diff），避免继承作者思路偏见
/verify	代理自检通过后，人工对运行中的应用做最终复核，确认行为而非只看代码
只读审查子代理	授予只读工具、按团队清单输出意见，不直接修改代码

具体可用项随版本演进，实际以当前安装版本的命令列表与帮助为准；本节强调的是审查方法与组织方式。

二、Writer / Reviewer 双角色工作流

1. 作者会话（Writer）：按方案实现、运行自检，产出变更与测试结果。
2. 审查会话（Reviewer）：在新鲜上下文中只看差异与相关源码，不带作者的实现理由，按清单找问题。
3. 反馈回流：审查意见带回作者会话，区分必须修复与可选建议；修复后再进入下一轮审查。
4. 最终人工验证：代码审查通过后，结合 /verify 思路在真实运行状态确认关键路径行为。

把审查放进独立会话/只读子代理，比让实现者"自查"更能暴露边界条件、一致性遗漏与潜在缺陷。

三、结构化审查清单

维度	重点问题
正确性	逻辑是否实现目标、分支与边界值是否覆盖、是否有空值/越界
错误处理	失败路径是否处理、错误是否可诊断、是否吞异常
并发与状态	共享状态、竞态、资源释放与幂等性
一致性	是否遵循既有模式、命名与结构、重复逻辑是否合并
测试充分性	正常/异常/边界用例、回归用例是否到位（详见下一章）
安全与敏感数据	注入、越权、凭据与日志脱敏（见安全加固节）
可维护性	复杂度、职责清晰度、注释与文档、可删除的冗余
性能敏感点	循环内重操作、不必要的全量读取与 I/O 放大

四、问题分级与闭环

• 阻断级（必须修复）：逻辑错误、崩溃风险、安全漏洞、缺失关键回归测试。
• 建议级（应当修复）：一致性、可读性、错误处理缺口、命名不清。
• 可选级（记录待办）：风格偏好、未来重构机会，不阻塞本次合入。

每条意见应带文件、位置与依据，避免空泛评价；修复后复审只针对变更范围，控制审查成本。审查不能替代自动化测试与真实运行验证，三者互补。

五、审查轮次节奏与证据要求

轮次	由谁执行	产出与证据
作者自检	作者会话	测试/构建输出、改动清单、自查结论；不视为最终审查
独立代码审查	新鲜只读会话或审查子代理	按第三节分级输出意见，每条附文件位置与理由
修复复审	作者修复 + 审查者复核变更范围	阻断级意见关闭记录、回归测试结果
运行态最终验证	人工结合 /verify 思路	关键路径实际行为确认，而非只看代码静态结论

• 审查意见落地为可执行项：阻断级必须关闭，建议级评估后决定修或登记，可选级记入待办，避免"提了但没结论"。
• 复审只覆盖本轮变更与受影响调用方，不重复展开无关代码，控制成本与噪声。
• 审查输入应包含：差异范围、需求/方案依据、测试结果、已知边界假设，让审查者判断有据可依。

六、FAQ

问题	处理建议
审查者只给风格吐槽、抓不到实质问题	按固定清单（正确性/错误处理/一致性/安全/测试）组织提示，并限定本次变更范围；要求每条意见带位置与风险等级，不接受空泛措辞。
作者和审查者结论冲突	回到可运行证据（测试、复现用例、文档约定）裁决；无法验证的分歧列为待人工确认，不强行合并。
审查发现一大堆历史遗留问题	历史问题另立任务，本次审查只对变更范围负责；避免借审查把无关重构塞进当前改动。
代码审查通过是否就可以发布	不可以：代码审查、自动化测试、真实运行验证三者互补；安全与关键路径还需人工最终确认。

七、动手练习

• 练习：对一段真实改动走"作者自检 → 独立只读审查 → 分级意见 → 修复复审"流程，把每条意见标注阻断/建议/可选并给出关闭依据，复盘哪类问题最容易被作者自查漏掉。