ln-623-code-principles-auditor

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

コード原則監査担当（L3 ワーカー）

タイプ： L3 ワーカー

コード原則（DRY、KISS、YAGNI）とデザインパターンを監査する専門ワーカーです。

目的と範囲

• コード原則（DRY/KISS/YAGNI、エラー処理、DI）を監査します
• 重大度、場所、工数、pattern_signature、推奨事項を含む構造化された指摘事項を返します
• コード原則カテゴリの準拠スコア（X/10）を算出します

入力

必須の読み込み： references/audit_worker_core_contract.md を読み込みます。 ツールポリシー：ホストの AGENTS.md にある MCP の設定に従います。ホストのポリシーがない場合、または MCP の動作が不明確な場合に限り、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 を使って作業を続行し、レポートにフォールバックした旨を記載します。

ワークフロー

検出方針：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 が true、または .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：類似した命名や共有インターフェースにとどまらない、実際の重複であることを確認するため、両方のコードブロックを読みます
   • KISS：抽象化が DI パターンに役立っている（単一実装の有効なインターフェースである）のか、時期尚早なのかを確認します
   • YAGNI：フィーチャーフラグが最近追加されたもの（意図的）なのか、数か月間使われていないのかを確認します
5. 推奨事項を生成する
   • 必読： パターンの選択について、references/refactoring_decision_tree.md を読み込みます
   • 意思決定ツリーを使って、各指摘事項を適切なリファクタリングパターンに対応付けます
6. 重大度、場所、工数、pattern_id、pattern_signature、推奨事項とともに指摘事項を収集する
   • 各指摘事項に domain: domain_name を付与します（ドメインを考慮する場合）
   • ドメイン間のマッチングのため、ln-620 によって pattern_signature を割り当てます
7. ペナルティアルゴリズムを使用してスコアを計算する
8. レポートを作成する： references/templates/audit_worker_report_template.md に従って完全な Markdown レポートをメモリ上に作成し、単一の 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）-> 格下げ。現時点では単一実装だが、テスト用のインターフェース -> 対象外
YAGNI	A/B テストで使用されるフィーチャーフラグ -> 対象外。運用チームが使用する設定オプション -> 対象外
エラーハンドリング	50 行のスクリプトに中央集約型のハンドラーがない -> LOW に格下げ
DI	パラメーター／クロージャー経由で依存関係を差し替え可能 -> 対象外、ARCH-DI

監査ルール

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 し、サブクラス数を数える	高：コアロジックの理解を妨げる	DI／テスト用のインターフェース → スキップ。フレームワークで必須（Spring、ASP.NET） → スキップ	抽象化を削除し、インライン化する	L
3種類未満の型を扱うファクトリー	ファクトリーパターンを grep し、分岐数を数える	中：不要なパターン	DI／テスト用の差し替えにファクトリーを使用 → 引き下げ	直接インスタンスを生成する形に置き換える	M
3階層を超える深い継承	extends の連鎖をたどる	高：壊れやすい階層構造	フレームワークで必須の階層構造（UI ウィジェット、ORM モデル） → 引き下げ	コンポジションを使ってフラット化する	L
過剰なジェネリック制約	<T extends ... & ...> を grep する	低：許容できるトレードオフ	公開 API の境界における型安全性 → スキップ	制約を簡素化する	M
ラッパーに徹したクラス	確認：すべてのメソッドが内部のクラスに委譲している	中：不要な間接化	外部 API を分離するためのアダプターパターン → スキップ	ラッパーを削除し、内部のクラスを直接使用する	M

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

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

4. エラーハンドリングの欠如

• try-catch のない非同期関数を見つける
• エラーミドルウェアのない API ルートを確認する
• データベース呼び出しにエラーハンドリングがあることを確認する

重大度	基準
致命的	エラーハンドリングのない決済／認証
高	エラーハンドリングのないユーザー向け操作
中	エラーハンドリングのない内部操作

工数： M

5. 集中的なエラーハンドリング

• 集中型エラーハンドラーを検索する：ErrorHandler、errorHandler、error-handler.*
• ミドルウェアがハンドラーに処理を委譲するか確認する
• 非同期ルートが promise／async-await を使用していることを確認する
• アンチパターン： process.on("uncaughtException") の使用

重大度	基準
高	集中型エラーハンドラーがない
高	uncaughtException リスナーを使用している（Express のアンチパターン）
中	ミドルウェアがエラーを直接処理している（委譲していない）
中	適切なエラーハンドリングのない非同期ルート
低	本番環境でスタックトレースが公開される

目標： すべてのエラーがコンテキストとともにログに記録され、ユーザーにわかりやすいメッセージが返されます。エラーが握りつぶされることはありません。本番環境のレスポンスにスタックトレースが漏れることはありません。実装方法（ErrorHandler クラス、ミドルウェア、デコレーター）はプロジェクトのスタックと規模に応じて選択します。

工数： M-L

6. 依存性注入 / 集中初期化

• DI コンテナの有無を確認する: inversify、awilix、tsyringe (Node)、dependency_injector (Python)、Spring @Autowired (Java)、ASP.NET IServiceCollection (C#)
• ビジネスロジック内の new SomeService() (直接インスタンス化) を grep する
• ブートストラップモジュールの有無を確認する: bootstrap.ts、init.py、Startup.cs、app.module.ts

重大度	基準
MEDIUM	DI コンテナがない (密結合)
MEDIUM	ビジネスロジック内での直接インスタンス化
LOW	DI と直接インポートの混在

達成目標: 本番コードを変更せずに、テストのために依存関係を差し替えられるようにします。サービスのインスタンス化とビジネスロジックの間に密結合が存在しないようにします。実装の選択 (DI コンテナ、ファクトリ関数、パラメータ注入、クロージャ) は、プロジェクトの規模とスタックによって異なります。

工数: L

7. ベストプラクティスガイドの欠如

• 以下を確認する: docs/architecture.md、docs/best-practices.md、ARCHITECTURE.md、CONTRIBUTING.md

重大度	基準
LOW	アーキテクチャ / ベストプラクティスガイドがない

推奨事項: レイヤリングのルール、エラーハンドリングのパターン、DI の使用法、コーディング規約を記載した docs/architecture.md を作成します。

工数: S

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

必読: 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: "Architecture & Design" を付けて書き込みます。

FINDINGS-EXTENDED ブロック (このワーカーで必須): Findings テーブルの後に、ln-620 コーディネーターによるクロスドメインマッチングのために 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 時間超
• 除外: 生成されたコード、vendor、マイグレーションをスキップします (detection_patterns.md#exclusions を参照)

完了の定義

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

• contextStore を解析済み（domain_mode、current_domain、output_dir を含む）
• scan_path を決定済み（ドメインのパスまたはコードベースのルート）
• 検出パターンを references/detection_patterns.md から読み込み済み
• 7 つのチェックをすべて完了済み（scan_path の範囲内）：
  • DRY（10 個のサブカテゴリー：1.1～1.10）、KISS、YAGNI、エラー処理、エラーの一元管理、DI／初期化、ベストプラクティスガイド
• 推奨事項を references/refactoring_decision_tree.md を使用して選定済み
• 重大度、場所、工数、pattern_id、pattern_signature、推奨事項、ドメインを含む指摘事項を収集済み
• references/audit_scoring.md に従ってスコアを算出済み
• FINDINGS-EXTENDED ブロックを含むレポートを {output_dir}/ln-623--{domain}.md に書き込み済み（Write 呼び出し 1 回で原子的に実行）
• コントラクトに従って概要を作成済み

参照ファイル

• 検出パターン： references/detection_patterns.md
• リファクタリング決定木： references/refactoring_decision_tree.md

---

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