review-structure

構造・保守性レビュー

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

何よりも、このスキルではコード構造について野心的な姿勢をレビュー担当者に促します。局所的なクリーンアップの機会を見つけるだけにとどまらないでください。動作を維持しながら、実装を大幅にシンプルに、小さく、直接的で、洗練されたものにする再構成、つまり「コード柔術」の手法を積極的に探してください。

構造を見る視点はリポジトリ全体に及びます。既存の標準ヘルパーの有無、ファイルサイズの上限が守られているか、変更によってコードベースの扱いやすさが向上するか低下するかを判断するため、必要に応じてコードベース内のあらゆるファイルを読み、検索してください。

捏造防止（ゲート 0 — 他のすべてのゲートより先に実行）

判定を一切出す前に――指摘、再構成の提案、構造上の主張のいずれであっても――このターンで読んだソースから、評価対象となる正確な成果物を引用して必ず示してください。

• コードに関する指摘の場合：ファイル名:行番号と、今あらためて読み取った該当コード（以前のセッションでの記憶ではなく、今読み取ったもの）。
• 構造上の主張（「標準ヘルパーが存在しない」「ファイルが 1,000 行を超えている」など）の場合：根拠となる検索パターンと検索結果、または wc -l／読み取りに基づく行数。

成果物だけを唯一の根拠としてください。レビュー対象をブランチ名、作業ディレクトリ、周辺ファイル、記憶から推測してはいけません。頭の中の認識と、今あらためて読み取ったソースが異なる場合は、ソースを優先してください。対象を同じターンで示さずに出した判定は無効です。判定の前に引用を示すか、判定を出さないでください。

このゲートは、文脈による先入観を受けた LLM が、ファイルに存在しないコードを自信満々に指摘するのを防ぐためのものです。以下のハードゲートより先に実行してください。

ハードゲート（順番どおりに実行）

各ゲートの合格条件が客観的に満たされた場合にのみ次へ進んでください（「頭の中で確認した」ではなく、成果物のパス、ツール出力、またはラベル付きの記録が必要です）。

ゲート	合格条件
G1 — 変更ファイル一覧	git diff --name-only（または同等のコマンド）が空でない一覧を返すか、「変更ファイルなし」と明示して終了していること。レビューを始める前に一覧を記録すること。
G2 — ファイル全体の読み取り	対象となるすべてのファイルを最後まで読み、各ファイルについてパスと行数を記録していること（例：src/foo.ts — 342 lines）。すべての読み取り記録がそろうまで、指摘に進まないでください。
G3 — 標準ヘルパーと 1,000 行の主張の検証	「標準ヘルパーが存在しない」と主張する指摘には、検索パターンと結果を示すコードベース検索の成果物が必要です。ファイルが 1,000 行を超えると主張する指摘には、wc -l または読み取りに基づく行数の成果物が必要です。これらの成果物がない指摘は、報告に含めることができません。

中核プロンプト

次の基本方針から始めてください。

現在のブランチの変更について、構造を深くレビューしてください。 動作に影響を与えずにコード品質を実質的に向上させるため、変更の構成や実装方法を見直してください。 抽象化とモジュール性を高め、スパゲッティコードを減らし、簡潔さと読みやすさを向上させてください。 野心的に取り組んでください。コードベースの一部を再構成することで実装を明確に改善できるなら、実行してください。 非常に徹底的かつ厳密にレビューしてください。念には念を入れてください。

譲れない追加基準

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

主なレビュー質問

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

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

特に厳しく指摘する点

上記のルール 0〜7 を適用し、特に次の点を重視してください。

• 読者が頭の中で把握しておかなければならない概念の数を減らせていない、コードの配置換えにすぎないリファクタリング。
• ヘルパーを抽出せず、ロジックをコピーして貼り付けている箇所。
• すでに複雑な関数の途中に実装された、限定的なエッジケース処理。
• テストには通るものの、コードのモジュール性や可読性を損なうリファクタリング。
• 恒久的な負債になりそうな「一時的な」分岐。

推奨する改善策

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

• 間接性を磨くのではなく、レイヤー全体を削除する。
• 条件分岐を集約するのではなく、条件分岐が不要になるように状態モデルを捉え直す。
• 機能が既存の抽象化の自然な拡張となるよう、責務の境界を変更する。
• 特殊ケースのロジックを、例外の少ないシンプルなデフォルトフローに置き換える。
• ヘルパーまたは純粋関数を抽出する。
• 大きなファイルを、目的を絞った小さなモジュールに分割する。
• 機能固有のロジックを専用の抽象化の内側に移す。
• 条件分岐の連鎖を、型付きモデルまたは明示的なディスパッチャーに置き換える。
• オーケストレーションとビジネスロジックを分離する。
• 重複した分岐を、より明快な単一のフローにまとめる。
• API を実質的に明確にしないラッパーを削除する。
• 類似したヘルパーを新たに導入せず、既存の正規ヘルパーを再利用する。
• 型の境界をより明確にし、制御フローをシンプルにする。
• その概念をすでに担っているパッケージ、モジュール、レイヤーにロジックを移す。
• オーケストレーションもシンプルになる場合は、独立した処理を並列化する。
• 部分的な状態のほうが把握しにくくなる場合は、関連する更新をよりアトミックなフローに組み直す。

本質的な問題が構造にあるのに、「名前を変えてみてはどうでしょう」といったフィードバックで済ませないでください。 大幅にシンプルな案が考えられるなら、同じ問題のある考え方を単に小ぎれいにしただけの案で満足しないでください。

レビューの姿勢

品質に対して率直で、真剣かつ妥協なく指摘してください。 失礼な言い方は避けつつ、保守性に関わる重大な問題を軽い提案のように和らげないでください。 コードベースをさらに雑然とさせているなら、そのことを明確に伝えてください。 劇的にシンプルにする機会を逃しているなら、そのことも明確に伝えてください。

出力に関する期待事項

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

1. 構造的なコード品質の低下
2. 劇的な簡素化やコード柔術による再構成の機会を逃している点
3. スパゲッティ化や分岐の複雑さの増加
4. 推論を難しくする境界、抽象化、型契約の問題
5. ファイルサイズと分割に関する懸念
6. モジュール性と抽象化の問題
7. 読みやすさと保守性に関する懸念

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

承認基準

動作が正しいように見えるというだけで承認しないでください。基準は、上記のルール 0～7 に違反せず、明らかな構造上の後退がないことです。

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

• 妥当なコード整理によって削除できる付随的な複雑さが、PR に残されている（ルール 0）
• PR により、ファイルの行数が 1000 行未満から 1000 行を超える（ルール 1）
• 既存のフローをさらに複雑にする場当たり的な分岐が PR に追加されている（ルール 2）
• 不要な抽象化、ラッパー、またはキャストの多いコントラクトが PR に追加されている（ルール 4～5）
• 既存のヘルパーが重複している、またはロジックが誤ったレイヤーに配置されている（ルール 6）

これらの条件に該当しない場合は、明示的かつ実行可能なフィードバックを残し、より洗練された分割を促してください。

ステップ 1：変更されたファイルを特定する

レビューの前に、コマンドの出力（または同等のもの）を、変更されたファイルの正式な一覧として取得してください。構造面の観点はあらゆる言語の変更に適用されます。拡張子で絞り込まないでください。

BASE=$(for ref in main origin/main master origin/master; do
         git rev-parse --verify "$ref" >/dev/null 2>&1 && { echo "$ref"; break; }
       done)
if [ -z "$BASE" ]; then
  echo "error: no main/master ref found (checked main, origin/main, master, origin/master)." >&2
  exit 1
fi
MERGE_BASE=$(git merge-base HEAD "$BASE") || {
  echo "error: git merge-base HEAD $BASE failed." >&2
  exit 1
}
git diff --name-only "$MERGE_BASE..HEAD"

一覧が空の場合は、その旨を明記し、構造上の指摘を捏造しないでください。

出力形式

## Review Summary

[1-2 sentence overview of structural findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of the structural problem
   - Why: Why this matters (maintainability, spaghetti growth, missed code-judo move)
   - Fix: Specific recommended restructuring

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

ルール

• 正式なヘルパーが存在しないと主張する前に、リポジトリ全体を読み、検索してください
• すべての指摘に 1、2、3…と順番に番号を付けてください
• 各指摘に FILE:LINE を含めてください
• Issue／Why／Fix を明確に分けてください
• 実際の重大度に分類してください
• 多数の表面的な指摘より、確信度の高い構造上の指摘を少数選んでください
• Verdict では Minor と Informational の項目を無視し、承認を妨げるのは Critical と Major のみです