thermo-nuclear-code-quality-review

热核级代码质量审查

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

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

核心提示词

从以下基准开始：

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

不可妥协的附加标准

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

0. 积极寻求简化结构。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fowler 代码异味启发式

发现以下异味时，请标注。这些是 Fowler 在《Refactoring》第 3 章中提出的启发式，并非自动阻断项。只有当异味也违反了上述不可妥协的规则时，才升级处理。若异味只是局部润色问题，则作为评论指出即可。

每种异味都说明了其表现和修复方式：

• 神秘命名：函数、变量或类型的名称无法说明其作用或所存内容。→ 重命名。如果找不到恰当的名称，说明设计模糊；这是结构性问题，而不是吹毛求疵的命名问题。
• 重复代码：相同的逻辑结构出现在多个代码块或文件中。→ 提取共用结构，并在两处调用。
• 依恋情结：某个方法访问另一个对象的数据多于访问自身数据。→ 将该方法移到它所依恋的数据所属对象中。
• 数据泥团：相同的几个字段或参数总是一起传递（仿佛某个类型正等待被创建）。→ 将它们封装成一个类型，并传递该类型。
• 基本类型偏执：用基本类型或字符串代替值得拥有独立类型的领域概念。→ 为该概念创建一个小型独立类型。
• 重复的 Switch：同一类型上的相同 switch/if 级联在此次变更中反复出现。→ 用多态替代，或使用两处共用的映射表。
• 霰弹式修改：一个逻辑变更迫使你在许多文件中分散修改。→ 将相关变更集中到一个模块中。
• 发散式变化：一个文件或模块因多个无关原因而被修改。→ 拆分它，让每个模块只因一个原因而变化。
• 投机性通用性：为假设中的未来需求添加抽象、参数或钩子。→ 删除它；内联回去，直到出现实际需求。
• 消息链：调用方不应依赖的冗长 a.b().c().d() 导航。→ 在第一个对象上用一个方法封装这段访问过程。
• 中间人：主要只负责向下委派的类或函数。→ 删除它，直接调用真正的目标。
• 被拒绝的馈赠：子类或实现者忽略或重写了继承的大部分内容。→ 移除继承，改用组合。

主要审查问题

对于每一项有意义的变更，都请思考：

• 有没有一种“代码柔道”式的做法，能让代码大幅简化？
• 能否重新设计这项变更，以减少概念、分支或辅助层？
• 这会改善还是损害局部架构？
• diff 是否增加了分支复杂度，而更好的抽象本可以避免这种情况？
• 原本内聚的模块是否变得耦合更紧、状态更多，或更难浏览？
• 这段逻辑是否位于正确的文件和层级？
• 这项变更是否让文件或组件膨胀到超出健康的大小边界？
• 是否存在表明缺少模型或辅助工具的重复条件判断？
• 实现是否直接易读，还是依赖特殊情况和偶然的控制流？
• 这个抽象是否真正发挥了作用，还是只是个包装器？
• diff 是否引入了类型转换、可选性或临时拼凑的对象形状，从而掩盖真正的不变量？
• 这段逻辑是否位于规范层，还是 diff 让细节泄漏到了边界之外？
• 这段编排是否不必要地更顺序化或不够原子化？
• 这是否符合某种命名的 Fowler 代码异味，其修复是否属于结构调整，而非局部润色？

应积极标记的问题

遇到以下情况时，应升级处理：

• 实现复杂，而通过更清晰的重新设计可以消除整类复杂性。
• 重构只是挪动代码，却没有减少读者需要记住的概念数量。
• PR 导致文件超过 1000 行，尤其是新增代码本可以拆分出去的情况。
• 在无关的代码路径中追加新的条件分支。
• 一次性布尔值、可空模式或标志让现有控制流变得复杂。
• 特定功能的逻辑泄漏到通用模块中。
• 通用的“魔法”处理掩盖了简单结构，让代码更难推理。
• 薄包装器或恒等抽象增加了间接层，却没有带来任何简化。
• 不必要的类型转换、any、unknown 或可选参数模糊了真正的契约。
• 复制粘贴逻辑，而不是提取辅助函数。
• 在已经繁忙的函数中间处理狭窄的边缘情况。
• 重构虽然通过了测试，却让代码的模块化程度或可读性变差。
• 可能会成为永久负担的“临时”分支。
• 代码库已有规范工具，却另行编写专用辅助函数。
• 本应放在更中心位置的逻辑，却被加到了错误的层或包中。
• 明显可以并行执行的独立工作，却采用了顺序异步流程。
• 部分更新逻辑导致状态的原子性不必要地降低。
• Feature Envy、Data Clumps、Shotgun Surgery、Message Chains 或 Refused Bequest 还会纠缠流程或泄漏边界。

首选解决方案

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

• 删除整个间接层，而不是对其进行润色。
• 重新设计状态模型，让条件分支消失，而不是把它们集中起来。
• 调整所有权边界，让该功能自然扩展现有抽象。
• 将特殊情况逻辑改为更简单、例外更少的默认流程。
• 提取辅助函数或纯函数。
• 将大文件拆分为更小、职责更集中的模块。
• 将特定功能的逻辑置于专用抽象之后。
• 用类型化模型或显式分发器替代条件链。
• 将编排与业务逻辑分离。
• 将重复分支合并为一个更清晰的流程。
• 删除无法实质性阐明 API 的包装器。
• 复用现有的规范辅助函数，而不是引入近似重复项。
• 明确类型边界，让控制流变得更简单。
• 将逻辑移至已有该概念所有权的包、模块或层。
• 在并行化独立工作的同时简化编排。
• 将相关更新重构为更原子的流程，避免部分状态更难推理。
• 将方法移至它所依赖的数据上。
• 将总是一起传递的字段归入同一类型。
• 将出于相同原因而分散的修改集中到一个模块中。
• 在第一个对象上用一个方法封装消息链。
• 用组合替代不恰当的继承。

如果真正的问题在于结构，不要满足于“也许可以改个名字”之类的反馈。 如果有合理的路径能让想法变得简单得多，也不要满足于仅仅把同一个杂乱想法整理得更干净。

评审语气

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

好的表达：

• this pushes the file past 1k lines. can we decompose this first?
• this adds another special-case branch into an already busy flow. can we move this behind its own abstraction?
• this works, but it makes the surrounding code more spaghetti. let's keep the behavior and restructure the implementation.
• this feels like feature logic leaking into a shared path. can we isolate it?
• this abstraction seems unnecessary. can we just keep the direct flow?
• why does this need a cast / optional here? can we make the boundary more explicit instead?
• this looks like a bespoke helper for something we already have elsewhere. can we reuse the canonical one?
• i think there's a code-judo move here that makes this much simpler. can we reframe this so these branches disappear?
• this refactor moves complexity around, but doesn't really delete it. is there a way to make the model itself simpler?
• this looks like Feature Envy. can we move this onto the type that owns the data?
• these fields always travel together. that's a Data Clump. can they be one type?
• one change is touching many files. can we gather this so it isn't Shotgun Surgery?

输出要求

按以下顺序优先指出问题：

1. 结构性代码质量退化
2. 错失大幅简化或代码重构的机会
3. 意大利面式代码或分支复杂度增加
4. 让代码更难理解的边界、抽象或类型契约问题
5. 文件大小和拆分问题
6. 模块化和抽象问题
7. 可读性和可维护性问题

如果存在更严重的结构性问题，不要堆砌低价值的细枝末节。 优先给出少量有充分依据的评论，而不是一长串外观方面的意见。

批准标准

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

• 没有明显的结构性退化
• 在存在明显路径的情况下，没有错失让实现大幅简化的机会
• 文件大小没有无正当理由地膨胀
• 没有因特殊情况分支而明显增加意大利面式代码
• 没有明显牵强或充满魔法、让代码更难理解的抽象
• 没有不必要的包装器、强制类型转换或可选性改动掩盖真实设计
• 没有明显的架构边界泄漏或可避免的规范辅助函数重复
• 没有错过能显著改善可维护性的明显拆分机会

以下情况应视为推定阻碍批准的问题，除非作者能给出充分理由：

• PR 保留了大量偶然复杂性，而显然存在可以删掉这些复杂性的代码重构方案
• PR 将文件从不足 1000 行扩展到超过 1000 行
• PR 添加临时分支，让已有流程更加纠缠
• PR 通过在共享代码中散布功能检查来解决局部问题
• PR 添加不必要的抽象、包装器，或充满强制类型转换的契约，让设计更加迂回
• PR 重复现有辅助函数，或把逻辑放在错误的层中，而显然存在规范的归属位置

如果不符合以上情况，请给出明确、可执行的反馈，并推动更清晰的拆分。