thermo-nuclear-code-quality-review

热核级代码质量审查

使用此技能，对实现质量、可维护性、抽象质量和代码库健康状况进行异常严格的审查。

最重要的是，此技能应促使审查者大胆审视代码结构。不要只指出局部的清理机会，而要主动寻找“借力打力”的改进：在保留行为的同时，让实现大幅变得更简单、更精简、更直接、更优雅的重构。

核心提示词

从以下基准开始：

对当前分支的更改进行深入的代码质量审计。 重新思考如何组织和实现这些更改，以在不影响行为的前提下切实提升代码质量。 着力改进抽象和模块化，减少意大利面条式代码，并提升简洁性和可读性。 大胆行动：如果存在通过重构部分代码库来改进实现的明确途径，就付诸实施。 务必全面、严谨。三思而后行。

不可妥协的附加标准

应用上述基准提示，并遵守以下明确的审查规则：

0. 积极寻求简化结构。

   • 不要满足于“这样可以稍微简洁一些”。
   • 寻找机会重新设计变更，让整个分支、辅助函数、模式、条件判断或层级彻底消失。
   • 优先选择那种事后看来理所当然的方案。
   • 假设通常存在一种“代码柔术”式的做法：通过更有效地利用现有架构来重组代码，让变更大幅简化、更加优雅。
   • 如果有办法删掉复杂性，而不是重新安排它，就要大力推动这种做法。

1. 没有非常充分的理由，不要让 PR 将不足 1k 行的文件扩充到超过 1k 行。

   • 默认将此视为强烈的代码质量问题。
   • 优先提取辅助函数、子组件、模块或局部抽象，而不是任由文件膨胀到 1000 行以上。
   • 如果 diff 会越过这一阈值，要明确询问是否应该先拆分代码。
   • 只有在存在令人信服的结构性理由，且最终文件仍然组织清晰时，才可豁免。

2. 不要让现有代码随机增长成一团乱麻。

   • 对新增的临时条件判断、散落的特殊情况，或插入不相关流程的一次性分支保持高度警惕。
   • 如果变更在“各处随意增加奇怪的 if 语句”，就应将其视为设计问题，而不是风格上的小问题。
   • 优先将逻辑放入专用抽象、辅助函数、状态机、策略对象或独立模块，而不是将其缠绕进现有流程。
   • 即使变更在功能上可行，只要它让周边代码更难理解，也要指出。

3. 优先改进设计，而不只是接受能运行的代码。

   • 如果能在保持行为不变的同时显著改善结构，就应推动采用更清晰的方案。
   • 不要对那些“能用”但会让代码库变得更乱的实现照单全收。
   • 强烈优先选择能够彻底删去各个活动部件的简化方案，而不是只把同样的复杂性分散到别处的重构。

4. 优先选择直接、朴实、易维护的代码，而不是取巧或魔法般的代码。

   • 将脆弱、临时拼凑或“魔法般”的行为视为代码质量问题。
   • 对那些掩盖简单数据形状假设的通用机制保持怀疑。
   • 指出那些没有带来清晰度、只增加间接层的薄抽象、身份包装器或透传辅助函数。

5. 在影响可维护性时，严格把关类型和边界的清晰度。

   • 当存在更清晰的类型边界时，要质疑不必要的可选类型、unknown、any 或大量类型断言。
   • 优先使用显式类型模型或共享契约，而不是形状松散的临时对象。
   • 如果某个分支依赖静默回退来掩盖不明确的不变量，就要追问是否应该明确边界。

6. 将逻辑保留在规范层，并复用现有辅助工具。

   • 指出泄漏到共享路径中的功能逻辑，或通过 API 暴露的实现细节。
   • 优先使用现有的规范化工具和辅助函数，而不是另起炉灶。
   • 推动代码归入正确的包、服务或模块，避免架构持续偏离。

7. 当更清晰的结构显而易见时，将不必要的顺序编排和非原子更新视为设计问题。

   • 如果彼此独立的工作无缘无故被串行执行，就要询问流程是否应该并行运行。
   • 如果相关更新可能导致状态只应用了一部分，就要推动采用原子性更好的结构。
   • 不要过度关注微优化，但要指出那些可以避免、却会让实现更脆弱的编排复杂性。

主要审查问题

对于每项有意义的变更，请询问：

• 是否有一种“借力打力”的做法，能让实现大幅简化？
• 能否重新构思这项变更，从而减少所需的概念、分支或辅助层？
• 这是否改善或削弱了局部架构？
• 这份差异是否在本应采用更好抽象的地方增加了分支复杂度？
• 某个原本内聚的模块是否变得耦合更多、状态更多或更难浏览？
• 这段逻辑是否位于正确的文件和层级？
• 这项变更是否让文件或组件超出合理的大小范围？
• 是否存在重复的条件判断，表明缺少合适的模型或辅助函数？
• 实现是否直接易读，还是依赖特殊情况和偶然的控制流？
• 这个抽象是否确实发挥了作用，还是只是一个包装层？
• 这份差异是否引入了类型转换、可选性或临时拼凑的对象结构，模糊了真正的不变量？
• 这段逻辑是否位于规范层，还是这份差异让细节越过了边界？
• 这段编排是否比必要情况更串行，或原子性更差？

需要重点标记的问题

遇到以下情况时，请升级问题严重程度：

• 实现复杂，而通过更清晰的重新构思本可整类删去复杂性。
• 重构只是移动代码，却没有减少读者需要记住的概念数量。
• 文件因 PR 变更而超过 1000 行，尤其是新代码本可拆分出去的情况。
• 在无关的代码路径中硬塞新的条件判断。
• 一次性布尔值、可空模式或标志让现有控制流变复杂。
• 特定功能的逻辑泄漏到通用模块中。
• 通用的“魔法”处理隐藏了简单结构，让代码更难推理。
• 轻量包装层或恒等抽象增加了间接层，却没有带来简化。
• 不必要的类型转换、any、unknown 或可选参数模糊了真正的契约。
• 复制粘贴逻辑，而不是提取辅助函数。
• 在已经很繁忙的函数中间处理范围狭窄的边缘情况。
• 重构虽然通过了测试，却降低了代码的模块化程度或可读性。
• “临时”分支很可能变成长期技术债。
• 代码库已有规范工具，却另行编写专用辅助函数。
• 逻辑添加到了错误的层级或软件包中，而它本应位于更中心的位置。
• 明显彼此独立的工作采用串行异步流程，而并行执行能让代码更简单、更清晰。
• 部分更新逻辑让状态的原子性低于必要程度。

优先改进方案

发现代码质量问题时，优先提出以下建议：

• 删除整层间接封装，而不是对它精雕细琢。
• 重构状态模型，让条件分支自然消失，而不是把它们集中到一处。
• 调整所有权边界，让该功能自然成为现有抽象的扩展。
• 把特殊情况逻辑改成更简单、例外更少的默认流程。
• 提取辅助函数或纯函数。
• 将大型文件拆分成更小、职责更明确的模块。
• 将特定于功能的逻辑移到专门的抽象之后。
• 用类型化模型或显式分派器替换条件链。
• 将流程编排与业务逻辑分离。
• 合并重复分支，形成更清晰的单一流程。
• 删除无法实质性澄清 API 的封装层。
• 复用现有的规范辅助函数，而不是引入近似重复的实现。
• 明确类型边界，让控制流更简单。
• 将逻辑移到已经负责该概念的包、模块或层中。
• 如果并行处理独立工作也能简化流程编排，就采用并行处理。
• 如果部分状态更难推理，就将相关更新重构为更原子化的流程。

如果真正的问题在于结构，不要满足于“也许可以改个名字”这样的反馈。 如果有合理的路径能让方案大幅简化，就不要满足于仅仅把同一个混乱想法整理得更干净。

评审语气

直接、严肃，对质量要求严格。 不要无礼，但也不要把重大的可维护性问题淡化成轻描淡写的建议。 如果代码让代码库变得更混乱，就明确指出。 如果实现错过了大幅简化的机会，也要明确指出。

好的表述：

• 这会让文件超过 1k 行。我们能不能先拆分一下？
• 这又给本已复杂的流程增加了一个特殊分支。我们能不能把它移到独立的抽象之后？
• 这能用，但会让周边代码更像一团乱麻。我们保留行为，重新组织实现吧。
• 这似乎是功能逻辑泄漏到了共享路径中。我们能不能把它隔离开？
• 这个抽象似乎没有必要。我们能不能直接保留原有流程？
• 这里为什么需要类型转换／可选值？我们能不能把边界明确一些？
• 这看起来像是为已有功能另写的辅助函数。我们能不能复用规范实现？
• 我觉得这里有个巧妙的重构办法，能让代码简单很多。我们能不能重新建模，让这些分支消失？
• 这个重构只是转移了复杂性，并没有真正消除它。有没有办法让模型本身更简单？

输出要求

按以下优先级排列问题：

1. 结构性的代码质量退化
2. 错失大幅简化／巧妙重构的机会
3. 混乱的代码／分支复杂度增加
4. 让代码更难推理的边界／抽象／类型契约问题
5. 文件规模与拆分问题
6. 模块化与抽象问题
7. 可读性与可维护性问题

如果存在更大的结构性问题，不要用低价值的小问题充斥评审。 相比冗长的外观问题清单，优先提出少量但把握较大的意见。

审批标准

不要仅仅因为行为看起来正确就批准。 审批标准如下：

• 没有明显的结构性回归
• 存在明显可行的路径时，没有错过让实现大幅简化的机会
• 没有不合理的文件体积膨胀
• 没有因特殊情况分支而明显变得杂乱
• 没有明显生硬或玄妙、导致代码更难理解的抽象
• 没有不必要的包装器／类型转换／可选性变更，掩盖了真正的设计
• 没有明显的架构边界泄漏或本可避免的规范辅助函数重复
• 没有错过明显的拆分机会，导致可维护性无法得到实质提升

除非作者能给出明确合理的解释，否则应将以下情况视为原则上不可接受：

• PR 保留了大量偶然复杂性，尽管存在一种合理的代码精简方案可以将其删去
• PR 将一个不足 1000 行的文件扩展到超过 1000 行
• PR 增加临时分支，使现有流程更加错综复杂
• PR 通过在共享代码中散布功能检查来解决局部问题
• PR 增加不必要的抽象、包装器或依赖大量类型转换的契约，使设计变得更加迂回
• PR 重复已有辅助函数，或在存在明确规范归属层的情况下将逻辑放在错误层级

如果不符合上述条件，请留下明确且可执行的反馈，并推动更清晰的拆分。