ln-832-bundle-optimizer

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

ln-832-bundle-optimizer

タイプ： L3 ワーカー カテゴリ： 8XX 最適化

キープ／破棄の検証を用いて、JavaScript または TypeScript のバンドルサイズを削減します。JS/TS プロジェクトのみが対象です。

---

概要

項目	詳細
入力	JS/TS プロジェクトのパスと、任意の最適化範囲
出力	サイズを縮小したバンドルと、機械可読なモダナイゼーション概要
範囲	JS/TS のみ

---

ワークフロー

フェーズ： 事前チェック -> ベースライン -> 分析 -> 最適化ループ -> レポート

---

フェーズ 0：事前チェック

チェック	必須	未対応の場合のアクション
package.json が存在する	はい	最適化をブロック
ビルドコマンドを利用できる	はい	最適化をブロック
出力ディレクトリ（dist/ または build/）を検出できる	はい	ベースラインを確立するために一度ビルド
ワークスペースのベースラインが安全である	はい	管理された実行では、コーディネーターがすでに準備済みです。単独実行では、ロールバックできるようローカルで保護します

必ず読み込むこと： ビルドの検出については references/ci_tool_detection.md を読み込みます。 ツールポリシー：ホストの AGENTS.md にある MCP の設定に従います。ホストポリシーがない場合、または MCP の動作が不明確な場合に限り、references/mcp_tool_preferences.md と references/mcp_integration_patterns.md を読み込みます。

ホットスポットやクローングループによって最適化の対象選定が大きく改善される場合は、まず hex-graph を使用します。利用可能な場合は、ローカルコードや設定の読み取りにはまず hex-line を使用します。MCP が利用できない、未対応、またはインデックス化されていない場合は、組み込みの Read/Grep/Glob/Bash を使用して続行し、フォールバックを概要に記載します。

ランタイムの調整

管理された実行では、決定論的な runId と正確な summaryArtifactPath が ln-830 から渡されます。 単独実行も引き続きサポートされます。ランタイム引数が省略された場合は、返す前に単独実行スコープの成果物を生成します。

---

フェーズ 1：ベースラインの確立

1. Run the detected build command.
2. Measure total size of the output directory.
3. Record baseline bytes and per-chunk sizes.

指標	方法
合計サイズ	ソースマップを除く、すべてのバンドル出力ファイルの合計
チャンクごとのサイズ	個々の JS ファイルと CSS ファイルを測定
ソースマップの扱い	.map ファイルを除外

---

フェーズ 2：最適化の機会を分析

チェック	ツール	検出内容
未使用の依存関係	depcheck または同等のツール	どこからもインポートされていないパッケージ
バンドルの構成	バンドルアナライザー	サイズの大きな依存関係や重複
ツリーシェイキングの不足	手動スキャン	名前空間インポートやサイズの大きなエントリーポイント
コード分割の不足	ルート分析	遅延読み込みの候補

最適化カテゴリ：

カテゴリ	例	一般的な削減量
未使用の依存関係を削除	不要な依存関係	パッケージごとに 10-50KB
名前付きインポート	lodash-es の名前付きインポート	50-200KB
より軽量な代替手段	サイズの大きな日付／ユーティリティライブラリを置き換え	50-300KB
動的インポート	サイズの大きなコンポーネントを遅延読み込み	初期バンドルを縮小
CSS の最適化	未使用の CSS を削除し、圧縮	10-100KB

---

フェーズ 3：最適化ループ（キープ／破棄）

最適化の各サイクル：

FOR each optimization:
  1. APPLY the change
  2. BUILD
     IF build fails -> DISCARD and revert
  3. MEASURE new bundle size
  4. KEEP only if the bundle is smaller than the current baseline
  5. LOG the result

停止条件：

条件	アクション
すべての最適化を処理済み	停止して報告
破棄が 3 回連続	停滞とみなして停止
ビルドインフラストラクチャが壊れた	最後にキープした状態に戻して停止
バンドルがすでに目標を下回っている	停止して報告

最適化の順序：

1. 未使用の依存関係を削除
2. ツリーシェイキングとインポートを改善
3. サイズの大きなライブラリを置き換え
4. コード分割を導入
5. CSS を最適化

---

フェーズ 4：結果を報告する

フィールド	説明
project	プロジェクトのパス
baseline_bytes	元のバンドルサイズ
final_bytes	最終的なバンドルサイズ
reduction_bytes	削減されたバイト数
reduction_percent	削減率
optimizations_applied	適用した最適化の数
optimizations_discarded	数と理由
deps_removed[]	削除した依存関係
details[]	最適化ごとの削減量
artifact_path	書き込まれた場合の、永続的なワーカーレポートのパス

---

設定

Options:
  build_command: ""             # Auto-detect
  output_dir: ""                # Auto-detect
  run_depcheck: true
  run_bundle_analyzer: false
  remove_unused_deps: true
  fix_tree_shaking: true
  replace_heavy_libraries: true
  enable_code_splitting: true

---

エラー処理

エラー	原因	解決策
最適化後にビルドが失敗する	コードまたは設定の変更が無効	その最適化を元に戻します
サイズが削減されない	最適化の効果がない	破棄します
アナライザーを利用できない	ツールが見つからない	手動での確認を続行します

---

参考資料

• optimization_categories.md
• references/ci_tool_detection.md

---

ランタイムサマリーアーティファクト

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

modernization-worker のサマリーエンベロープを出力します。

管理モード：

• ln-830 が決定的な runId と正確な summaryArtifactPath を渡します
• サマリーを指定された summaryArtifactPath に書き込みます

スタンドアロンモード：

• runId と summaryArtifactPath を省略します
• .hex-skills/runtime-artifacts/runs/{run_id}/modernization-worker/ln-832--{identifier}.json に書き込みます

モニター（2.1.98+）： 維持／破棄ループ内で30秒を超えると予想されるビルドコマンドには、Monitor を使用します。フォールバック：Bash(run_in_background=true)。

完了の定義

• 実際のビルド出力からベースラインのバンドルサイズを確定している
• バンドル構成とプロジェクトでの使用状況から最適化の機会を分析している
• 各最適化について、維持／破棄の検証を行っている
• サイズを削減する最適化のみを維持している
• 最終レポートにバンドルの差分、破棄した試行、削除した依存関係を記録している
• modernization-worker のサマリーアーティファクトを、管理モードまたはスタンドアロンモードのパスに書き込んでいる

---

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