ln-637-test-structure-auditor

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

保守性／構成監査担当（L3 ワーカー）

種類： L3 ワーカー

テストスイートの拡大に伴う保守性を確保するため、テストファイルの構成、孤立したテスト、分散した重複、配置のずれを監査する専門ワーカーです。

目的と範囲

• テストの保守性／構成（カテゴリ 8：中優先度）を監査します
• 配置パターン（フラット／ミラー型／ソースと同じ場所／ハイブリッド）を検出します
• 増加のしきい値を超えたフラットなディレクトリを検出し、ドメインごとのグループ化を推奨します
• テストとソースの対応関係の一貫性、孤立したテスト、分散した重複を検証します
• MOVE、MERGE、DELETE_ORPHAN を出力します
• 適合スコア（X/10）を算出します

入力

必ず読み込むこと： references/audit_worker_core_contract.md を読み込みます。

次の情報を含む contextStore を受け取ります：tech_stack、testFilesMetadata（自動テストと手動テストの両方を含む、すべての種類）、codebase_root、output_dir、domain_mode、all_domains。

注： ディレクトリ構造の分析には、自動テストと手動テストの両方がどこに配置されているかを含む全体像が必要なため、このワーカーは、種類でフィルターされたメタデータを受け取る他のワーカーとは異なり、すべてのテストファイルを受け取ります。

ワークフロー

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

1. コンテキストを解析： contextStore からテストファイル一覧、output_dir、codebase_root、ドメイン情報を抽出します
2. ソース構造をマッピング： ソースディレクトリ（src/、app/、lib/）を Glob で検索し、ソースのドメイン／モジュールツリーを構築します
3. テスト構造をマッピング： テストファイルを親ディレクトリごとにグループ化し、ディレクトリごとのファイル数を数え、配置場所を分類します
4. チェックをスキャン（レイヤー 1）： Glob／Grep パターンを使用して、6 つの監査チェックを実行します（「監査ルール」を参照）
5. コンテキストを分析（レイヤー 2 -- 必須）： 候補となる各指摘に対して、レイヤー 2 のフィルターを適用します（各チェックを参照）
6. 指摘を収集： 違反を重要度、場所、工数、アクション、推奨事項とともに記録します
7. スコアを算出： 重要度ごとに違反数を数え、適合スコア（X/10）を算出します
8. レポートを作成： references/templates/audit_worker_report_template.md に従って完全な Markdown レポートをメモリ上に構築し、単一の Write 呼び出しで {output_dir}/ln-637--global.md に書き込みます
9. 概要を返す： 最小限の概要をコーディネーターに返します（「出力形式」を参照）

監査ルール

1. 配置パターンの検出

内容： プロジェクトで使用されているテスト構成パターンを検出し、意図しない混在がないか確認します

検出方法：

• 各テストファイルの配置場所を分類します：
  • ソースと同じ場所： ソースファイルと同じディレクトリにあるテストファイル（例：src/users/users.test.ts）
  • ミラー型： 並行する階層にあるテストファイル（例：tests/users/users.test.ts は src/users/ に対応）
  • 一元管理・フラット： すべてのテストが単一ディレクトリにある（例：tests/ または __tests__/）
  • 手動： tests/manual/ 内のファイル（情報提供のみで、指摘対象外）
• パターンごとの割合を算出します
• ファイルの 70% 超が 1 つのパターンに従う場合、そのパターンを支配的なパターンとします
• 70% に達するパターンがない場合は、ハイブリッドとします

レイヤー 2：

• 異なるテスト種別で異なるパターンを使用している場合、ハイブリッドは許容されます（例：ユニットテストはソースと同じ場所に配置し、統合テストは tests/automated/integration/ に配置する）。逸脱がテスト種別と相関しているか確認します
• テストファイルが 5 件未満のプロジェクトはスキップします（パターンを特定するには少なすぎます）

重要度： テスト種別に基づく明確なルールがなく、ハイブリッドの場合は 中（同じ種別のテストの 30% 超が支配的なパターンから逸脱）

推奨事項： テストの配置を標準化します。テスト種別ごとに 1 つのパターンを選び、テストガイドラインに記載してください アクション： MOVE

工数： L

2. テストとソースのマッピング

内容： ソースファイルが削除されたのにテストが残っている孤立したテストファイルや、パスの不一致を検出します。

検出方法：

• 各テストファイルから、対応するソースモジュールを特定します。
  • users.test.ts -> users.ts または users/index.ts
  • test_payments.py -> payments.py
• 対応するソースファイルが想定された場所に存在するか確認します。
• ソースファイルが見つからない場合、孤立したテストの候補とします。

レイヤー 2：

• 統合テスト／e2e テストはスキップします（複数のモジュールをテストするため、1 対 1 のソースマッピングがありません）。
• 集中管理されたフラットなレイアウトのテストはスキップします（パスベースのマッピングが想定されません）。
• 複数のソースモジュールをインポートするテストファイルはスキップします（性質上、統合テストであるため）。
• ユーティリティ／ヘルパーのテストファイル（test_utils.ts、test_helpers.py）はスキップします。

重大度： 孤立したテストは MEDIUM（デッドコード）、パスの不一致は LOW

推奨事項： 孤立したテストを削除するか、現在のソース構造に合わせて更新します。 アクション： ソースの動作が存在しなくなった場合は DELETE_ORPHAN、それ以外の場合は MOVE

工数： S

3. フラットディレクトリの肥大化

内容： サブディレクトリに分けることで整理しやすくなる、ファイル数が過剰なテストディレクトリを検出します。

検出方法：

• ディレクトリごとにテストファイル数を数えます（node_modules、dist、build を除外）。
• しきい値：
  • フラットなディレクトリに 15～20 ファイル -> LOW（上限に近づいています）
  • フラットなディレクトリに >20 ファイル -> MEDIUM（再構成を推奨）
• MEDIUM の検出結果では、ファイル名の接頭辞を分析して、ドメインベースのグループ分けを提案します。
  • 共通の接頭辞でグループ化します（例：test_auth_*.py -> auth/ サブディレクトリ）。
  • 利用可能であれば、ソースのドメイン構造と照合します。

レイヤー 2：

• ディレクトリにすでにサブディレクトリがある場合はスキップします（一部整理済み）。
• サブディレクトリがなくても十分に整理できる、明確な命名接頭辞をファイルに使用している場合はスキップします。
• tests/manual/ はスキップします（手動テストには別の規約があります）。

重大度： MEDIUM（>20 ファイル）、LOW（15～20 ファイル）

推奨事項： ドメイン／機能ごとにテストをサブディレクトリにまとめます。ファイル名の分析に基づき、具体的なグループ分けを提案します。

# Before (flat):
tests/test_auth_login.py, tests/test_auth_tokens.py, tests/test_users_crud.py, ...

# After (grouped):
tests/auth/test_login.py, tests/auth/test_tokens.py, tests/users/test_crud.py, ...

工数： M アクション： MOVE

4. ドメインのグループ分けの整合性

内容： テストディレクトリのグループ分けが、ソースのドメイン構造を反映しているか確認します。

検出方法：

• ソースのドメインディレクトリ（all_domains またはスキャンした src/ から取得）とテストディレクトリ名を比較します。
• 各ソースドメインについて、対応するテストグループが存在するか確認します。
  • ミラー配置：tests/{domain}/ ディレクトリが存在する
  • 同じ場所に配置：src/{domain}/ にテストファイルが存在する
• 対応するテストグループがないソースドメインを報告します。

レイヤー 2：

• プロジェクトに明確なドメイン構造がない場合（domain_mode="global" またはソースドメインが 2 つ未満）はスキップします。
• references／common／utils ドメインはスキップします（横断的な領域のため、専用のテストグループが不要な場合があります）。
• プロジェクトが集中管理されたフラットなレイアウトを使用している場合はスキップします（グループ分けが想定されません）。

重大度： ソースファイルが 5 個を超えるのにテストグループがないドメインは MEDIUM、それ以外は LOW

推奨事項： 構造の整合性を保つため、ドメイン用のテストディレクトリ／グループを作成します。

工数： M アクション： MOVE

5. 同一ディレクトリ配置の一貫性

概要： プロジェクトで採用している同一ディレクトリ配置パターンを検出し、不整合を報告します

検出方法：

• ソースファイルの隣に配置されたテストファイルと、専用のテストディレクトリに配置されたテストファイルの数を数えます
• 比率を算出します：同一ディレクトリ配置 / （同一ディレクトリ配置 + 集中配置）
• 比率が0.0～0.2の場合 -> 集中配置パターン
• 比率が0.8～1.0の場合 -> 同一ディレクトリ配置パターン
• 比率が0.2～0.8の場合 -> 混在（不整合の可能性）
• 混在の場合：支配的なパターンから逸脱しているモジュールを特定します

レイヤー2：

• テストの種類によって配置場所が異なる場合、混在は許容されます：
  • 単体テストは同一ディレクトリ配置、統合テスト／E2Eテストは集中配置 -> 有効なハイブリッド
  • テストファイルの命名や配置場所とテストの種類との相関を確認します
• テストファイルが5件未満のプロジェクトはスキップします

重大度： 同じ種類のテストの20%超が、支配的な配置パターンから逸脱している場合は MEDIUM

推奨事項： テストの配置を統一し、逸脱しているテストをプロジェクトの支配的なパターンに従うよう移動します

作業量： M-L アクション： MOVE

6. 分散した重複テスト

概要： 1つの正規テストにまとめることで保守しやすくなる、ファイル間に散在する重複または類似のテストを検出します

検出方法：

• インポートされているソースモジュールとテストの説明に含まれるキーワードでテストをグループ化します
• ファイル間で繰り返されるセットアップブロック、アサーション、重複するシナリオ名を探します
• ソースインポートが重複し、Arrange／Assertの内容が類似するテストファイルを比較します

レイヤー2：

• 各ファイルが異なる環境、アダプター、プロバイダー、またはブラウザーを対象とする、意図的なマトリックステストはスキップします
• アサーションが異なる製品動作を対象とする重複名はスキップします
• ln-632 によってE2Eの無駄としてすでに報告されている重複はスキップします。このワーカーは構造上の分散のみを対象とします

重大度： 重複した構造によって保守コストが増加する場合は MEDIUM、局所的な小規模の重複の場合は LOW

推奨事項： 製品のシグナルを維持できる場合は、重複するテストを1つの正規の場所または共有ヘルパーにまとめます

作業量： S-M アクション： MERGE

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

必ず読むこと： references/audit_scoring.md を読み込みます。

重大度の対応付け：

• 孤立したテスト、過剰なフラットディレクトリ（20超）、レイアウトの不整合、同一ディレクトリ配置の不整合、分散した重複テスト -> MEDIUM
• フラットディレクトリの上限に近い（15～20）、ドメインテストグループの不足（小規模ドメイン）、パスの不一致 -> LOW

出力形式

必ず読むこと： references/templates/audit_worker_report_template.md を読み込みます。

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

レポートを {output_dir}/ln-637--global.md に書き込み、category: "Test Maintainability" および次のチェックを含めます：layout_pattern、test_source_mapping、flat_dir_growth、domain_grouping、colocation_consistency、fragmented_duplicates。

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-637--global.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

重大なルール

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

• 自動修正禁止： 報告のみ行い、再構成を提案してください
• 作業量の現実性： S = 1 時間未満、M = 1～4 時間、L = 4 時間超
• 軽微な場合はスキップ： テストファイルが合計 5 個未満の場合は、指摘事項なしでスコア 10/10 を返してください
• 命名チェック禁止： テストの命名規則（.test. と .spec.）の一貫性確認は対象外です。重複して指摘しないでください
• 両方の種類を対象にする： 構成全体を把握するため、自動テストと手動テストの両方のファイル配置を分析してください
• 具体的な提案： フラットなディレクトリの肥大化に関する指摘では、ファイル名のプレフィックス分析に基づいた具体的なサブディレクトリへの分類を必ず提案してください
• 独自の観点： 保守性と構造のみを監査してください。製品の動作、E2E の利用価値、ポートフォリオとしての価値、不足しているカバレッジ、信頼性、オラクルの強さ、手動テストの証跡の品質は評価しないでください
• 対応必須： 各指摘には MOVE、MERGE、DELETE_ORPHAN のいずれかを使用してください

完了の定義

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

• contextStore を正常に解析した（output_dir、ドメイン情報を含む）
• ソース構造をマッピングした（ドメイン／モジュールのツリー）
• テスト構造をマッピングした（ディレクトリ別にファイルを分類し、件数を算出）
• 6 項目すべてのチェックを完了した
• レイヤー 2 のコンテキスト分析を適用した（タイプベースのハイブリッド、小規模プロジェクトの除外）
• レイアウトのパターンを検出し、レポートに記載した
• フラットなディレクトリの肥大化の兆候を特定し、具体的な分類案を提示した
• 重大度、場所、作業量、アクション、推奨事項を含む指摘事項を収集した
• ペナルティアルゴリズムを使用してスコアを算出した
• {output_dir}/ln-637--global.md にレポートを書き込んだ（Write を 1 回だけ使用し、アトミックに実行）
• 契約に従ってサマリーを書き込んだ

---

バージョン： 1.0.0 最終更新日： 2026-03-15