ln-624-code-quality-auditor

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリを基準とします。

コード品質監査担当（L3 ワーカー）

種類： L3 ワーカー

コードの複雑さ、メソッドシグネチャ、アルゴリズム、定数管理を監査する専門ワーカーです。

目的と範囲

• コード品質を監査します（カテゴリ 5+6+NEW：優先度「中」）
• 複雑度の指標、メソッドシグネチャの品質、アルゴリズムの効率、定数管理をチェックします
• 重要度、場所、工数、推奨事項を含む構造化された指摘を返します
• コード品質カテゴリの適合スコア（X/10）を算出します

入力

必須の読み込み： references/audit_worker_core_contract.md を読み込みます。 必須の読み込み： references/mcp_tool_preferences.md と references/mcp_integration_patterns.md を読み込みます

contextStore には次の情報が含まれます：tech_stack、best_practices、principles、codebase_root、output_dir。

ドメイン対応： domain_mode + current_domain に対応しています（audit_output_schema.md#domain-aware-worker-output を参照）。

ホットスポット、アーキテクチャの結合、またはセマンティックな関係が監査の質を大きく高める場合は、まず hex-graph を使用します。利用可能な場合、ローカルコードの読み込みにはまず hex-line を使用します。MCP が利用できない、未対応、またはインデックス化されていない場合は、組み込みの Read/Grep/Glob/Bash を使用して続行し、レポートにフォールバックした旨を記載します。

ワークフロー

必須の読み込み： 検出方法について 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 が存在する場合：
     • 複雑度と巨大クラス： audit_workspace(path=scan_path, verbosity="minimal", limit=5) を実行し、返されたホットスポットを使って複雑な関数と巨大クラスを事前に特定します。意図的に詳細調査する場合に限り、limit を引き上げます。
     • モジュール指標： analyze_architecture(path=scan_path, verbosity="full") を実行し、返された結合指標をカスケードの深さと結合の分析に使用します。
     • グラフを利用できない場合は、以下の grep パターンにフォールバックします。
     • アウトラインを先に読む： 大きなソースファイルを読む前に outline(file_path) を実行し、複雑度分析のために関数／クラスの構造を把握します。
   • 例：Grep(pattern="if.*if.*if", path=scan_path) でネストを検出します
3. 候補ごとにコンテキストを分析（レイヤー 2 -- 必須） レイヤー 2 の分析がないレイヤー 1 の指摘は、有効な指摘ではありません。報告する前に、「この違反は意図的なものか、設計上正当化されるものか」を確認します。
   • 循環的複雑度：列挙型に対する switch/case による複雑さ（妥当）か、深くネストした条件分岐によるもの（問題）かを確認します。列挙型のディスパッチは重要度を「低」に引き下げるか、対象外とします
   • O(n^2)：コンテキストを読み、n が何を指すかを確認します。上限がある場合（n < 100）は、重要度を引き下げます
   • N+1：ORM 設定を読み込み、別の箇所でイーガーローディングが設定されているかを確認します。管理者専用のエンドポイントの場合は、重要度を引き下げます
   • 巨大クラス：設定／スキーマ／ビルダークラスかどうかを確認します。その場合は重要度を引き下げます
   • カスケードの深さ：呼び出しを追跡済み（暗黙的なレイヤー 2）です。オーケストレーター関数には SEB は適用されません（ARCH-AI-SEB の「競合の解決」を参照）
4. 重要度、場所、工数、推奨事項を含む指摘を収集
   • 各指摘に domain: domain_name のタグを付けます（ドメイン対応の場合）
5. ペナルティアルゴリズムを使用してスコアを算出
6. レポートを作成： references/templates/audit_worker_report_template.md に従って完全な Markdown レポートをメモリ内に作成し、単一の 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 行
• 引き下げる場合： 設定／スキーマ／マイグレーションファイル、生成コード、バレル／インデックスファイルの場合 -> 対象外にします

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

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

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

内容： 関数のパラメーターが過剰です

検出方法：

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

深刻度：

• MEDIUM： 6-8 個のパラメーター
• LOW： 5 個のパラメーター（境界値）
• 引き下げる場合： Builder/options パターンのコンストラクター、またはフレームワークで必須のシグネチャ（ミドルウェア、フック）の場合 -> 対象外にします

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

作業量： 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 に引き下げるか、対象外にします

推奨事項： ハッシュマップを使用し、単一パスで最適化し、より適切なデータ構造を使用します

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

7. N+1 クエリパターン

内容： ORM の遅延読み込みによって N+1 クエリが発生します

検出方法：

• データベースクエリを内部で実行するループを探します
• ORM のパターンを確認します：users.forEach(u => u.getPosts())

深刻度：

• CRITICAL： API エンドポイントでの N+1（パフォーマンスに深刻な影響）
• HIGH： 頻繁に実行する処理での N+1
• MEDIUM： 管理パネルでの N+1
• 引き下げる場合： 管理者専用エンドポイントが 1 日に 1 回以下しか呼び出されない場合 -> LOW に引き下げます。ORM の別の箇所で Eager Loading が設定されている場合 -> 対象外にします

推奨事項： Eager Loading、バッチクエリ、JOIN を使用します

作業量： M（ORM クエリを変更）

8. 定数管理（新規）

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

検出方法：

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

重大度：

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

推奨事項：

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

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

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

内容： 可読性と保守性を低下させる、品質の低いメソッドコントラクト

検出方法：

問題	パターン	例
ブール値フラグのパラメーター	シグネチャにブール値のパラメーターが 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

重大度：

• 中： ブール値フラグのパラメーター（列挙型／ストラテジーパターンを使用）、不明確な戻り値の型
• 低： オプションパラメーターが多すぎる、命名が不統一

推奨事項：

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

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

10. 副作用の連鎖の深さ

内容： 外部への副作用（DB 書き込み -> 通知 -> メトリクス -> 制限）が連鎖する関数。

検出方法： 必ず読むこと： 副作用マーカー、誤検出の除外条件、追跡できないシンクの規則について、references/ai_ready_architecture.md を読み込みます。

• **/services/**/*.{py,ts,js,cs,java} を glob してサービスファイルを見つけます
• 各公開関数の本体を確認し、副作用マーカーを調べます（リファレンスに従います）
• 呼び出される内部関数を再帰的にたどり、追加のマーカーを調べます
• エントリーポイントからの連鎖の最大深度を計算します

重大度：

• 高： cascade_depth >= 4
• 中： cascade_depth = 3
• 問題なし：depth <= 2
• 重大度を下げる条件： オーケストレーター／コーディネーター関数（3 個以上のサービスをインポートし、それらに順次処理を委譲する）→ 対象外。追跡できないシンク（ログ、メトリクス）からの深度 → 対象外

競合の解決： 関数がオーケストレーター／コーディネーター（3 個以上のサービスをインポートし、それらに順次処理を委譲する）の場合、ARCH-AI-SEB は適用されません。オーケストレーターには、複数カテゴリの副作用が想定されています。SEB はリーフ関数のみを対象にします。

推奨事項： フラットなオーケストレーションにリファクタリングし、副作用を独立したシンク関数に抽出します。リファレンスを参照してください。

工数： M-L

出力： モジュールごとのサマリー Pipe／Sink テーブルも生成します：

モジュール	シンク（0-1）	浅いパイプ（2）	深いパイプ（3+）	シンク比率

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

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

出力形式

必ず読むこと： references/audit_worker_core_contract.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 Quality" と以下のチェック項目を記載したレポートを出力してください：cyclomatic_complexity、deep_nesting、long_methods、god_classes、too_many_params、quadratic_algorithms、n_plus_one、magic_numbers、method_signatures、cascade_depth。

references/audit_summary_contract.md に従ってサマリーを返してください。

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 フィールドを含めてください
• コンテキストを考慮： 小規模な関数（n < 100）では、O(n^2) が許容される場合があります
• 定数の検出： テストファイル、設定ファイル、サンプルは除外してください
• メトリクスツール： 利用可能な場合は、既存のツール（ESLint complexity plugin、radon、gocyclo）を使用してください

完了の定義

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

• contextStore を解析済み（domain_mode、current_domain、output_dir を含む）
• scan_path を特定済み（ドメインのパスまたはコードベースのルート）
• 10 項目すべてのチェックを完了済み（scan_path の範囲に限定）：
  • complexity、nesting、length、god classes、parameters、O(n^2)、N+1、constants、method signatures、cascade depth
• 重要度、場所、作業量、推奨事項、ドメインを含む検出結果を収集済み
• スコアを算出済み
• レポートを {output_dir}/ln-624--{domain}.md に書き込み済み（単一の Write 呼び出しによるアトミックな書き込み）
• コントラクトに従ってサマリーを書き込み済み

参照ファイル

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

---

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