ln-512-tech-debt-cleaner

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

技術的負債のクリーンアップ（L3 ワーカー）

タイプ： L3 ワーカー

コードベース監査で検出された、安全でリスクの低い技術的負債を自動的にクリーンアップします。

目的と対象範囲

• docs/project/codebase_audit.md（ln-620 の出力）または ln-511 のコード品質出力から監査結果を取り込みます
• 信頼度が 90% 以上の、自動修正可能な検出結果に絞り込みます
• 安全な修正を適用します：未使用のインポートの削除、デッドコードの削除、コメントアウトされたブロックの整理、サポートされていないエイリアスの削除
• ビジネスロジック、複雑なリファクタリング、アーキテクチャの変更には決して手を加えません
• すべての変更を構造化した要約とともに、単一のコミットを作成します
• ln-510 の品質調整パイプラインから、または単独で呼び出せます

自動修正可能なカテゴリ

カテゴリ	ソース接頭辞	リスク	自動修正アクション
未使用のインポート	MNT-DC-	低	インポート行を削除
未使用の変数	MNT-DC-	低	宣言を削除
未使用の関数（非エクスポート）	MNT-DC-	低	関数ブロックを削除
コメントアウトされたコード（5 行超）	MNT-DC-	低	コメントブロックを削除
後方互換性シム（6 か月超）	MNT-DC-	中	シムを削除し、再エクスポートを更新
サポートされていないエイリアス	MNT-DC-	低	エイリアス行を削除
末尾の空白／空行	MNT-	低	末尾の空白を削除／空行をまとめる

自動修正の対象外（常にスキップ）

カテゴリ	理由
DRY 違反（MNT-DRY-）	抽出先のアーキテクチャ上の判断が必要
巨大クラス（MNT-GOD-）	分割にはドメイン知識が必要
セキュリティの問題（SEC-）	コンテキストに応じた修正が必要
アーキテクチャ違反（ARCH-*）	設計上の判断が必要
パフォーマンスの問題（PERF-*）	ベンチマークが必要
工数が M または L の検出結果	自動修正には複雑すぎます

使用するタイミング

• コード品質分析後、安全でリスクの低いクリーンアップを適用できる場合に使用します
• 単独実行： ln-620 によるコードベース監査の完了後（ユーザーが手動で起動）
• 定期実行： コードベースの健全性を保つための定期的な「ガベージコレクション」として

入力

• パイプラインモード（ln-510）： ln-511 のコード品質出力からの検出結果（調整役のコンテキスト経由で渡されます）
• 単独モード： docs/project/codebase_audit.md（ln-620 の出力）

必読： references/mcp_tool_preferences.md を読み込みます。コードファイルでは、hex-line MCP が利用可能な場合は必ず使用してください。hex-line がダウンしている場合を除き、標準の Read/Edit へのフォールバックはしないでください。

必読： references/mcp_integration_patterns.md を読み込みます。

コードファイルには hex-line を主要な手段として使用し、デッドコードの参照チェックには hex-graph を主要な手段として使用します。組み込みの Read/Edit/Grep は、該当する MCP が利用できない場合に限り、フォールバックとして使用します。

ワークフロー

1. 検出結果を読み込む： docs/project/codebase_audit.md を読み込みます。Dead Code セクション（ln-626 の結果）と Code Quality セクション（ln-624 の結果）から検出結果を解析します。

2. 自動修正可能な項目に絞り込む：

   • カテゴリは上記の Auto-Fixable テーブルに含まれている必要があります
   • 重大度は LOW または MEDIUM（HIGH／CRITICAL は対象外）である必要があります
   • 工数は S（小）である必要があります
   • 次のファイルは対象外とします：node_modules/、vendor/、dist/、build/、*.min.*、生成コード、テストフィクスチャ

3. 各検出結果を検証する（信頼度を確認）： 必ず読み込むこと： references/clean_code_checklist.md を読み込みます 修正候補ごとに、次を行います。 a) 指定された場所にある対象ファイルを読み込みます b) 検出内容がまだ存在することを確認します（監査後にファイルが変更されている場合があります） c) 削除しても安全であることを確認します：

   • 未使用のインポート：使用箇所をコードベース全体で grep します（参照が 0 件である必要があります）
   • 未使用の関数：関数名を grep します（呼び出し箇所が 0 件である必要があります）
   • コメントアウトされたコード：ドキュメントではなくコードであることを確認します
   • 未サポートのエイリアス：利用者が残っていないことを確認します d) 信頼度スコア（0～100）を割り当てます。信頼度が 90 以上の場合のみ続行します

   Hex-line による効率化（利用可能な場合）： Hex-line MCP サーバーが利用可能な場合：

   • 手動でクリーンアップ編集する前に、outline(file_path) と、探索を優先した read_file() を使用します。edit_file に必要なリビジョン／チェックサムを取得する場合に限り、edit_ready=true, verbosity="full" を指定して再読み込みします。
   • クリーンアップを一括処理： 同じパターン（例：未使用のインポートの削除）を 3 ファイルを超えて修正する場合は、bulk_replace(dry_run=true) でプレビューしてから、bulk_replace() で適用します。
   • 編集の検証： 各修正の後に verify(file_path, checksums) を実行し、古い状態でないことを確認します。
   • セマンティックなデッドコードの確認： エクスポート、ラッパー、エイリアス、またはシムを削除する前に find_references() を使用します。
   • 該当する MCP が利用できない場合のみ、ファイルごとの Edit または Grep に切り替えます。

4. 修正を適用し、修正ごとに保持または破棄する（autoresearch パターン）： 必ず読み込むこと： 検出階層を確認するため、references/ci_tool_detection.md を読み込みます。lint と型チェックのコマンドを一度検出し、すべての修正で再利用します。

   検証済みの修正をファイルごとにまとめます。各ファイルについて（ファイルごとに独立して処理します）：

   • ファイル内の修正を行番号の降順で並べます（下から上へ処理すると行番号のずれを防げます）
   • Edit ツールを使用して、このファイルの修正をすべて適用します
   • 変更したファイルに対して lint／型チェックを実行します
   • 成功した場合 → git add {file}（状態：保持）
   • 失敗した場合 → git checkout -- {file}（状態：破棄）。破棄した修正を記録します
   • 修正ごとに次を記録します：ファイル、削除した行、カテゴリ、検出 ID、状態（保持／破棄）

   lint／型チェックのコマンドが検出されない場合：すべての修正を適用し、警告を出してファイルごとの検証を省略し、変更したファイルをすべて git add します。

5. コミットを作成する（保持した修正のみ）：

   • 保持したファイルはすべて、ステップ 4 で git add によりステージされています
   • 保持したファイルが 0 件（すべて破棄）の場合：コミットを省略し、失敗をすべて報告します
   • コミットメッセージの形式：

     chore: automated tech debt cleanup
     
     Removed {N} auto-fixable findings from codebase audit:
     - {count} unused imports
     - {count} dead functions
     - {count} commented-out code blocks
     - {count} unsupported aliases
     
     Source: docs/project/codebase_audit.md
     Confidence threshold: >=90%
     

6. 監査レポートを更新する：

   • docs/project/codebase_audit.md に「Last Cleanup」セクションを追加します：

     ## Last Automated Cleanup
     **Date:** YYYY-MM-DD
     **Findings fixed:** N of M auto-fixable
     **Skipped:** K (confidence <90% or verification failed)
     **Build check:** PASSED / SKIPPED
     

出力形式

verdict: CLEANED | NOTHING_TO_CLEAN | ALL_DISCARDED
stats:
  total_findings: {from audit}
  auto_fixable: {filtered count}
  kept: {files that passed lint/typecheck}
  discarded: {files that failed lint/typecheck}
  skipped: {confidence <90 or stale}
fixes:
  - file: "src/utils/helpers.ts"
    line: 45
    category: "unused_function"
    removed: "formatDate()"
    finding_id: "MNT-DC-003"
    status: "keep"
  - file: "src/api/v1/auth.ts"
    line: 12
    category: "unsupported_alias"
    removed: "export { newAuth as oldAuth }"
    finding_id: "MNT-DC-007"
    status: "discard"
    discard_reason: "typecheck failed: Type error in auth.ts:15"
commit_sha: "abc1234" | null

重要なルール

• 安全を最優先： 確信度が90%未満の場合は、決して修正しないでください。判断に迷う場合は、スキップしてください。
• 下から上へ編集： 行番号のずれを避けるため、必ずファイルの下から上へ修正を適用してください。
• ファイルごとに維持／破棄： ファイルのリンターまたは型チェッカーが失敗した場合は、そのファイルのみを元に戻し（git checkout -- {file}）、ほかの成功したファイルは維持してください。
• ビジネスロジックには手を加えない： 関数本体、条件分岐、制御フローは決して変更しないでください。
• 明示的にステージング： ファイル名を指定してファイルをステージングしてください。git add . や git add -A は決して使用しないでください。
• 冪等性： 監査レポートに変更がない場合、2回実行しても変更が発生しないようにしてください。
• Git を考慮： 追跡対象のファイルのみを操作してください。未追跡ファイルや無視対象のファイルはスキップしてください。
• 対象外： 生成コード、ベンダーディレクトリ、圧縮ファイル、テスト用フィクスチャはスキップしてください。

実行時サマリー成果物

必ず読み込む： references/quality_summary_contract.md、references/quality_worker_runtime_contract.md

実行時プロファイル：

• family: quality-worker
• worker: ln-512
• summary kind: quality-worker
• コーディネーターが使用するペイロードフィールド：worker、status、verdict、issues、warnings、artifact_path

呼び出しルール：

• 単独実行：runId と summaryArtifactPath を省略します
• 管理対象の実行：runId と正確な summaryArtifactPath の両方を渡します
• 最終結果を返す前に、必ず検証済みのサマリーを書き込みます

完了の定義

• 監査レポートを読み込み、解析した
• 検出結果を自動修正可能なカテゴリに絞り込んだ
• 各検出結果を確信度90%以上で確認した
• ファイルごとに下から上へ修正を適用した
• ビルドの整合性を検証した（リンター＋型チェック）、または警告付きでスキップした
• 構造化されたメッセージを付けて単一のコミットを作成した（またはビルド失敗時にすべて元に戻した）
• 「Last Automated Cleanup」セクションで監査レポートを更新した
• YAML 出力を呼び出し元に返した

参照ファイル

• クリーンコードチェックリスト： references/clean_code_checklist.md
• 監査出力スキーマ： references/audit_output_schema.md
• 監査レポートテンプレート： references/templates/codebase_audit_template.md

---

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