ln-624-code-maintainability-hotspot-auditor

パス: ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

コード保守性ホットスポット監査ツール（L3 ワーカー）

タイプ： L3 ワーカー

読みづらく、変更しにくく、理解しにくいローカルコードのホットスポットを監査する専門ワーカーです。

目的と範囲

• コード保守性のホットスポットを監査します（優先度：中）
• 複雑度メトリクス、メソッドシグネチャの品質、ローカルなアルゴリズム効率、定数の管理、レイヤー間の識別子の一貫性を確認します
• REFACTOR_HOTSPOT、SIMPLIFY_SIGNATURE、EXTRACT_CONSTANT、または UNIFY_IDENTIFIER を出力します
• 重大度、場所、工数、推奨事項を含む構造化された検出結果を返します
• コード品質カテゴリの準拠スコア（X/10）を算出します

入力

必須の読み込み： references/audit_worker_core_contract.md と references/mcp_tool_preferences.md を読み込みます。 ツールポリシー：ホストの AGENTS.md が対象範囲外となる独立したサブエージェントとして実行される場合があるため、ファイルの読み取り、検索、編集にはまず hex-line MCP を使用してください。MCP の動作が不明確な場合に限り、references/mcp_integration_patterns.md を読み込みます。

tech_stack、best_practices、principles、codebase_root、output_dir を含む contextStore を受け取ります。

ドメイン対応： domain_mode と current_domain をサポートします（audit_output_schema.md#domain-aware-worker-output を参照）。

ワークフロー

検出ポリシー：2 層検出（候補のスキャン、その後のコンテキスト検証）を使用します。検証方法が曖昧な場合に限り、references/two_layer_detection.md を読み込みます。

1. コンテキストを解析 -- フィールドを抽出し、scan_path を決定し（指定されていればドメイン対応）、output_dir を抽出します
2. 違反がないかコードベースをスキャン（レイヤー 1）
   • すべての Grep/Glob パターンで codebase_root ではなく scan_path を使用します
   • グラフによる高速化（利用可能な場合）： contextStore.graph_indexed または .hex-skills/codegraph/index.db が存在する場合：
     • 複雑度と God クラス： audit_workspace(path=scan_path, verbosity="minimal", limit=5) を実行し、返されたホットスポットを使って複雑な関数と God クラスを事前に特定します。意図的に詳細調査する場合に限り、limit を増やします。
     • モジュールメトリクス： analyze_architecture(path=scan_path, verbosity="full") を実行し、返された結合メトリクスをカスケードの深さと結合の分析に使用します。
     • グラフが利用できない場合は、以下の grep パターンに切り替えます。
     • アウトラインを先に読む： 大きなソースファイルを読む前に outline(file_path) を使用し、複雑度分析のために関数／クラスの構造を把握します。
   • 例：ネストを検出するには Grep(pattern="if.*if.*if", path=scan_path) を使用します
3. 候補ごとにコンテキストを分析（レイヤー 2 -- 必須） レイヤー 2 の確認がないレイヤー 1 の検出結果は、有効な検出結果ではありません。報告する前に、「この違反は意図的なものか、設計上の妥当な理由があるか」を確認します。
   • 循環的複雑度：複雑さの原因は enum に対する switch/case（妥当）か、深くネストした条件（問題あり）か。enum のディスパッチなら重大度を「低」に下げるか、対象から除外します
   • O(n^2)：コンテキストを読み、n が何かを確認します。n に上限がある場合（n < 100）、重大度を下げます
   • God クラス：config/schema/builder クラスかどうかを確認し、該当する場合は重大度を下げます
   • 識別子の不一致：名前の変更が明示的なシリアライザーエイリアス（@JsonProperty、alias_generator、@SerializedName）または ORM のカラムマッピング（@Column(name=...)）によって処理されているかを確認します。該当する場合は重大度を下げるか、対象から除外します
4. 重大度、場所、工数、推奨事項を含む検出結果を収集
   • ドメイン対応の場合、各検出結果に domain: domain_name のタグを付けます
5. ペナルティアルゴリズムを使用してスコアを算出
6. レポートを作成： references/templates/audit_worker_report_template.md に従って完全な Markdown レポートをメモリ上で作成し、1 回の Write 呼び出しで {output_dir}/ln-624--{domain}.md（グローバルモードでは 624-quality.md）に書き込みます
7. 概要を返す： 最小限の概要を返します（出力形式を参照）

監査ルール（優先度：中）

1. 循環的複雑度

概要： 単一の関数に判定箇所が多すぎます（> 10）

検出方法：

• if/else、switch/case、三項演算子、&&、||、for、while の数を数えます
• 次のツールを使用します：eslint-plugin-complexity、radon（Python）、gocyclo（Go）

重大度：

• HIGH： 複雑度 > 20（テストが非常に困難です）
• MEDIUM： 複雑度 11-20（リファクタリングを推奨します）
• LOW： 複雑度 8-10（許容範囲ですが、監視してください）
• 引き下げる場合： Enum/switch によるディスパッチ、ステートマシン、パーサー文法の場合は、LOW に引き下げるか、対象外にします

推奨事項： 関数を分割し、ヘルパーメソッドを抽出し、早期リターンを使用します

作業量： M-L（複雑度によります）

2. 深いネスト（> 4 階層）

概要： if/for/while ブロックのネストが深すぎます

検出方法：

• インデントの階層数を数えます
• パターン：if { if { if { if { if { ... } } } } }

重大度：

• HIGH： > 6 階層（判読困難です）
• MEDIUM： 5-6 階層
• LOW： 4 階層
• 引き下げる場合： 早期リターンのガード節によるネスト（構造上は深くても、ロジックは直線的）の場合は、重大度を引き下げます

推奨事項： 関数を抽出し、ガード節を使用し、条件を反転します

作業量： M（構造のリファクタリング）

3. 長いメソッド（> 50 行）

概要： 関数が長すぎる、または処理が多すぎます

検出方法：

• 関数の開始から終了までの行数を数えます
• コメントと空行は除外します

重大度：

• HIGH： > 100 行
• MEDIUM： 51-100 行
• LOW： 40-50 行（境界域）
• 引き下げる場合： 順次処理を委譲するオーケストレーター関数、データ変換パイプラインの場合は、重大度を引き下げます

推奨事項： 小さな関数に分割し、単一責任の原則を適用します

作業量： M（ロジックの抽出）

4. ゴッドクラス／モジュール（> 500 行）

概要： 責務が多すぎるファイルです

検出方法：

• ファイルの行数を数えます（コメントは除外）
• public メソッド／関数の数を確認します

重大度：

• HIGH： > 1000 行
• MEDIUM： 501-1000 行
• LOW： 400-500 行
• 引き下げる場合： 設定／スキーマ／マイグレーションファイル、生成コード、バレル／index ファイルの場合は、対象外にします

推奨事項： 複数のファイルに分割し、関心の分離を適用します

作業量： L（大規模なリファクタリング）

5. パラメーターが多すぎる（> 5）

概要： 関数のパラメーターが多すぎます

検出方法：

• 関数のパラメーター数を数えます
• コンストラクターとメソッドを確認します

重大度：

• MEDIUM： 6-8 個のパラメーター
• LOW： 5 個のパラメーター（境界域）
• 引き下げる場合： ビルダー／オプションパターンのコンストラクター、フレームワークで必要なシグネチャ（ミドルウェア、フック）の場合は、対象外にします

推奨事項： パラメーターオブジェクト、ビルダーパターン、デフォルトパラメーターを使用します

作業量： S-M（シグネチャと呼び出し箇所のリファクタリング）

6. O(n^2) 以上のアルゴリズム

概要： コレクションに対するネストしたループが非効率です

検出方法：

• ネストした for ループ：for (i) { for (j) { ... } }
• ネストした配列メソッド：arr.map(x => arr.filter(...))

重大度：

• HIGH： ホットパス（API リクエストハンドラー）での O(n^2)
• MEDIUM： たまにしか実行されない処理での O(n^2)
• LOW： 小規模なデータセット（n < 100）での O(n^2)
• 引き下げる場合： n の上限が保証されている（ドメイン上 n < 100 が保証されている）場合、または一度だけ実行する初期化／マイグレーションコードの場合は、LOW に引き下げるか、対象外にします

推奨事項： ハッシュマップを使用し、1 回の走査で最適化し、より適切なデータ構造を使用します

作業量： M（アルゴリズムの再設計）

7. 定数の管理

内容： マジックナンバー／文字列、分散した定数、重複

検出方法：

問題	パターン	例
マジックナンバー	条件式／計算式にハードコードされた数値	if (status === 2)
マジック文字列	比較にハードコードされた文字列	if (role === 'admin')
分散	ファイル間に散在する定数	5つのファイルに MAX_SIZE = 100
重複	同じ値が複数回登場	3か所に STATUS_ACTIVE = 1
中央ファイルがない	constants.ts または config.py がない	信頼できる唯一の情報源がない

重大度：

• HIGH： ビジネスロジック内のマジックナンバー（支払額、ステータス）
• MEDIUM： 定数の重複（同じ値が3回以上定義されている）
• MEDIUM： 定数をまとめた中央ファイルがない
• LOW： ロギング／デバッグで使われるマジック文字列
• 重大度を下げる条件： HTTP ステータスコード（200、404、500）→対象外。アルゴリズム内の数学定数（0、1、-1）→対象外。テストデータ→対象外

推奨事項：

• 定数をまとめたファイル（constants.ts、config.py、constants.go）を作成する
• マジックナンバーを名前付き定数に置き換える：const STATUS_ACTIVE = 1
• 重複を統合し、中央ファイルからインポートする
• 関連する定数には列挙型を使用する

工数： M（定数の抽出、インポートの更新、統合）

8. メソッドシグネチャの品質

内容： 可読性と保守性を低下させる、適切でないメソッドの契約

検出方法：

問題	パターン	例
真偽値フラグの引数	シグネチャに真偽値の引数が2つ以上ある	def process(data, is_async: bool, skip_validation: bool)
オプション引数が多すぎる	デフォルト値を持つオプション引数が3つ以上ある	def query(db, limit=10, offset=0, sort="id", order="asc")
動詞の命名に一貫性がない	同じ種類の操作に対し、モジュール内で異なる動詞が使われている	get_user() と fetch_account() と load_profile()
戻り値の型が不明瞭	TypedDict／NamedTuple を使わずに -> dict、-> Any、-> tuple としている	-> StatsResponse ではなく def get_stats() -> dict

重大度：

• MEDIUM： 真偽値フラグの引数（列挙型／ストラテジーを使用）、戻り値の型が不明瞭
• LOW： オプション引数が多すぎる、命名に一貫性がない

推奨事項：

• 真偽値フラグ：列挙型、ストラテジーパターン、または個別のメソッドに置き換える
• オプション引数：設定／オプション用のデータクラスにまとめる
• 命名：モジュールごとに動詞の規則を統一する（同期処理には get_、非同期処理には fetch_ など）
• 戻り値の型：生の dict／tuple ではなく、TypedDict、NamedTuple、またはデータクラスを使用する

工数： S-M（シグネチャと呼び出し元のリファクタリング）

9. レイヤー間の識別子の一貫性

内容： 同じ概念に対して、API コントラクト、DTO、サービス、リポジトリ、DB カラム、内部モジュールで異なる識別子が使われています。

検出方法：

問題	パターン	例
外部コントラクトの不一致	API/OpenAPI/外部スキーマのフィールド名が、DTO/サービス/リポジトリ/DB カラムと異なる	OpenAPI では user_id だが、DTO では uid、サービスでは userId、DB では user カラム
同義語の不一致（内部）	同じエンティティがモジュール間で異なる名前で参照されている	1 つの概念に対して customer、client、account、user が使われている
明示的な変換なしの大文字・小文字や表記の変換	明示的なシリアライザーのエイリアスなしに snake/camel/kebab が切り替わっている	API フィールドの created_at が、エイリアスを宣言せずに creationTime に割り当てられている
略語の不一致	1 つの概念に対して完全形と略語が混在している	organization、org、orgId、organizationId が混在している

重要度：

• HIGH： 外部コントラクトのフィールド名が、明示的なシリアライザーのエイリアスなしにコード内で変更されている場合。上流のコントラクトが変更された際に、気づかないまま破損するリスクがあります
• MEDIUM： 1 つのエンティティに対する同義語の不一致が 3 つ以上のモジュールにまたがっている場合（customer / client / account）
• MEDIUM： 明示的なエイリアスマッピングなしに大文字・小文字の変換が行われている場合
• LOW： 1 つの境界づけられたモジュール内で 2 種類の表記が使われている場合。内部コードのみで略語の不一致がある場合
• 重要度を下げる条件： ORM を介した明示的なカラムエイリアスによるマッピング、フレームワークで必須の変換（例：コード生成による GraphQL の camelCase）、コントラクトから生成された DTO、名前の変更を余儀なくする言語キーワードとの衝突がある場合は、重要度を下げるかスキップしてください

レイヤー 2 の要件： 同義語の不一致を検出するには、プロジェクトで管理している用語集、または使用文脈の確認が必要です。Grep だけでは不十分です。報告する前に、2 つの識別子が同じ概念を指していることを必ず確認してください。

推奨事項：

• 外部コントラクトの場合： DTO / サービス / リポジトリ / DB カラムでも外部 API 名をそのまま使用してください。大文字・小文字や言語の慣習と競合する場合は、コード内でフィールド名を変更するのではなく、境界でシリアライザーのエイリアス（@JsonProperty、alias_generator、@SerializedName）を一度設定してください
• 内部のみの場合： 意味が最も正確な表記を選び、モジュール全体で検索・置換してください。共有用語集または共有の定数／列挙型モジュールに標準用語を記録してください。可能であれば、再発を防ぐために lint ルールまたはコード生成ステップを追加してください
• 単一モジュール内での動詞の命名については、ルール #8（メソッドシグネチャの品質）を参照してください

工数： S-M（名前の変更とシリアライザーの設定）。DB カラムの変更とマイグレーションが必要な場合は L

スコアリングアルゴリズム

必ず読むこと： references/audit_scoring.md を読み込んでください。

出力形式

必ず読むこと： references/templates/audit_worker_report_template.md を読み込んでください。

references/audit_summary_contract.md に従って JSON サマリーを作成してください。管理モードでは、呼び出し元が runId と summaryArtifactPath の両方を渡します。スタンドアロンモードでは、ワーカーは共有コントラクトに従って、実行スコープのアーティファクトパスを独自に生成します。

レポートを {output_dir}/ln-624--{domain}.md（またはグローバルモードでは 624-quality.md）に、category: "Code Maintainability Hotspots" とチェック項目 cyclomatic_complexity、deep_nesting、long_methods、god_classes、too_many_params、quadratic_algorithms、magic_numbers、method_signatures、identifier_consistency を含めて作成してください。

summaryArtifactPath がない場合は、スタンドアロンの実行時サマリーを .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json に書き込み、必要に応じて同じサマリーを構造化出力にも含めてください。

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-624--orders.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

重要なルール

すでに読み込まれている references/audit_worker_core_contract.md を適用してください。

• 自動修正しない： 報告のみ行ってください
• ドメインを考慮したスキャン： domain_mode="domain-aware" の場合は、scan_path のみをスキャンしてください（コードベース全体は対象外です）
• 指摘へのタグ付け： ドメインを考慮した場合、各指摘に domain フィールドを含めてください
• メトリクスツール： 利用可能な場合は既存のツール（ESLint complexity plugin、radon、gocyclo）を使用してください
• 独自の観点： ローカルな保守性のホットスポットのみを監査してください。重複、パッケージの健全性、アーキテクチャの境界、N+1 の永続化動作、オーケストレーションの所有権は監査しないでください。識別子の一貫性に関する指摘は、レイヤーをまたいだ単一の概念の命名の一貫性を対象とします。これは ln-623（コードの重複）および ln-643（DTO の有無／シグネチャにおけるレイヤーの漏洩）とは異なります。
• 必要なアクション： すべての指摘で REFACTOR_HOTSPOT、SIMPLIFY_SIGNATURE、EXTRACT_CONSTANT、または UNIFY_IDENTIFIER を使用してください。

完了の定義

すでに読み込まれている references/audit_worker_core_contract.md を適用してください。

• contextStore を解析済み（domain_mode、current_domain、output_dir を含む）
• scan_path を特定済み（ドメインのパスまたはコードベースのルート）
• 9 項目すべてのチェックを完了済み（scan_path の範囲内）：
  • 複雑度、ネスト、長さ、巨大クラス、パラメーター、O(n^2)、定数、メソッドシグネチャ、識別子の一貫性
• 重大度、場所、工数、推奨事項、ドメインを含めて指摘を収集済み
• スコアを算出済み
• {output_dir}/ln-624--{domain}.md にレポートを書き込み済み（Write の単一の呼び出しによるアトミックな書き込み）
• コントラクトに従って概要を記載済み

参照ファイル

• 監査出力スキーマ： references/audit_output_schema.md

---

バージョン： 3.0.0 最終更新日： 2025-12-23