用途:对 diff、包或 API 进行代码审查。审查前必须先用一句话说明代码解决的问题,若说不清应先提问,避免在猜测目的的前提下审查。
三种视角(每次只选一种,不可混用,否则优先级判断会互相矛盾):Russ Cox(RUSS-COX.md)——这段代码是否该存在、是否处于正确分层、是否值得其维护成本,适用于被要求 audit、polish 或 refactor 时;BurntSushi(BURNTSUSHI.md)——行为是否符合宣称、是否会 panic、静默截断或成本超预期,默认值与错误契约是否诚实,适用于审查库 API 或改变复杂度的补丁;Mitsuhiko(MITSUHIKO.md)——是否被套用了错误的标准、该不该直接发布简单版本、是否需要长期稳定,适用于审查公共接口、破坏性变更或看似过度设计的产品代码。无特别说明的“review this diff”默认用 Russ Cox;库边界用 BurntSushi;产品/库定位本身存疑用 Mitsuhiko。在既有代码库中,任何视角下都应先搜索已有原语,最常见发现是已有 helper、接口或包实现了该功能。
输出契约:先自由分析,读够后再输出。每条发现一个块,按影响从大到小排列,格式为 [file:line] 一行结论(traced 或 inferred);Failure: 具体输入或状态 → 错误输出、崩溃或成本;Instead: 一个替代方案草图。无法给出具体输入导致具体错误行为的,不算发现,应丢弃而非弱化为建议。traced 表示已跟踪路径,inferred 表示从形态推断,两者不可混淆。结尾用一行说明已检查且确认无误的部分(覆盖范围而非赞美),再附简短 Summary。不挑剔风格、命名或格式,除非影响正确性或成本。只报告实际发现,不按数量凑数。
接受妥协:作者以“周五要发布”回应时,审查者仍需裁决。可接受:硬性截止日期加书面债务计划、法规合规要求、明知风险的供应商锁定、团队技能限制加培训。接受方式:在代码中记录决定、写带日期的偿还计划、缩小捷径范围、设定复审日期;无偿还触发条件的妥协只是更礼貌的缺陷。绝不可接受:安全漏洞、数据完整性风险、静默失败、未测试的关键路径,这些没有截止日期例外,应明确说明并保持最高优先级。
措辞:发现应携带分析而非判决。例如不说“太复杂”,而说“有 N 层间接,能否直接解决:[草图],收益:[列表],权衡:[列表]”。
不适用:撰写 commit 或 PR 信息(用 write-docs)、编辑前评估复杂度与价值(用 complexity-budget)、审查新人难以理解之处(用 newcomer-lens-review)。
限制:资料未提供安装命令、平台支持、收费方式或具体运行步骤。