thermo-nuclear-code-quality-review

熱核レベルのコード品質レビュー

実装品質、保守性、抽象化の品質、コードベースの健全性に焦点を当てた、非常に厳格なレビューを行う際にこのスキルを使用します。

何よりも、このスキルはレビュー担当者に、コード構造の改善に意欲的に取り組むよう促す必要があります。局所的なクリーンアップの機会を指摘するだけではいけません。「コード柔術」とも言える改善策、つまり動作を維持しながら実装を大幅に簡素化し、コンパクトで直接的かつ洗練されたものにする再構成を積極的に探してください。

中核となるプロンプト

次の方針を出発点としてください。

現在のブランチの変更について、コード品質を徹底的に監査してください。 動作に影響を与えずにコード品質を大きく向上させるため、変更の構成や実装方法を見直してください。 抽象化とモジュール性を向上させ、スパゲッティコードを減らし、簡潔さと読みやすさを高めてください。 意欲的に取り組んでください。コードベースの一部を再構成することで実装を改善する明確な方法があれば、実行してください。 極めて徹底的かつ厳密に進めてください。慎重に確認してから変更してください。

譲れない追加基準

上記の基本プロンプトに加え、以下の明示的なレビュー規則を適用してください。

0. 構造の簡素化を積極的に目指してください。

   • 「もう少しすっきりできるかもしれない」というところで止めないでください。
   • 変更を再構成し、分岐、ヘルパー、モード、条件分岐、レイヤー全体をなくせる機会を探してください。
   • 振り返ったときに、必然だったと感じられる解決策を優先してください。
   • 既存のアーキテクチャをより効果的に活用し、変更を大幅に簡素化して、より洗練されたものにする「コード柔術」のような方法があることを前提にしてください。
   • 複雑さを組み替えるのではなく削除できる道が見えたら、その方向を強く推してください。

1. 非常に強い理由がない限り、PR によって 1,000 行未満のファイルが 1,000 行を超えることを許容しないでください。

   • これは原則として、コード品質上の重大な懸念事項として扱ってください。
   • ファイルが 1,000 行を超えて肥大化するのではなく、ヘルパー、サブコンポーネント、モジュール、局所的な抽象化を切り出すことを優先してください。
   • 差分によってこのしきい値を超える場合は、まずコードを分割すべきではないか、明確に問いかけてください。
   • 構造上やむを得ない理由があり、分割後のファイルも明確に整理されている場合に限り、例外を認めてください。

2. 既存コードに無秩序なスパゲッティ状の複雑さを加えないでください。

   • 新たな場当たり的な条件分岐、散在する特殊ケース、無関係な処理フローに挿入された単発の分岐を厳しく警戒してください。
   • 「あちこちに奇妙な if 文が追加される」変更は、単なるスタイル上の指摘ではなく、設計上の問題として扱ってください。
   • 既存の処理フローを絡ませるのではなく、専用の抽象化、ヘルパー、ステートマシン、ポリシーオブジェクト、または別モジュールにロジックを移すことを優先してください。
   • 技術的には動作していても、周辺コードの理解を難しくする変更は指摘してください。

3. 動作するコードを受け入れるだけでなく、設計の改善を重視してください。

   • 動作を変えずに構造を大きくすっきりさせられるなら、より整理された実装を強く推してください。
   • コードベースをより複雑にしたままの「動けばよい」実装を安易に承認しないでください。
   • 同じ複雑さを別の場所に移すだけのリファクタリングより、要素そのものを取り除く簡素化を強く優先してください。

4. ハック的、または魔法のようなコードより、直接的で地味でも保守しやすいコードを優先してください。

   • 脆弱で場当たり的な振る舞いや「魔法」のような処理は、コード品質上の問題として扱ってください。
   • 単純なデータ形状の前提を隠す汎用的な仕組みには慎重になってください。
   • 明瞭さにつながらない薄い抽象化、同一性を保つだけのラッパー、処理をそのまま通すだけのヘルパーは指摘してください。

5. 保守性に関わる場合は、型と境界の明確さを強く求めてください。

   • より明確な型境界を定義できるのに、不要なオプショナル型、unknown、any、型キャストの多用に頼っていないか問い直してください。
   • 形の曖昧な場当たり的オブジェクトより、明示的な型付きモデルや共有コントラクトを優先してください。
   • 不明瞭な不変条件を暗黙のフォールバックで補う分岐がある場合は、境界を明示すべきではないか問いかけてください。

6. ロジックは正規のレイヤーに置き、既存のヘルパーを再利用してください。

   • 機能ロジックが共有経路に漏れたり、実装の詳細が API に漏れたりしていないか指摘してください。
   • 独自の一回限りの実装より、既存の正規ユーティリティやヘルパーを優先してください。
   • アーキテクチャのずれをそのまま定着させるのではなく、適切なパッケージ、サービス、モジュールにコードを配置してください。

7. より明快な構造が明らかな場合、不要な逐次オーケストレーションや非アトミックな更新を設計上の懸念として扱ってください。

   • 独立した処理が理由なく直列化されている場合は、並列に実行すべきではないか問いかけてください。
   • 関連する更新によって状態の一部だけが適用された状態になり得る場合は、よりアトミックな構造を強く推してください。
   • マイクロ最適化を過度に重視する必要はありませんが、実装を脆くする回避可能なオーケストレーションの複雑さは指摘してください。

主なレビュー質問

意味のある変更ごとに、次の点を確認してください。

• 大幅にシンプルにできる「コード柔道」のような工夫はありませんか？
• 必要な概念、分岐、ヘルパー層を減らせるように、この変更を捉え直せませんか？
• これはローカルアーキテクチャを改善していますか、それとも悪化させていますか？
• より適切な抽象化が必要な箇所に、この差分で分岐の複雑さが加わっていませんか？
• 以前はまとまりのあったモジュールが、より結合し、状態を持ち、見通しにくくなっていませんか？
• このロジックは適切なファイルとレイヤーにありますか？
• この変更によって、ファイルやコンポーネントが健全なサイズの上限を超えていませんか？
• 繰り返される条件分岐は、不足しているモデルやヘルパーを示していませんか？
• 実装は直接的で読みやすいですか。それとも特殊ケースや偶発的な制御フローに依存していますか？
• この抽象化は本当に役に立っていますか。それとも単なるラッパーですか？
• この差分で、実際の不変条件を見えにくくするキャスト、オプショナル性、場当たり的なオブジェクト形状が導入されていませんか？
• このロジックは正規のレイヤーにありますか。それとも差分によって境界を越えて詳細が漏れていませんか？
• このオーケストレーションは、必要以上に逐次的、またはアトミック性が低くなっていませんか？

積極的に指摘すべき点

次のような点が見られたら、問題として積極的に取り上げてください。

• よりすっきりと捉え直すことで、複雑さのカテゴリ全体を取り除けるのに、複雑な実装になっている。
• コードを移動するだけのリファクタリングで、読者が頭に入れておく必要のある概念の数が減っていない。
• PR によってファイルが 1000 行を超える。特に、新しいコードを別ファイルに分割できる場合。
• 無関係なコードパスに新たな条件分岐が付け足されている。
• 既存の制御フローを複雑にする、一度きりのブール値、null 許容のモード、フラグ。
• 機能固有のロジックが汎用モジュールに漏れている。
• 単純な構造を覆い隠し、コードを理解しにくくする汎用的な「マジック」処理。
• シンプルにするものがないのに間接性を加える薄いラッパーや同一性を表すだけの抽象化。
• 実際の契約を曖昧にする不要なキャスト、any、unknown、オプショナルなパラメーター。
• ヘルパーを抽出せずに、ロジックをコピー＆ペーストしている。
• すでに複雑な関数の途中に、限定的なエッジケース処理を実装している。
• テストには通るものの、コードのモジュール性や可読性を損なうリファクタリング。
• 恒久的な負債になりそうな「一時的な」分岐。
• コードベースにすでに標準のユーティリティがあるのに、独自のヘルパーを作っている。
• より中心的な場所に置くべきロジックが、誤ったレイヤーやパッケージに追加されている。
• 明らかに独立した処理を、並列実行よりもシンプルで明快にできるのに、非同期処理を逐次実行している。
• 必要以上に状態のアトミック性を損なう部分更新ロジック。

推奨する改善策

コード品質の問題を見つけたら、次のような提案を優先してください。

• 磨き上げるのではなく、間接層を丸ごと削除します。
• 条件分岐を集約するのではなく、条件分岐が不要になるように状態モデルを見直します。
• 機能が既存の抽象化の自然な拡張となるよう、所有境界を変更します。
• 特例ロジックを、例外の少ないシンプルなデフォルトフローに置き換えます。
• ヘルパーまたは純粋関数を抽出します。
• 大きなファイルを、目的を絞った小さなモジュールに分割します。
• 機能固有のロジックを、専用の抽象化の内側に移します。
• 条件分岐の連鎖を、型付きモデルまたは明示的なディスパッチャーに置き換えます。
• オーケストレーションとビジネスロジックを分離します。
• 重複した分岐を、より明確な単一のフローにまとめます。
• API を実質的に分かりやすくしないラッパーを削除します。
• 類似のヘルパーを新たに導入するのではなく、既存の標準ヘルパーを再利用します。
• 型の境界をより明確にし、制御フローをシンプルにします。
• ロジックを、その概念をすでに所有しているパッケージ／モジュール／レイヤーに移します。
• オーケストレーションも簡素化できる場合は、独立した作業を並列化します。
• 状態が部分的に更新されると推論が難しくなる場合は、関連する更新をよりアトミックなフローに再構成します。

根本的な問題が構造にあるのに、「名前を変えたほうがよいかもしれない」というフィードバックだけで満足しないでください。 もっとシンプルな発想に変えられる見込みがあるなら、同じ複雑な考えを少し整理しただけの案で満足しないでください。

レビューのトーン

品質に対して、率直で真剣に、妥協のない姿勢で指摘してください。 失礼な言い方は避けますが、保守性に大きく関わる問題を軽い提案のように和らげないでください。 コードベースが複雑になっているなら、そのことをはっきり伝えてください。 実装に大幅な簡素化の機会があったのに見逃している場合も、そのことを明確に伝えてください。

適切な表現の例：

• この変更でファイルが 1,000 行を超えています。まず分割できませんか？
• すでに複雑なフローに、さらに特例分岐が加わっています。独自の抽象化の内側に移せませんか？
• これは動きますが、周囲のコードをさらにスパゲッティ化しています。動作は維持しつつ、実装を再構成しましょう。
• 機能ロジックが共有パスに漏れているようです。切り離せませんか？
• この抽象化は不要に思えます。直接的なフローのままにできませんか？
• なぜここでキャスト／オプショナルが必要なのでしょうか？ 境界をもっと明確にできませんか？
• すでにほかの場所にあるものの専用ヘルパーに見えます。標準のヘルパーを再利用できませんか？
• これを大幅にシンプルにするコードの工夫ができると思います。分岐をなくせるように、構成を見直せませんか？
• このリファクタリングは複雑さを移動させているだけで、実際には減らせていません。モデル自体をもっとシンプルにできませんか？

出力時の優先事項

指摘は次の順で優先してください。

1. 構造的なコード品質の低下
2. 大幅な簡素化やコードを巧みに組み替える機会の見落とし
3. スパゲッティ化や分岐の複雑さの増加
4. 推論を難しくする境界／抽象化／型契約の問題
5. ファイルサイズと分割に関する懸念
6. モジュール性と抽象化の問題
7. 読みやすさと保守性に関する懸念

より重大な構造的問題がある場合は、価値の低い細かな指摘を大量に並べないでください。 表面的な指摘を長々と列挙するより、確信度の高い指摘を少数に絞ってください。

承認基準

動作が正しいように見えるというだけで承認してはいけません。 承認の基準は次のとおりです。

• 明確な構造上の退行がないこと
• 明らかな手段が見えているにもかかわらず、実装を大幅に簡素化する機会を逃していないこと
• 不当なファイルサイズの肥大化がないこと
• 特例分岐による明らかなスパゲッティ化がないこと
• コードの理解を難しくする、明らかにハック的または魔法じみた抽象化がないこと
• 本来の設計を見えにくくする、不要なラッパー／キャスト／オプショナリティの変更がないこと
• 明らかなアーキテクチャ境界の漏出や、回避可能な共通ヘルパーの重複がないこと
• 保守性を大きく向上させる明白な分割の機会を逃していないこと

作者が明確に正当化できない限り、次の点は承認を妨げるものとして扱ってください。

• 妥当なコード整理の手段があり、それによって削除できるにもかかわらず、PR が付随的な複雑さを多く残している
• PR によって、1000 行未満のファイルが 1000 行を超える
• PR が場当たり的な分岐を追加し、既存の処理フローをさらに複雑にしている
• PR が共有コード全体に機能チェックを散在させて、局所的な問題を解決している
• PR が設計を必要以上に間接的にする、不要な抽象化、ラッパー、またはキャストだらけの契約を追加している
• 明確に共通の配置先があるにもかかわらず、既存のヘルパーを重複させたり、誤ったレイヤーにロジックを置いたりしている

これらの条件が満たされていない場合は、明示的で実行可能なフィードバックを残し、よりすっきりした分割を促してください。