inspect-structure

inspect-structure — コード品質と構造的負債のインスペクター

ドメイン評価基準

1. 対象範囲と運用上の境界

• 構造的負債と構文・書式の区別: 分析対象をモジュール、クラス、メソッドの各階層における構造的、OOP、および認知的負債に厳密に限定します。空白、セミコロン、スタイルの細かな指摘はすべて、標準のリンターに委ねます。
• アーキテクチャの形式とビジネスロジックの区別: 構造的な凝集度と保守性のみを監査します。信頼できる仕様がない限り、ドメインのビジネスルール、価格設定ロジック、数式は決して評価しません。バグの切り分けは /diagnose に、仕様とのずれは /assay に委ねます。
• 読み取り専用の監査とコード変更の区別: 構造化された検査報告書のみを作成します。ディスク上のファイルの変更、コード差分の生成、自動リファクタリングの適用は禁止します。修正計画は /changeset に委ねます。

2. 構造の検査項目

1. クラスの凝集度とSRP（God Class）

   • 問題の兆候：複数の異なるドメイン上の関心事を集約しているクラス、フィールド数やメソッド数が過剰なクラス、またはメソッドの凝集度が低いクラスです。
   • 対処法：単一の責務に特化したサービス、値オブジェクト、または戦略デリゲートに分解します。
   • マイクロスニペット：

     Smell:  class OrderManager { calculateTax(); sendEmail(); saveToDb(); renderPdf(); }
     Remedy: class OrderService delegates to TaxCalculator, OrderMailer, OrderRepository, PdfRenderer.
     

2. メソッドとフローの複雑さ（長大なメソッド／深いネスト）

   • 問題の兆候：適切に管理できる長さを超えるメソッド、3階層以上の制御フローのネスト、アローアンチパターン、または認知負荷の高さです。
   • 対処法：条件を反転してガード節にし、ネストしたブロックを平坦化し、単一のタスクに特化したヘルパーサブルーチンに分解します。
   • マイクロスニペット：

     Smell:  void process() { if (a) { while (b) { if (c) { try { ... } } } } }
     Remedy: Use guard clauses for early returns; extract loop bodies into private subroutines.
     

3. システム全体にわたる重複（マクロ／マイクロDRY）

   • 問題の兆候：クラス、ファイル、メソッドをまたいで存在する、アルゴリズム処理、複数ステップの検証手順、またはエラー処理パイプラインのコピー＆ペーストです。
   • 対処法：共有ドメインヘルパー、基底抽象化、または再利用可能なミドルウェアに集約します。
   • マイクロスニペット：

     Smell:  ServiceA and ServiceB replicate identical 20-line auth header parsing and claim verification.
     Remedy: Extract to TokenAuthenticator.validateAndExtractClaims().
     

4. 結合度とカプセル化の漏れ

   • 問題の兆候：外部クラスの内部データを操作するメソッド（Feature Envy）、またはゲッターを通じて変更可能な内部コレクションを直接公開するクラスです。
   • 対処法：「Tell, Don't Ask」を適用し、ドメインメソッドの背後に状態変更をカプセル化します。不変のスナップショットまたは防御的コピーを返します。
   • マイクロスニペット：

     Smell:  if (order.getCustomer().getAddress().getCountry().equals("US")) { ... }
     Remedy: if (order.isDomesticDelivery()) { ... }
     

5. ポリモーフィズムと戦略の不足（分散した分岐）

   • 問題の兆候：複数のクラスに散在する、並行したswitch(type)やif (type == A)の連鎖によって、Shotgun Surgeryを引き起こすことです。
   • 対処法：分散した型条件分岐を、ポリモーフィズム、Strategy Pattern、または専用のVisitorディスパッチに置き換えます。
   • マイクロスニペット：

     Smell:  PaymentService, InvoiceService, and EmailService all maintain parallel switch (user.getPlanTier()).
     Remedy: Encapsulate tier-specific behaviors inside PlanTier strategy implementations.
     

6. 堅牢性とリソース管理

   • 問題の兆候：空のcatchブロックによるエラーの握りつぶし、またはクリーンアップ用のフックがない、適切に管理されていないストリーム、データベース接続ハンドル、イベントリスナーです。
   • 対処法：コンテキスト情報を付与して明示的に処理するか、再スローします。リソースのライフサイクルを、決定論的な破棄ブロック（defer、finally、using）内にカプセル化します。
   • マイクロスニペット：

     Smell:  try { connect(); } catch (Exception e) {}
     Remedy: try { connect(); } catch (Exception e) { logger.error("DB connection failed", e); throw new ServiceUnavailableException(e); }
     

標準出力コントラクト

# Structural Inspection Dossier: <Target Scope / Module>

## 1. Executive Summary
- **Target Inspected**: `<file_or_directory_path>`
- **Health Rating**: <CLEAN | MODERATE_DEBT | CRITICAL_DEBT>
- **Primary Bottleneck**: <Single-sentence summary of greatest structural risk>

## 2. Technical Debt Catalog

### [<CRITICAL | MAJOR | MINOR>] <Dimension Name>: `<Target Entity / Symbol>`
- **Location**: [<file>#L<N>-L<M>](file:///path/to/file#L<N>-L<M>)
- **Smell**: <Observable anti-pattern description and maintainability impact>
- **Remedy**: <Exact architectural decomposition or extraction path>

*(Repeat for each distinct structural finding; emit 'No structural code smells observed across rubric dimensions' if clean)*

ルーティング

• 複数ファイルにわたる構造リファクタリング、God Classの分解、または共有抽象化の抽出 →（via /changeset）。
• 実行時の機能バグが疑われる場合やテストが失敗する場合 →（via /diagnose）。

実行プロトコル

フェーズ1：スコープのトリアージとマクロレベルの把握

1. 対象パス（file、directory、またはsubsystem）を取り込みます。
2. シンボルツールとファイルツールを使用して、主要な構造上の基点（クラス、モジュールのエントリーポイント、共有ユーティリティ）を特定します。

フェーズ 2：規模に応じた検査

1. 対象範囲の規模を評価します。
   • ターン内での実行（10 ファイル未満、または単一のまとまりのあるモジュール）：ルーブリックの各評価項目に照らして、コードをターン内で直接監査します。
   • サブエージェントへの分散（複数パッケージにまたがるサブシステム、または広範なリポジトリ）：2～3 個の research サブエージェントを起動します（役割：構造インスペクター（<スライス>））。
2. サブエージェントへのコンテキスト提供に関する契約：
   • 各サブエージェントに、対象スライスの座標、特定した構造上のアンカー、ドメインルーブリックの評価項目、および標準出力契約を提供します。

フェーズ 3：統合とターン停止ゲート（集約）

1. サブエージェントの調査結果を照合し、重複を除いて標準出力契約にまとめます。
2. 確定的な健全性評価を割り当てます。
   • CLEAN：ルーブリックに違反する構造上の欠陥はありません。
   • MODERATE_DEBT：カプセル化の漏れが点在する、条件分岐が散在している、または軽微な重複がある状態です。
   • CRITICAL_DEBT：巨大クラスが広範に存在する、サブシステム間でコピー＆ペーストが行われている、またはリソースリークがシステム全体で発生している状態です。
3. 完了した検査ドシエを会話ストリームに出力し、直ちにターンを停止します。