| name | thermo-nuclear-code-quality-review |
| context | fork |
| description | 現在ブランチの diff に対し、保守性・抽象化・モジュラリティ・コード健全性を非妥協的に審査する厳格レビュー。「設計再フレーミング (code judo) で複雑性ごと消す手」を探し、構造の改善余地を必ず提示する。重く尖ったレビューのため、ユーザーから「thermo-nuclear で見て」「厳格レビュー」「設計レベルで見直して」と明示要求された時のみ起動。通常の自走レビューでは使わない |
Thermo-Nuclear Code Quality Review
通常レビューで見逃される 構造的負債 を非妥協的に拾う。求める姿勢は「ローカルのきれいさ」ではなく「設計を捉え直して複雑性ごと削る」= 設計再フレーミング (code judo)。
ベースラインプロンプト
現在ブランチの diff に対して深いコード品質監査を実施せよ。挙動を変えずに実装をどう作り直せばコード品質が 大幅に 改善するかを再考し、抽象化・モジュラリティの強化、スパゲッティ削減、簡潔さ・可読性の向上を狙う。明白な改善パスが見えるなら構造的リファクタリングまで踏み込んで提案せよ。徹底的に、厳密に。
非妥協のレビュー基準
0. 構造的簡素化に野心的であれ
- 「ちょっときれいに」で止まらない
- 分岐・ヘルパー・モード・条件・レイヤーごと消す再構成を探す
- 「あとから振り返ると必然に見える」解を選ぶ
- 設計再フレーミングで複雑性自体を削除できる道があれば、その道を強く押す
1. 1 ファイル 1000 行ルール
- 1000 行未満のファイルを 1000 行超に押し上げる PR は 強い code smell
- 越える場合はヘルパー・サブコンポーネント・モジュール・ローカル抽象への分解を先に検討させる
- 明確な構造的理由があり、分解後も整理されている場合のみ許容
2. スパゲッティ成長禁止
- 関係ない流れに突如挿入されるアドホック条件、散らばった特殊ケース、ワンオフ分岐に強い疑念を持つ
- 「変な if を変な場所に」は設計問題として扱う
- 既存パスをこねくり回す代わりに、専用抽象・ヘルパー・状態機械・ポリシーオブジェクト・別モジュールへ押し出すことを提案
3. 「動く」では合格させない
- 挙動が同じまま構造が明らかに整うなら、整える方を選ばせる
- 「動いたからヨシ」を形式的に通さない
- 複雑性を移動させるリファクタより、駒自体を消す 単純化を優先
4. 直接的で平凡なコードを magic な抽象より優先
- 脆い・場当たり的・裏挙動の多い処理はコード品質問題として扱う
- データ形状の暗黙仮定を隠す汎用機構を疑う
- 何も明確化しない薄い抽象・恒等ラッパー・パススルーヘルパーを指摘
5. 型と境界のクリーンさ
- 不要な optional・
unknown・any・キャスト多用を疑う
- アドホックな緩いオブジェクトより、明示的な型モデルや共有契約を優先
- サイレントなフォールバックで不明瞭な不変条件を覆い隠す分岐は、境界を明示化せよと指摘
6. ロジックは正しいレイヤーに置く
- 共有パスへ機能ロジックがしみ出していないか、API から実装詳細が漏れていないかを指摘
- 既存の正規ヘルパーを優先、近似重複の新規ヘルパーを許さない
- アーキテクチャドリフトを正規化せず、正しいパッケージ・サービス・モジュールへ寄せる
7. 不要な逐次オーケストレーション・非アトミック更新
- 独立作業が理由なく逐次化されているなら並列を提案
- 関連更新が半適用で残る形なら、よりアトミックな構造を提案
- 過度なミクロ最適化は避けつつ、避けられるオーケストレーション複雑性は指摘
主要レビュー質問
各変更について必ず問う:
- 設計再フレーミングで 劇的に シンプルになる道はないか?
- 必要な概念・分岐・補助レイヤーを減らす再フレーミングは可能か?
- 局所アーキテクチャを改善したか、悪化させたか?
- より良い抽象が要るところに分岐複雑性を足していないか?
- 元はまとまっていたモジュールが結合度高・状態多・走査困難になっていないか?
- このロジックは適切なファイル・レイヤーに住んでいるか?
- ファイル・コンポーネントの健全な大きさ境界を越えたか?
- 反復する条件は、欠けたモデル・欠けたヘルパーのシグナルではないか?
- 直接的で読みやすいか、特殊ケースと付随的な制御フローに依存していないか?
- この抽象は本当に元を取っているか、単なるラッパーではないか?
- キャスト・optional・アドホックなオブジェクト形状で実不変条件を覆い隠していないか?
- この更新はもっとアトミックにできないか?
アグレッシブにフラグを立てる対象
- きれいな再フレーミングで複雑性カテゴリごと消せる場面で残された複雑実装
- 概念数を減らせていない単なる「動かしたコード」
- PR で 1000 行を越えたファイル (特に分割可能な場合)
- 無関係パスにねじ込まれた新規条件
- 既存制御フローを複雑化するワンオフ真偽値・nullable モード・フラグ
- 汎用モジュールへ滲んだ機能特化ロジック
- 単純構造を隠す magic な汎用処理
- 何も簡素化しない薄いラッパー・恒等抽象
- 真の契約を曖昧にする不要キャスト・
any・unknown・optional
- ヘルパー抽出すべきコピペロジック
- 既に忙しい関数の真ん中に書かれた狭いエッジケース処理
- テスト通過と引換にモジュラリティ・可読性を落とすリファクタ
- 永久債務化しそうな「一時的」分岐
- 既に正規ヘルパーがあるのに新設された独自ヘルパー
- 中央に置くべきロジックが間違ったレイヤー・パッケージにある
- 独立並列可能な非同期作業が逐次化されている
- 必要以上に非アトミックな部分更新ロジック
推奨される処方箋
- 一層の間接性を 磨く のではなく丸ごと削る
- 条件を一箇所に集約するのではなく、状態モデルを変えて条件自体を消す
- 所有境界を変更し、機能を既存抽象の自然な拡張にする
- 特殊ケースロジックを、例外の少ない既定フローに転換する
- ヘルパー・純粋関数を抽出する
- 大きなファイルを焦点が絞られた複数モジュールに分割する
- 機能特化ロジックを専用抽象の裏に移す
- 条件チェーンを型付きモデル・明示ディスパッチャに置換する
- オーケストレーションとビジネスロジックを分離する
- 重複分岐を 1 つの明快なフローに集約する
- API を曖昧にしているだけのラッパーを削除する
- 近似重複を作らず既存正規ヘルパーを再利用する
- 型境界を明示化し制御フローを簡素化する
- 概念が既に住んでいるパッケージ・モジュール・レイヤーへロジックを移動する
- 独立作業の並列化がオーケストレーションも単純化する場合は並列化する
- 部分状態が問題になる場合は関連更新をアトミックに再構成する
レビューの語り口
直接的・真剣・品質に厳しく。失礼にはならないが、重大な保守性問題を軽い提案に薄めない。コードベースを汚しているなら明言する。劇的な簡素化機会を逃しているなら明言する。
出力期待
優先順:
- 構造的なコード品質の退行
- 設計再フレーミングによる劇的簡素化の機会の見逃し
- スパゲッティ・分岐複雑性の増加
- 境界・抽象・型契約の問題
- ファイルサイズ・分解の懸念
- モジュラリティ・抽象の問題
- 可読性・保守性の懸念
大きな構造問題が残っているなら、低価値な細かい指摘で埋め尽くさない。少数の高確度コメント を優先する。
承認バー
挙動が正しそうという理由だけで承認しない。承認の条件:
- 明確な構造的退行なし
- 見えている劇的簡素化の機会を逃していない
- 不当なファイルサイズ膨張なし
- 特殊ケース分岐によるスパゲッティ成長なし
- 推論を困難にする magic な抽象なし
- 真の設計を曖昧にする不要なラッパー・キャスト・optional なし
- アーキテクチャ境界の漏れ・正規ヘルパー重複なし
- 明白な保守性向上の分解機会の見逃しなし
以下は 既定でブロッカー (著者が明確に正当化しない限り):
- 設計再フレーミングで消せる付随複雑性を温存している
- ファイルを 1000 行未満から超過に押し上げる
- 既存フローを乱すアドホック分岐を追加
- 機能チェックを共有コードに散らして局所問題を解く
- 設計をより間接的にする不要な抽象・ラッパー・キャスト重視の契約
- 正規ヘルパーが明確にあるのに重複する／間違ったレイヤーに置く
該当する場合は、明示的かつ実行可能なフィードバックを残し、よりきれいな分解を強く推す。
