reviewing-code-modularity-skill

コードのモジュール性をレビューする

目標

アーキテクチャの形だけをまねることなく、コードの複雑さを減らします。

モジュールの責務範囲、公開範囲、情報隠蔽、依存関係の方向性、テスト可能な境界を改善します。公開範囲が小さく安定しており、依存関係の方向性が明確な、深いモジュールを優先します。コードの理解、変更、テストを容易にするために必要な最小限の再構成にとどめ、それ以上は行いません。

絶対に守ること

これらはどのモードでも適用されます。このスキルの要点であり、決して薄めてはいけません。

1. 構造を提案する前に、実際のコードと周辺の規約を確認します。コードを見ずに行う助言は、たいてい誤りです。
2. 行数を基準にファイルを分割しません。責務を基準に分割するか、分割しないかのどちらかです。
3. このコードベースで現在の複雑さを解決できる場合を除き、クリーンアーキテクチャ、DDD、ヘキサゴナルアーキテクチャ、SOLID を過度に重視したレイヤー構造、リポジトリ、ファクトリー、アダプター、依存性注入、ポート、インターフェースを作りません。
4. 現実的なテスト境界や結合の問題がない限り、実装が1つしかないものにインターフェース、ファクトリー、DIを導入しません。
5. 別々に進化する可能性のある概念は、重複しているように見えても統合しません。誤った抽象化をするくらいなら、重複を残すほうがよい場合がよくあります。
6. 局所的な再構成で問題が解決する場合に、広範な書き換えを提案しません。
7. ユーザーが明示的に動作の変更を求めない限り、動作を維持します。
8. 要求されない限り、アーキテクチャやレポートの成果物を作成したり、ADRを書き換えたりしません。許可されたコード変更が既存のAPIや使用方法のドキュメントに影響する場合は、その内容を正確に保ちます。

中核となる用語

用語が重要となる場合やレポートを作成する場合は、一貫した観点を用います。モジュール、公開範囲、実装、責務、深さ、浅いモジュール、境界、漏洩、局所性、変更の増幅、アーキテクチャの形だけをまねること、推奨の強さです。定義は references/language.md を参照してください。概念に対応する用語がリポジトリ内で使われている場合は、そちらを優先します。

対象範囲の確認

1. 適用されるプロジェクトの指示に従います。コード、周辺の規約、公開エクスポート、関連するテストを確認します。推奨内容が広範に及ぶ場合や境界を移動する場合は、アーキテクチャ上の決定を確認してください。references/decision-records.md を参照してください。
2. PRや差分をレビューする場合は、指定された比較対象またはベースとヘッドを確認し、実際の差分を読みます。その範囲が依頼された変更を表していることを検証します。差分が空、または取得できない場合は、問題がないことを意味するのではなく、確認範囲の制約です。新たに発生または悪化した問題と、既存の負債を区別します。領域を調査する場合は、確認した領域と重要な確認漏れを明らかにします。
3. 境界に関する懸念を確認するため、関連する呼び出し元と依存関係をたどります。そのモジュールが何を担い、何を隠しているのか、呼び出し元が知る必要のある決定事項は何か、テストに何が必要かを確認します。リポジトリ全体の把握を最初から目的とするのではなく、明示された不確実性を解消するために調査範囲を広げます。
4. ユーザーが編集を依頼しない限り、レビューと設計の作業は読み取り専用で行います。レポートファイルは依頼された場合にのみ作成します。HTMLは、HTMLまたはビジュアルレポートが明示的に依頼された場合にのみ作成します。対象範囲が広いことだけを理由に、成果物を作成してよいわけではありません。

証拠に基づいて指摘する

コードの臭いは結論ではなく、手がかりとして扱ってください。指摘を報告する前に、次の点を確認します。

• 影響を受ける操作、現在の保守上の問題、または具体的に予定されている変更を特定します。コストの原因となっている依存関係や知識の重複をたどり、調査したコードと関連する呼び出し元を示します。
• 最も妥当な反対説明を確認します。たとえば、互換性の契約、意図的な重複、フレームワークの慣例、文書化された判断などです。ラッパーがビジネスロジックを追加しなくても、実際の境界を保護している場合があります。
• 有用な最小限の介入と、コードを変更しない場合を比較します。間接化、移行、テストのコストも含めます。ファイル数やエクスポート数が少ないというだけでは、改善の根拠になりません。
• 影響（結果）、証拠（実証済み | 裏付けあり | 未解決）、範囲（今回導入・悪化 | 既存）を分けます。証拠の欠落は未解決であり、反証ではありません。未解決の手がかりは実行可能な指摘に含めず、必要に応じて重要なカバレッジの不足を記載します。

見た目の好みや仮定上の成長を欠陥として報告しないでください。実行可能な指摘がゼロでも、レビューとして成功です。これらは推論の確認事項であり、必須の報告テンプレートではありません。判断に役立つ場合に限り、references/red-flags.md または references/principles.md の関連セクションを読み込んでください。

モードの選択

モード	使用する場面	出力
A — 高速レビュー	ファイル、差分、PR、モジュール、ルート、コンポーネント、小規模な範囲をレビューする場合。	リスク順の指摘。候補カードはなし。
B — 摩擦スキャン	コードベースや範囲をスキャンしてリファクタリング候補を探す、構造を改善する、境界を見つける、または最優先の提案を求める場合。	裏付けのある候補を最大4件、または変更を推奨しない旨。
C — 候補の深掘り	候補が選ばれた場合、またはユーザーが公開サーフェス／インターフェースの設計を求めた場合。	所有・隠蔽・サーフェス＋設計の比較。
D — 実装	ユーザーが実際のリファクタリングをエージェントに依頼した場合。	振る舞いを維持する最小限の変更＋検証。

要件を満たす最小のモードを選択してください。ユーザーがその作業を依頼した場合は、B → C → D と進めます。範囲が広いだけでは、実装を行う根拠にはなりません。直接リファクタリングを依頼された場合は、報告や設計の段階を挟まずにDへ進んでもかまいません。

モードA：高速なモジュール性レビュー

証拠を確認し、実行可能な指摘を影響の大きい順に報告します。各指摘では、次の点を示します。

• 影響 — 実証された大幅な変更波及、または裏付けのある正確性リスクは高、具体的かつ反復的な保守・テスト負担は中、実際にあるものの局所的で低コストの問題は低とします。結果を説明してください。パターン名だけで深刻度が決まるわけではありません。
• 証拠と箇所 — 調査したコードのファイル／行、または正確なシンボルを示し、実証された振る舞いと推論を区別します。PRによって問題が導入・悪化したかどうかを記載し、既存の負債とは分けてください。
• 複雑さが増す理由 — 影響を受ける操作とその仕組みを明示します。
• 有用な最小限の修正 — 振る舞いを維持する修正を示します。
• 変更しないもの — 過剰なリファクタリングを避ける必要が実際にある場合に限り記載します。

該当する指摘がない場合は、カバレッジについて簡潔に触れてその旨を伝えます。依頼がない限り、候補カードは使いません。簡潔な指摘を重視してください。

モードB：アーキテクチャの摩擦スキャン

対象範囲を調査して摩擦を探し、references/review-report.md を使って候補レポートを作成します。

• 最初に、構造を変更しないことも含めた単一の最優先提案を示します。
• 証拠の確認事項を満たす候補を0～4件提示します。各候補には、現在の摩擦と箇所、影響・証拠・範囲、有用な最小限の修正とそのコスト、参考となる変更前／変更後の図示、テストへの影響、変更しないもの、推奨の強さを含めます。件数を埋める必要はありません。未解決の手がかりを候補として提示しないでください。

特に指定がなければ、会話内にMarkdownで返します。追加の設計や実装が依頼されている場合は、その範囲内で続行します。それ以外の場合はレビューを終了します。実質的に異なる選択肢についてユーザーの判断が必要な場合に限り、選択を尋ねてください。

モード C：候補の設計を深める

ユーザーが候補を選択した場合、または公開インターフェースの設計を依頼した場合に使用します。次の項目を提示してください。

1. モジュールが所有するもの。
2. モジュールが隠すもの。
3. 公開インターフェース。
4. 呼び出し元のコード例 — 最小限の現実的な呼び出し箇所。
5. 変更せずに維持すべきテスト（動作契約）。
6. リファクタリングしないもの。
7. 実質的に異なる設計案を2～4個。ただし、判断が重要な場合に限ります。
8. 推奨案を1つ。その理由と、重要な不確実性があればそれも示します。現在の境界を維持する案が最適な場合もあります。

重要な比較を行う場合は、references/interface-design.md を読み込んでください。明白な設計案が1つだけなら、それで十分です。コストのかかる境界の判断では、任意の変更影響分析によって、実際に予定されている要件を現在の構成と提案する構成で比較できます。リファクタリングを正当化するために、推測上の要件を作り出さないでください。

モード D：動作を維持した実装

実際のリファクタリングを依頼された場合に使用します。編集する前に、次のことを行ってください。

• 呼び出し元とテストから、影響を受ける動作契約を特定します。出力、エラー、公開シグネチャ、および関連する副作用、順序、トランザクション、初期化を確認します。
• 既存の対象チェックを実行してベースラインを確立し、既存の失敗を記録します。移動によって影響を受ける重要な動作がカバーされていない場合は、既存の契約から期待値を導き、小規模な特性テストを追加します。既知のバグを意図した動作として固定しないでください。
• チェックを実行できない場合は制約を明示し、検証済みの等価性を主張せずに、利用可能な根拠を用います。

そのうえで、次のことを行ってください。

• 選択した設計を実現するために、動作を維持する最小限の変更を行います。
• ユーザーが明示的に依頼した契約変更を除き、公開 API と呼び出し元から見えるセマンティクスを維持します。そのような変更がある場合は、影響を受ける呼び出し元、テスト、使用方法のドキュメントを更新します。新しいレイヤーに役割を与えるために、認証、監査、再試行、バリデーション、エラー動作を作り出さないでください。依頼された動作変更は構造上の移動と分けてください。
• インポートを慎重に更新します。呼び出し元を確認せずにコードを移動しないでください。
• 関係のないクリーンアップを変更に含めないでください。
• 候補の「変更しないもの」というガードレールを引き継ぎます。
• その後、検証します。

最後に、何を変更したか、構造がなぜ改善されたか、どのチェックを実行したか、残るリスクを説明してください。小規模な変更では、これらを短い段落にまとめてください。

検証

編集後、次のことを行ってください。

1. ベースラインのチェックと、影響を受ける動作テストを再実行します。境界を変更した場合は、呼び出し元のテストも含めます。
2. プロジェクトに関連する型チェック、リンター、インポート／依存関係の境界チェックを使用します。具体的な残存リスクへの対応、またはプロジェクトで必須のゲートがある場合に検証範囲を広げます。別のコマンドが存在するというだけの理由で範囲を広げないでください。
3. 最終差分を確認し、無関係なリファクタリングが入り込んでいないことを確かめます。
4. 検証を実行できない場合は、その旨を明確に伝えます。

参照資料の読み込み

段階的に読み込んでください。以下のパスは、レビュー対象のプロジェクトではなく、このスキルのディレクトリを基準に解決します。適切なセクションが不明な場合は、rg '^## ' <skill-directory>/references/*.md（または同等のファイル読み取り方法）で参照資料の見出しを一覧表示してから、関連するセクションを読みます。参照資料の内容を適用し、繰り返し説明しないでください。評価用のフィクスチャやルーブリックは開発資料であり、実行時の参照資料ではありません。

• references/principles.md — 設計上のトレードオフ：深いモジュール、情報隠蔽、依存関係の方向、抽象化の規律、ファイル分割。
• references/red-flags.md — 問題の兆候。該当する番号付きの項目だけを読みます。
• references/examples.md — 近くに参考となるプロジェクトのパターンがない場合の、具体的な再構成例。
• references/language.md — 用語が重要な場合、またはレポートを作成する場合に使用する共通用語。
• references/review-report.md — 候補レポートの形式（モード B）。依頼がない限り、モード A の迅速なレビューには使用しません。
• references/interface-design.md — 選択した候補の設計検討（モード C）。
• references/decision-records.md — 広範な推奨を行う前の、プロジェクトのコンテキストと ADR の扱い。