ln-623-duplication-overabstraction-auditor

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

重複・過剰抽象化監査担当（L3 ワーカー）

種別： L3 ワーカー

重複、過剰抽象化、未使用の拡張性を監査する専門ワーカーです。

目的と範囲

• 重複と過剰抽象化（DRY/KISS/YAGNI）を監査します
• 重大度、場所、作業量、pattern_signature、推奨事項を含む、構造化された調査結果を返します
• MERGE_DUPLICATION、REMOVE_ABSTRACTION、または REMOVE_YAGNI を出力します
• 重複・過剰抽象化カテゴリの適合スコア（X/10）を算出します

入力

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

ワークフロー

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

1. コンテキストを解析 -- フィールドを抽出し、scan_path（指定がある場合はドメインを考慮）を決定し、output_dir を抽出します
2. 検出パターンを読み込む
   • 必読： 言語固有の Grep/Glob パターンについて、references/detection_patterns.md を読み込みます
   • プロジェクトの tech_stack に一致するパターンを選択します
3. コードベースをスキャンして違反を検出（第 1 層）
   • すべての Grep/Glob パターンで codebase_root ではなく scan_path を使用します
   • グラフによる高速化（利用可能な場合）： contextStore.graph_indexed が真、または .hex-skills/codegraph/index.db が存在する場合：
     • DRY（1.1-1.10）： audit_workspace(path=scan_path, verbosity="minimal", limit=5, clone_member_limit=3) -- 返されたクローングループはそれぞれ DRY の候補です。意図的に詳細を調査する場合にのみ上限を引き上げます。深刻度の判定には、クローンの種類とホットスポットのコンテキストを使用します。利用できない場合は grep パターンにフォールバックします。
     • KISS の継承： 抽象クラスに対して find_implementations(symbol) を使い、実装数を数えます（1 件 = KISS の候補）。グラフを使って継承の深さをたどります。
     • 複雑性： audit_workspace(path=scan_path, verbosity="minimal", limit=5) -- 返されたホットスポットを使い、KISS／品質分析の対象となる複雑な関数を事前に特定します。詳細調査を意図する場合にのみ limit を引き上げます。
     • 概要を先に読む： 大きなソースファイルを読む前に outline(file_path) を実行し、原則を分析する前に構造を把握します。
   • detection_patterns.md の手順に沿って検出します
   • detection_patterns.md#exclusions の除外項目を適用します
4. 候補ごとにコンテキストを分析（第 2 層）
   • DRY：2 つのコードブロックを両方読み、単なる命名の類似や共有インターフェースではなく、実際の重複であることを確認します
   • KISS：抽象化が DI パターン（単一実装でも妥当なインターフェース）に役立つのか、時期尚早なのかを確認します
   • YAGNI：機能フラグが最近追加された（意図的）ものか、数か月間使われていないものかを確認します
5. 推奨事項を作成
   • 必読： パターンの選択にあたり、references/refactoring_decision_tree.md を読み込みます
   • 判断ツリーを使って、各指摘を適切なリファクタリングパターンに対応付けます
6. 深刻度、場所、工数、pattern_id、pattern_signature、推奨事項とともに指摘事項を収集
   • 各指摘事項に domain: domain_name をタグ付けします（ドメインを考慮する場合）
   • 管理対象の集約用に pattern_signature を割り当てます
7. ペナルティアルゴリズムを使ってスコアを計算
8. レポートを作成： references/templates/audit_worker_report_template.md に従って完全な Markdown レポートをメモリ上に作成し、1 回の Write 呼び出しで {output_dir}/ln-623--{domain}.md（またはグローバルモードでは 623-principles.md）に書き込みます。ドメイン間 DRY 分析用の pattern_signature フィールドを含む `` JSON ブロックを必ず含めます
9. 概要を返す： 最小限の概要を返します（出力形式を参照）

2 層検出

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

すべての指摘事項で第 2 層のコンテキスト分析が必要です。第 2 層の分析がない第 1 層の指摘は、有効な指摘事項ではありません。報告する前に、「この違反は意図的なものですか、それとも設計上の妥当な理由がありますか？」と確認します。

指摘の種類	第 2 層で格下げする例
DRY	ライフサイクル／所有者が異なるモジュール → 対象外とします。結合を避けるための意図的な重複 → 対象外とします
KISS	フレームワークで必須の抽象化（例：Spring の DI） → 格下げします。現時点では実装が 1 つでも、テスト用のインターフェースである → 対象外とします
YAGNI	A/B テストで使用されている機能フラグ → 対象外とします。運用チームが使用する設定オプション → 対象外とします

監査ルール

1. DRY 違反（Don't Repeat Yourself）

必読： 各タイプの検出手順については、references/detection_patterns.md を読み込んでください。

タイプ	内容	重大度	例外（スキップ／引き下げ）	推奨される対応	工数
1.1 同一コード	複数のファイルにある同一の関数／定数／ブロック（10行超）	高：ビジネスクリティカル（認証、決済）。中：ユーティリティ。低：5回未満の単純な定数	ライフサイクル／所有者が異なるモジュール -> スキップ。意図的な疎結合 -> スキップ	関数を抽出 -> 重複の範囲に応じて配置場所を決定	M
1.2 検証処理の重複	複数のファイルにある同一の検証パターン（メール、パスワード、電話番号、URL）	高：認証／決済。中：3回以上のユーザー入力。低：3回未満の形式チェック	セキュリティコンテキストが異なる（認証と公開処理など） -> スキップ	共有バリデーター用モジュールに抽出	M
1.3 エラーメッセージの繰り返し	一元管理されたカタログを使わず、エラー文字列をハードコード	中：重要なメッセージがハードコードされている、またはエラーカタログがない。低：3か所未満	コンテキストごとに表現を変える必要があるユーザー向け文字列 -> 引き下げ	定数／エラーメッセージ用ファイルを作成	M
1.4 類似パターン	呼び出し順序／制御フローは同じで、名前やエンティティが異なる関数	中：重要な処理経路にあるビジネスロジック。低：3回未満のユーティリティ	今後別々に進化することが見込まれるモジュール -> スキップ	共通ロジックを抽出（パターンについては判断ツリーを参照）	M
1.5 SQL／ORM の重複	異なるサービスにある同一クエリ	高：決済／認証クエリ。中：一般的なクエリが3回以上。低：3回未満の単純なクエリ	境界づけられたコンテキストが異なる場合。DB を共有するより重複させる方が望ましい場合 -> スキップ	Repository 層に抽出	M
1.6 コピー＆ペーストされたテスト	複数のテストファイルにある同一のセットアップ／ティアダウン／フィクスチャ	中：5ファイル以上のセットアップ。低：5ファイル未満	明確さ／独立性のために意図的に分離されたテスト -> 引き下げ	テストヘルパーに抽出	M
1.7 API レスポンスの繰り返し	DTO を使わずに同じ形状のレスポンスオブジェクトを繰り返し使用	中：5エンドポイント以上。低：5エンドポイント未満	バージョン管理のライフサイクルが異なるレスポンス -> スキップ	DTO／Response クラスを作成	M
1.8 ミドルウェアチェーンの重複	複数のルートにある同一のミドルウェア／デコレーターのスタック	中：5ルート以上で同一チェーンを使用。低：5ルート未満	認証／レート制限の要件が異なるルート -> スキップ	名前付きミドルウェアグループを作成し、ルーター層で適用	M
1.9 型定義の重複	フィールドの80％以上が同じインターフェース／構造体／型	中：5ファイル以上。低：2～4ファイル	所有者／進化の経路が異なる型 -> スキップ	共有ベース型を作成し、必要に応じて拡張	M
1.10 マッピングロジックの重複	複数箇所にある同一のエンティティ->DTO／DTO->エンティティ変換	中：3か所以上。低：2か所	検証／拡張ルールが異なるマッピング -> スキップ	専用の Mapper クラス／関数を作成	M

推奨方法の選択： 重複の場所（レベル1）とロジックの種類（レベル2）に基づいて適切なリファクタリングパターンを選ぶには、references/refactoring_decision_tree.md を使用してください。

2. KISS 違反（シンプルに保つ）

違反	検出方法	重大度	例外（スキップ／引き下げ）	推奨事項	工数
実装が1つだけの抽象クラス	abstract class を grep して、サブクラスの数を数える	HIGH：コアロジックの理解を妨げます	DI／テスト用のインターフェース → スキップ。フレームワークで必須（Spring、ASP.NET） → スキップ	抽象化を削除し、インライン化する	L
3種類未満の型に対するファクトリー	ファクトリーパターンを grep して、分岐の数を数える	MEDIUM：不要なパターンです	DI／テスト用の差し替えに使うファクトリー → 引き下げ	直接インスタンスを生成する	M
3階層を超える深い継承	extends の連鎖をたどる	HIGH：脆弱な階層構造です	フレームワークで必須の階層（UI ウィジェット、ORM モデル） → 引き下げ	コンポジションでフラット化する	L
過剰なジェネリック制約	<T extends ... & ...> を grep する	LOW：許容できるトレードオフです	公開 API 境界の型安全性を確保するもの → スキップ	制約を簡素化する	M
ラッパーだけのクラス	読み取る：すべてのメソッドが内部のクラスに処理を委譲している	MEDIUM：不要な間接層です	外部 API を分離するアダプターパターン → スキップ	ラッパーを削除し、内部のクラスを直接使う	M

3. YAGNI 違反（必要になるまで作らない）

違反	検出方法	重大度	例外（スキップ／引き下げ）	推奨事項	工数
使用されていないフィーチャーフラグ（常に true／false）	フラグを grep して、切り替えられたことがないか確認する	LOW：クリーンアップが必要です	A/B テスト用のフラグ → スキップ。運用管理のトグル → スキップ	フラグを削除し、有効なコードパスは残す	M
オーバーライドされていない抽象メソッド	abstract を grep して、実装を検索する	MEDIUM：使用されていない拡張性です	公開ライブラリのプラグイン／拡張ポイント → 引き下げ	abstract を削除し、具象メソッドにする	M
使用されていない設定オプション	設定キーを grep して、参照が0件か確認する	LOW：使用されていない設定です	環境固有の設定（staging／prod） → 指摘する前に確認する	オプションを削除する	S
実装が1つだけのインターフェース	インターフェースを grep して、実装クラスの数を数える	MEDIUM：時期尚早な抽象化です	DI／テスト用モックのためのインターフェース → スキップ	インターフェースを削除し、クラスを直接使う	M
時期尚早なジェネリクス（1つの型で使用）	ジェネリックの使用箇所を grep して、型パラメーターの数を数える	LOW：過剰な設計です	利用者向けに設計された公開ライブラリ API → スキップ	ジェネリックを具体的な型に置き換える	S

4. エビデンスの条件

美的な好みを指摘してはいけません。コードの繰り返し、実際の変化点がない抽象化、または保守コストを増やす未使用の拡張性を作業者が示せる場合に限り、指摘は有効です。

問題	必要なエビデンス	対応
重複	一致するコードブロック、繰り返される検証／クエリ／マッピング、または複数のファイルで繰り返される pattern_signature	MERGE_DUPLICATION
過剰な抽象化	フレームワーク／テスト上の必要性がなく、実際の実装が1つだけの抽象化レイヤー	REMOVE_ABSTRACTION
YAGNI	現在使われていないフィーチャーフラグ、設定オプション、ジェネリック、または拡張ポイント	REMOVE_YAGNI

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

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

出力形式

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

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

レポートを {output_dir}/ln-623--{domain}.md（グローバルモードでは 623-principles.md）に category: "Duplication & Over-Abstraction" を付けて出力してください。

FINDINGS-EXTENDED ブロック（このワーカーでは必須）： Findings テーブルの後に、管理モードでの集約用に pattern_signature を含むすべての DRY 検出結果をまとめた `` JSON ブロックを記載してください。references/templates/audit_worker_report_template.md に従ってください。

pattern_id： DRY の種類を示す識別子（dry_1.1 から dry_1.10）。DRY 以外の検出結果では省略してください。

pattern_signature： 検出されたパターンの正規化キー（例：validation_email、sql_users_findByEmail、middleware_auth_validate_ratelimit）。複数のドメインで同じシグネチャが検出された場合、ドメイン横断の DRY 検出結果として扱われます。形式は references/detection_patterns.md で定義されています。

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-623--users.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 フィールドを含めてください
• パターンシグネチャ： すべての DRY 検出結果に pattern_id と pattern_signature を含めてください
• コンテキストを考慮： プロジェクトの principles.md を使用して、許容される内容を判断してください
• 工数の目安： S = 1 時間未満、M = 1～4 時間、L = 4 時間超
• 除外対象： 生成コード、ベンダーコード、マイグレーションを除外してください（detection_patterns.md#exclusions を参照）
• 対象範囲を限定： 重複、過度な抽象化、未使用の拡張性のみを監査してください。デリバリーゲート、セキュリティ、パッケージの健全性、ローカルな複雑度メトリクス、アーキテクチャ境界、実行時のライフサイクルは監査しないでください。
• 必要なアクション： すべての検出結果に MERGE_DUPLICATION、REMOVE_ABSTRACTION、REMOVE_YAGNI のいずれかを指定してください。

完了条件

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

• contextStore を解析済み（domain_mode、current_domain、output_dir を含む）
• scan_path を決定済み（ドメインのパスまたはコードベースのルート）
• references/detection_patterns.md から検出パターンを読み込み済み
• 次の 3 項目すべてを確認済み（scan_path の範囲内）：
  • DRY（10 のサブカテゴリ：1.1～1.10）、KISS、YAGNI
• references/refactoring_decision_tree.md を使用して推奨事項を選択済み
• 重要度、場所、工数、アクション、pattern_id、pattern_signature、推奨事項、domain を含む検出結果を収集済み
• references/audit_scoring.md に従ってスコアを算出済み
• FINDINGS-EXTENDED ブロックを含むレポートを {output_dir}/ln-623--{domain}.md に書き込み済み（単一の Write 呼び出しでアトミックに実行）
• コントラクトに従ってサマリーを出力済み

参照ファイル

• 検出パターン： references/detection_patterns.md
• リファクタリング判断ツリー： references/refactoring_decision_tree.md

---

バージョン： 5.0.0 最終更新日： 2026-02-08