thermo-nuclear-code-quality-review

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。否则本地完成审查。

核心基线

从这个基线开始：

对当前分支改动做一次深度代码质量审计。 重新思考这些改动应该如何组织和实现，目标是在不影响行为的前提下实质性提升代码质量。 改进抽象、模块化，减少意大利面式代码，提高简洁性和可读性。 保持野心。如果存在一条范围受控、能明确减少概念或状态的清晰路径，就推动它；不要用未经证明的大范围重构扩大当前 PR。 极其彻底、严谨。三思而后行。

不可妥协的附加标准

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

0. 对结构性简化保持野心。

   • 不要停在“这里可以稍微干净一点”。
   • 寻找重新表述改动的机会，让整段分支、helper、mode、conditional 或 layer 直接消失。
   • 偏好事后看起来“本来就应该这样写”的方案。
   • 主动检查是否存在一个代码柔道动作：更有效地借用既有架构，让改动显著更简单；无法证明净收益时，不要假设它存在。
   • 如果看到删除复杂度而不是重新摆放复杂度的路径，要强力推动。
   • 把重组列为阻塞项前，必须说明它会净删除哪些概念、分支或模块依赖，并证明修复范围不会反过来让 PR 膨胀；否则只作为非阻塞探索方向。

1. 把 1000 行视为强制结构审视的警戒线，而不是按数字裁决的死亡线。

   • diff 让文件跨过该线时，必须显式检查职责数量、可分离所有权、读者工作集、分支增长和未来扩张方向。
   • 只有存在可信的提取边界，能让一个模块独立拥有内聚职责，并实质减少概念、分支或跨层泄漏时，体量增长才构成阻塞项。发现中必须说清该边界及其收益。
   • 不要仅凭行数要求拆分。若文件是一套内聚状态机、解析器、协议表或真实集成场景，拆开后反而增加跨文件编排和同时阅读成本，可以保留大文件。
   • 优先遵循项目语言和社区惯例。测试与实现同文件的项目（例如常见 Rust 布局）尤其应先判断职责和测试价值，不要为压行数机械搬运测试。
   • 无法说明拆分如何降低认知负担时，不要把跨线本身报告为问题；改为审查文件内部导航、命名与局部结构是否足够清晰。

2. 不要允许既有代码中随意滋生意大利面式复杂度。

   • 对新增的 ad-hoc conditional、散落 special case，或插入无关流程的一次性分支保持高度警惕。
   • 如果改动在随机位置增加“奇怪的 if”，把它当成设计问题，而不是风格 nit。
   • 优先把逻辑推入专门的 abstraction、helper、state machine、policy object 或独立 module，而不是缠进既有路径。
   • 即使代码技术上可运行，只要让周围代码更难推理，也要指出。

3. 偏向清理设计，而不是接受“能跑”的代码。

   • 如果行为可以保持不变，同时结构能明显变干净，就推动更干净的版本。
   • 不要给“它能工作，但让代码库更乱”的实现盖章。
   • 强烈偏好能直接移除活动部件的简化，而不是把同一份复杂度拆散到更多地方。

4. 偏好直接、朴素、可维护的代码，而不是 hacky 或魔法化代码。

   • 把脆弱、ad-hoc 或 magic 行为视为代码质量问题。
   • 对隐藏简单数据形状假设的泛化机制保持怀疑。
   • 标记只增加间接性、没有换来清晰度的薄抽象、identity wrapper 或 pass-through helper。

5. 当类型和边界影响可维护性时，强力推动它们变干净。

   • 当更清晰的类型边界存在时，质疑不必要的 optionality、unknown、any 或大量 cast。
   • 优先使用显式 typed model 或 shared contract，而不是形状松散的 ad-hoc object。
   • 如果某个分支依赖 silent fallback 来掩盖不清晰的不变量，追问是否应该把边界显式化。

6. 让逻辑待在规范层，并复用已有 helper。

   • 指出 feature logic 泄漏进 shared path，或实现细节通过 API 泄漏的情况。
   • 优先使用既有 canonical utility/helper，而不是新造 bespoke one-off。
   • 推动代码回到正确的 package、service 或 module，而不是把架构漂移正常化。

7. 当更干净的结构很明显时，把不必要的顺序编排和非原子更新视为设计异味。

   • 如果独立工作被无理由串行化，追问流程是否应该并行。
   • 如果相关更新可能让状态半应用，推动更原子的结构。
   • 不要过度关注微优化；但要指出那些会让实现更脆弱的、可避免的编排复杂度。

8. 把低价值测试当作代码质量问题，而不是覆盖率加分项。

   • 测试应该通过 public interface 验证可观察行为，而不是验证内部实现形状。
   • 不要接受只是在复述实现的测试。这类测试提供零信心，只会让未来重构更脆。
   • 偏好 integration-style 测试：走真实代码路径，描述系统做什么，而不是怎么做。
   • 对 mock 内部 collaborator、测试 private method、断言 call count/order、直接检查内部存储来绕过接口的测试保持高度怀疑。
   • 只在系统边界 mock，例如外部 API、时间、随机性、文件系统，或确实需要隔离的数据库边界；不要 mock 自己控制的 module/class。
   • 不要批量写 imagined behavior 测试。测试应该跟随真实实现和已确认行为逐个演进，而不是一次性铺满形状断言。

9. 让每份复杂度由真实场景买单。

   • 把每个新增概念、分支、恢复行为和测试追溯到受支持场景、明确契约或必须维护的系统不变量。
   • 不要为了违反明确契约的调用或无法通过系统入口产生的组合扩张实现。若该问题揭示边界设计不佳，优先让非法状态不可表达。
   • 连续审查若总在同一设计边界发现同类问题，或每次修复都继续增加概念、分支和成组测试，把它视为基础模型可能有误的信号，停止局部补丁并重新表述问题。
   • 审查结束前做减法审计：删除没有真实场景的防御逻辑，合并重复表达同一行为的测试，并区分“更完整”与“更正确、更简单”。

主要审查问题

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

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

要强力标记的问题

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

• 实现很复杂，但存在一种更干净的重新表述，可以删除整类复杂度。
• 重构只是搬动代码，却没有减少读者需要同时记住的概念数量。
• 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？
• 我觉得这里有一个代码柔道动作，可以让实现简单很多。能不能重新表述问题，让这些分支消失？
• 这个重构只是在移动复杂度，并没有真正删除复杂度。有没有办法让模型本身更简单？

输出期望

按以下优先级排列发现：

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

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

批准门槛

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

• 没有清晰的结构性退化
• 没有明显错过“能让实现显著更简单”的机会
• 跨过体量警戒线的文件仍然职责内聚，或已沿能降低认知负担的真实边界拆分
• 没有明显由 special-case branching 造成的意大利面式增长
• 没有明显 hacky 或 magic、并让代码更难推理的抽象
• 没有不必要的 wrapper、cast 或 optionality churn 遮蔽真实设计
• 没有清晰的 architecture-boundary leak，也没有可避免的 canonical-helper duplication
• 没有新增低价值测试来制造虚假信心或锁死内部实现
• 没有错过能实质性提升可维护性的明显拆分机会
• 每个新增状态轴、恢复路径和测试族都能追溯到真实场景或明确系统不变量
• 没有因为连续 review 而保留可由更干净契约消除的防御性复杂度

把以下情况视为默认阻塞项：

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

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