thermo-nuclear-code-quality-review - SKILL.md Agent Skill

name: thermo-nuclear-code-quality-review description: 运行极其严格的可维护性审查，重点检查抽象质量、超大文件、意大利面式条件增长、重复逻辑、低价值测试和有意义的清理机会。用于 thermo-nuclear code quality review、thermonuclear maintainability review、深度代码质量审计、针对变更代码或测试代码的 cleanup/fix 请求、复用检查、垃圾测试清理，或特别严格的可维护性审查。

热核级代码质量审查

使用这个 skill 做一次异常严格的审查，重点关注实现质量、可维护性、抽象质量和代码库健康。

最重要的是，这个 skill 要推动 reviewer 对代码结构保持野心。不要只识别局部清理机会。要主动寻找代码柔道式的重组：在不改变行为的前提下，让实现变得显著更简单、更小、更直接、更优雅。

聚焦清理与修复模式

当用户明确要求简化代码、清理 diff，或修复具体 review 发现时，审查变更文件中的以下问题：

是否可以复用项目已有的 utility、helper、component、type、constant 或约定
是否存在具体可维护性问题，例如重复变体、冗余状态、边界不清、不必要的 public API churn，或类型过弱
是否存在有实际意义的效率问题，例如重复昂贵计算、可避免的串行编排、过宽查询、不必要的 re-render/refetch，或重复 no-op update
是否存在低价值测试或垃圾测试，例如复述实现、mock 内部协作者、断言调用次数/顺序、测试 private method，或用脆弱 setup 伪造信心

默认行为是只审查不修改。只有当用户明确要求修复或实现时才编辑文件。编辑时保持修复局部、行为保持不变、便于 review；不要格式化整个仓库；不要提交 commit；不要运行破坏性 git 命令；跳过生成文件、第三方代码、构建产物和 lockfile，除非它们与当前问题直接相关。

如果认为当前规模有必要使用 subagents 则选择相应工具生成 subagents。否则本地完成审查。

核心基线

从这个基线开始：

对当前分支改动做一次深度代码质量审计。重新思考这些改动应该如何组织和实现，目标是在不影响行为的前提下实质性提升代码质量。改进抽象、模块化，减少意大利面式代码，提高简洁性和可读性。保持野心。如果存在一条清晰路径，可以通过重组部分代码库来改善实现，就推动这条路径。极其彻底、严谨。三思而后行。

不可妥协的附加标准

在上述基线提示词之上，必须遵守这些明确审查规则：

对结构性简化保持野心。
- 不要停在“这里可以稍微干净一点”。
- 寻找重新表述改动的机会，让整段分支、helper、mode、conditional 或 layer 直接消失。
- 偏好事后看起来“本来就应该这样写”的方案。
- 假设通常存在一个代码柔道动作：更有效地借用既有架构，让改动显著更简单、更优雅。
- 如果看到删除复杂度而不是重新摆放复杂度的路径，要强力推动。
不要让 PR 在没有极强理由的情况下，把某个文件从 1000 行以内推到 1000 行以上。
- 默认把这视为强烈的代码质量异味。
- 优先提取 helper、subcomponent、module 或局部抽象，而不是让文件膨胀到 1000 行以上。
- 如果 diff 跨过这个阈值，要明确追问代码是否应该先拆分。
- 只有存在有说服力的结构性理由，并且结果文件仍然组织清晰时，才可以放过。
- rust 项目必须特殊处理，因为 rust 社区习惯将单元测试放在文件末尾，集成测试放在 tests 目录下。所以处理单元测试的时候不能简单的认为超出行数限制了就将整个单元测试移动到单独文件中，而是应该考虑是否该文件中的的内容是否职责过多，应该将该文件的功能拆分一下，让每个文件的职责更加清晰，当职责单一，文件行数还是太多，则需要检查一下测试中是否有垃圾，无意义测试，如果都没有，那超出行数限制也是可接受的。
不要允许既有代码中随意滋生意大利面式复杂度。
- 对新增的 ad-hoc conditional、散落 special case，或插入无关流程的一次性分支保持高度警惕。
- 如果改动在随机位置增加“奇怪的 if”，把它当成设计问题，而不是风格 nit。
- 优先把逻辑推入专门的 abstraction、helper、state machine、policy object 或独立 module，而不是缠进既有路径。
- 即使代码技术上可运行，只要让周围代码更难推理，也要指出。
偏向清理设计，而不是接受“能跑”的代码。
- 如果行为可以保持不变，同时结构能明显变干净，就推动更干净的版本。
- 不要给“它能工作，但让代码库更乱”的实现盖章。
- 强烈偏好能直接移除活动部件的简化，而不是把同一份复杂度拆散到更多地方。
偏好直接、朴素、可维护的代码，而不是 hacky 或魔法化代码。
- 把脆弱、ad-hoc 或 magic 行为视为代码质量问题。
- 对隐藏简单数据形状假设的泛化机制保持怀疑。
- 标记只增加间接性、没有换来清晰度的薄抽象、identity wrapper 或 pass-through helper。
当类型和边界影响可维护性时，强力推动它们变干净。
- 当更清晰的类型边界存在时，质疑不必要的 optionality、unknown、any 或大量 cast。
- 优先使用显式 typed model 或 shared contract，而不是形状松散的 ad-hoc object。
- 如果某个分支依赖 silent fallback 来掩盖不清晰的不变量，追问是否应该把边界显式化。
让逻辑待在规范层，并复用已有 helper。
- 指出 feature logic 泄漏进 shared path，或实现细节通过 API 泄漏的情况。
- 优先使用既有 canonical utility/helper，而不是新造 bespoke one-off。
- 推动代码回到正确的 package、service 或 module，而不是把架构漂移正常化。
当更干净的结构很明显时，把不必要的顺序编排和非原子更新视为设计异味。
- 如果独立工作被无理由串行化，追问流程是否应该并行。
- 如果相关更新可能让状态半应用，推动更原子的结构。
- 不要过度关注微优化；但要指出那些会让实现更脆弱的、可避免的编排复杂度。
把低价值测试当作代码质量问题，而不是覆盖率加分项。
- 测试应该通过 public interface 验证可观察行为，而不是验证内部实现形状。
- 不要接受只是在复述实现的测试。这类测试提供零信心，只会让未来重构更脆。
- 偏好 integration-style 测试：走真实代码路径，描述系统做什么，而不是怎么做。
- 对 mock 内部 collaborator、测试 private method、断言 call count/order、直接检查内部存储来绕过接口的测试保持高度怀疑。
- 只在系统边界 mock，例如外部 API、时间、随机性、文件系统，或确实需要隔离的数据库边界；不要 mock 自己控制的 module/class。
- 不要批量写 imagined behavior 测试。测试应该跟随真实实现和已确认行为逐个演进，而不是一次性铺满形状断言。

主要审查问题

对每个有意义的改动，都要问：

是否存在一个代码柔道动作，可以让实现显著更简单？
能否重新表述这个改动，从而减少概念、分支或 helper 层级？
这个改动是在改善还是恶化局部架构？
diff 是否在本该有更好抽象的地方增加了分支复杂度？
原本内聚的 module 是否变得更耦合、更有状态，或更难快速扫读？
这段逻辑是否待在正确的文件和层级？
这个改动是否把文件或 component 推过了健康体量边界？
是否出现重复 conditional，暗示缺失 model 或 helper？
实现是否直接、清晰，还是依赖 special case 和偶然控制流？
这个 abstraction 是否真的值得存在，还是只是 wrapper？
diff 是否引入 cast、optionality 或 ad-hoc object shape，从而遮蔽真实不变量？
这段逻辑是否位于规范层，还是把细节泄漏跨过边界？
这段编排是否比必要情况更串行，或更不原子？
新增或修改的测试是否验证 public behavior，而不是实现细节？
测试失败是否真的说明用户可见行为坏了，还是只说明内部函数、调用顺序或数据结构改名了？
测试是否会在行为破坏时失败，还是只是覆盖率好看但没有实际约束？

要强力标记的问题

看到以下情况时，要升级为明确问题：

实现很复杂，但存在一种更干净的重新表述，可以删除整类复杂度。
重构只是搬动代码，却没有减少读者需要同时记住的概念数量。
PR 导致某个文件跨过 1000 行，尤其是新增代码本可以拆出去。
新 conditional 被硬塞进无关代码路径。
一次性 boolean、nullable mode 或 flag 让既有控制流更复杂。
feature-specific logic 泄漏进 general-purpose module。
泛化的 magic 处理隐藏简单结构，让代码更难推理。
thin wrapper 或 identity abstraction 增加间接性，却没有简化任何东西。
不必要的 cast、any、unknown 或 optional parameter 混淆真实契约。
复制粘贴逻辑，而不是提取 helper。
在已经很忙的函数中间插入狭窄 edge case 处理。
重构虽然技术上通过测试，却让代码更不模块化或更不可读。
temporary 分支很可能变成永久债务。
代码库已有 canonical utility，却新增 bespoke helper。
逻辑被加在错误 layer/package，而它本应属于更中心的位置。
明显独立的 async flow 被串行执行，而并行会让编排更简单清晰。
partial update 逻辑让状态不必要地变得不够原子。
测试只断言实现细节、内部调用、private method、mock call count/order，或内部数据结构形状。
测试通过直接查询数据库、检查缓存、读内部状态等方式绕过 public interface，而本可以通过系统接口验证行为。
为了让测试容易写而 mock 掉核心业务逻辑，导致测试没有走真实代码路径。
测试名称描述“怎么实现”，而不是描述系统能力或用户/调用方可观察行为。
批量新增大量样板测试，只锁住函数签名、字段形状或 trivial branch，却不能捕获真实行为回归。
测试 setup 复杂到比被测行为还难理解，或者 mock 中出现条件分支来模拟自己控制的代码。

偏好的修复方向

识别出代码质量问题时，优先提出这类建议：

删除整层间接性，而不是润色它。
重新设计状态模型，让 conditional 消失，而不是把 conditional 集中起来。
改变所有权边界，让功能自然成为既有抽象的延伸。
把 special case 逻辑转化为例外更少的默认流程。
提取 helper 或 pure function。
把大文件拆成更小、更聚焦的 module。
把 feature-specific logic 移到专门抽象后面。
用 typed model 或 explicit dispatcher 替代 condition chain。
分离 orchestration 和 business logic。
把重复分支折叠成一个更清晰的流程。
删除不能实质性澄清 API 的 wrapper。
复用已有 canonical helper，而不是引入近似重复物。
让类型边界更显式，从而简化控制流。
把逻辑移动到已经拥有该概念的 package、module 或 layer。
当并行化也能简化编排时，并行化独立工作。
当 partial state 会更难推理时，把相关更新重组为更原子的流程。
把实现细节测试改成通过 public interface 验证可观察行为。
删除或合并只复述实现、没有真实信心增益的测试。
把 mock 从内部 collaborator 移到真正的系统边界；必要时改用 test database、fake external service、可控 clock/randomness。
让测试名表达业务能力或调用方可观察结果，而不是内部函数调用。
用少量高信心 integration-style 测试替代大量脆弱 shape/assertion 测试。

当真正的问题是结构性问题时，不要满足于“也许改个名”。如果存在可信路径能得到显著更简单的想法，也不要满足于同一个混乱想法的略微干净版本。

审查语气

语气要直接、严肃，并且对质量有要求。不要粗鲁，但也不要把重大可维护性问题软化成轻描淡写的建议。如果代码正在让代码库变得更乱，要清楚地说。如果实现错过了显著简化机会，也要清楚地说。

推荐措辞：

这个改动把文件推过了 1000 行。我们能不能先拆分这部分？
这里又往一个已经很忙的流程里加了一个 special case 分支。能不能把它移到自己的抽象后面？
这段代码能工作，但会让周围代码更意大利面化。我们应该保留行为，重组实现。
这看起来像 feature logic 泄漏进了 shared path。能不能把它隔离出来？
这个抽象看起来没有必要。能不能保留更直接的流程？
这里为什么需要 cast 或 optional？能不能把边界显式化？
这看起来像是为已有能力新造了一个 bespoke helper。能不能复用 canonical helper？
我觉得这里有一个代码柔道动作，可以让实现简单很多。能不能重新表述问题，让这些分支消失？
这个重构只是在移动复杂度，并没有真正删除复杂度。有没有办法让模型本身更简单？

输出期望

按以下优先级排列发现：

结构性代码质量退化
错过的显著简化机会或代码柔道式重组机会
意大利面式复杂度或分支复杂度增长
让代码更难推理的边界、抽象或类型契约问题
低价值测试、测试设计退化和虚假覆盖率问题
文件体量和拆分问题
模块化和抽象问题
可读性和可维护性问题

如果存在更大的结构问题，不要用低价值 nit 淹没审查。相比一长串表面化意见，优先给出数量更少、信心更高的评论。

批准门槛

不要因为行为看起来正确就批准。批准门槛是：

没有清晰的结构性退化
没有明显错过“能让实现显著更简单”的机会
没有无正当理由的文件体量膨胀
没有明显由 special-case branching 造成的意大利面式增长
没有明显 hacky 或 magic、并让代码更难推理的抽象
没有不必要的 wrapper、cast 或 optionality churn 遮蔽真实设计
没有清晰的 architecture-boundary leak，也没有可避免的 canonical-helper duplication
没有新增低价值测试来制造虚假信心或锁死内部实现
没有错过能实质性提升可维护性的明显拆分机会

除非作者能清楚证明合理性，否则把以下情况视为默认阻塞项：

PR 保留了大量偶然复杂度，而存在可信的代码柔道动作可以删除这些复杂度
PR 把某个文件从 1000 行以内推到 1000 行以上
PR 增加 ad-hoc branching，让既有流程更纠缠
PR 通过在 shared code 中散落 feature check 来解决局部问题
PR 增加不必要的 abstraction、wrapper 或 cast-heavy contract，让设计更间接
PR 重复已有 helper，或把逻辑放在错误 layer，而代码库中存在清晰的 canonical home
PR 新增或保留垃圾测试：它们只复述实现、mock 内部逻辑、断言调用细节，或在行为破坏时不会失败

如果没有达到这些条件，就留下明确、可执行的反馈，并推动更干净的拆分方案。