rsdoctor-analysis

Rsdoctor 分析アシスタントスキル

実在する rsdoctor-data.json のパスが確認できた後に限り、グローバルにインストールされた @rsdoctor/agent-cli の rsdoctor-agent CLI を使用してください。ユーザーからインストールや設定の準備を明示的に依頼されない限り、分析は読み取り専用で行ってください。

回答の順序（必須）：優先度の高い問題 -> 解決策の提案 -> 参考：参照チェーンに関する追加確認の選択肢 -> 次に詳しく調査する問題カテゴリ（コマンドではありません）。

基本的なワークフロー

1. 新たな作業を行う前に、現在のセッションの結果と有効な .rsdoctor-analysis-cache.json のエントリを再利用します。
2. rsdoctor-data.json をすばやく見つけます。ユーザーが指定したパス、次に dist/rsdoctor-data.json、output/rsdoctor-data.json、static/rsdoctor-data.json、.rsdoctor/rsdoctor-data.json、その後 node_modules と .git を除外した範囲内で rg --files による検索を1回行います。manifest.json はインデックスとしてのみ扱います。
3. データが存在する場合は、プラグインのバージョン確認、設定、ビルド生成に関するロジックをすべて省略します。有用な場合はキャッシュを更新します。
4. データがない場合は、分析を中止します。rsdoctor-agent の分析コマンドと Analysis Gate は実行しないでください。データのパスを尋ねるか、セットアップや生成が必要な場合に限り、以下の Generation Gate を実行します。
5. 実在するデータファイルが確認できた後、最初の rsdoctor-agent データ取得コマンドを実行する前に、Analysis Gate を最大1回実行します。グローバルな @rsdoctor/agent-cli を npm view @rsdoctor/agent-cli version と rsdoctor-agent --version で確認し、未インストールまたは旧バージョンの場合、バージョン関連のエラーが発生した場合、あるいはユーザーから更新を依頼された場合に限り、最新バージョンをインストールします。
6. 分析の前に rsdoctor-agent compilers list --data-file <path> を実行してコンパイラーを確認し、以下のコンパイラー選択ルールに従います。
7. 選択した各コンパイラーについて、まず Default Evidence Set のみを取得します。可能な場合は独立した取得処理を並列で実行します。証拠を取得する際のすべてのコマンドに、そのコンパイラーの --compiler <name> を渡します。
8. 詳細調査コマンドや推奨事項を選択する前に、以下の ROI Triage Gate を実行します。測定された影響に基づいて問題カテゴリの優先順位を決め、その後、指定された回答順序に従って調査結果をまとめます。

パフォーマンスに関するルール：独立した確認は並列化し、キャッシュするのは派生した事実（dataFile、dataFileMtime、pluginName、pluginVersion、依存関係・設定・プラグインの変更時刻）のみとします。パスが見つからなくなった場合、変更時刻が変わった場合、ユーザーから更新を依頼された場合、またはキャッシュ値が無効になった場合は、キャッシュを無効化します。プラグインに関する推測的な確認によって、生成を開始してはいけません。こうした確認は、データファイルがないことを確認した後に限り使用します。

コンパイラーの選択

コンパイラーの確認は最初のデータクエリとして扱い、証拠取得の並列処理には含めません。

• レポートに名前付きコンパイラーが1つある場合は、分析全体でその正確な name を使用します。
• レポートに複数のコンパイラーがある場合は、ユーザーが指定した対象を正確なコンパイラー名に対応付けます。リクエストで client、server、worker などの対象が指定されていても、正確な名前と一致しない場合は、確認結果から一意に特定できる場合に限り対応付けます。対象が指定されていない場合、または一意に特定できない場合は、返された名前から選択するようユーザーに尋ねます。
• レガシーレポートで name: null のコンパイラーが1つ返された場合は、--compiler を省略します。
• 単一コンパイラーの分析では、Default Evidence Set とすべての追加クエリで、同じコンパイラーを選択し続けます。ユーザーからコンパイラー横断分析を明示的に依頼された場合は、上記のルールに従って依頼された各コンパイラー（または全コンパイラーの指定があれば、返されたすべてのコンパイラー）を選択し、それぞれの --compiler <name> を使って個別に証拠を取得してから、結果を明確にラベル付けして比較します。1回の処理内で異なるコンパイラーの結果を混在させてはいけません。
• 各処理でローカルの JSON 証拠を扱う場合、E1001/E1002 の概要を含め、compilers list が返す解決済みデータファイルのうち、選択したコンパイラーのエントリのみを読み取ります。コンパイラーごとの証拠として、最初に指定された集約ファイルやインデックスファイルを読み取ってはいけません。
• 証拠を取得する前に、選択したすべてのコンパイラーの available フィールドが true であることを確認します。いずれかが false の場合は、そのコンパイラーのデータファイルを復元または再生成するようユーザーに尋ねます。

ROI トリアージゲート

修正を提案する前に、現在のビルドを大まかなコスト区分に分類し、直感ではなくエビデンスに基づいて、最も ROI の高い施策を選んでください。このゲートは Rspack/Webpack プロジェクト全般を対象とします。ユーザーのプロジェクトのデータに現れていない限り、フレームワーク固有のランタイムレイヤーは使用しないでください。

コスト区分	エビデンスの参照元	最初の施策
アセット／メディア	assetsTop、assets media、chunkGraph.assets	大きなアセットを圧縮、変換、重複排除、サブセット化、または遅延読み込みする
大きなパッケージ／モジュール	packagesTop、モジュール／パッケージのサイズフィールド	重いパッケージを置き換える、ディープインポートを使う、重要度の低いコードを分割する、または直接依存関係の選択を見直す
重複／チャンク間コスト	E1001/E1002、packages duplicates、チャンク間のパッケージ概要	バージョンを重複排除する、パッケージ解決を調整する、または splitChunks／キャッシュグループを調整する
ツリーシェイキングの無駄	retainedModulesTop、保持された CJS／バレル／副作用のあるモジュール	CJS／バレルインポート、sideEffects 宣言、またはパッケージのエントリーポイントを修正する
ビルド時間のコスト	buildCost、ローダー／プラグイン／ディレクトリのコストデータ	ローダー／プラグイン、キャッシュ、ウォッチャー、またはソースマップ／開発設定を最適化する。ユーザーがビルドパフォーマンスについて尋ねた場合にのみ優先する

判断ルール：

• 推奨の優先順位が変わる場合は、まず測定された内訳を報告してください。
• 実用的な修正につながる区分のうち、最も大きなものから着手してください。ただし、より大きな問題が想定内または意図的に避けられないものでない限り、小さな問題を大きな問題より優先してはいけません。
• 発行元／参照チェーンの追跡は第 2 段階の作業として扱ってください。影響の大きい候補について所有者のエビデンスが必要な場合、またはユーザーが「なぜ」／「誰がこれをインポートしたのか」と尋ねた場合にのみ実行してください。
• 具体的なファイル、パッケージ、チャンク、サイズ、または依存関係のパスが必要な修正について、集約されたルールの出力だけを十分なエビデンスとして提示してはいけません。
• 最も大きな区分が構造上のもの、または意図的に必要なものである場合は、それが制約となっていることを伝え、影響の小さいソースコードの編集をでっち上げるのではなく、代わりに必要となる外部の変更を示してください。

生成ゲート

まず、プロジェクトのバンドラーを特定します。webpack の場合は、別途用意されている webpack 1.x generation guide に従ってください。以下の Rspack 2.x ゲートは適用しないでください。Rspack の場合は、package.json、ロックファイル、次にインストール済みパッケージのメタデータで @rsdoctor/core と @rsdoctor/rspack-plugin を確認します。pnpm why / npm ls はフォールバックとしてのみ使用します。依存関係の範囲からメジャーバージョンを推測せず、実際のバージョンを特定してください。選択したプラグインの peer dependency がインストール済みバンドラーを対象外としている場合は、そこで作業を中止してください。直接依存関係と、フレームワークが所有する推移的パッケージを介したアクティブなプラグイン登録は、分けて確認してください。@rsdoctor/core 1.x はカスタムルール用に存在する場合がありますが、ビルドプラグインを提供するとは限りません。

Rspack の場合は、次の正確な if/else 決定木を使用してください。分岐を統合しないでください。

if Rspack actively registers both @rsdoctor/core 2.x and @rsdoctor/rspack-plugin 1.x:
  stop and report mixed plugins; do not install or build
else if Rspack has @rsdoctor/core 2.x:
  use or register the v2 plugin; configure output.mode='brief' and include 'json' in output.options.type; build with RSDOCTOR=true only
else if @rsdoctor/rspack-plugin is installed but its version is unknown:
  resolve its version first; if still unknown, configure output.mode='brief' and include 'json' in output.options.type; build with RSDOCTOR=true only
else if an installed @rsdoctor/rspack-plugin 1.x version is >= 1.5.11:
  do not edit plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed
else if an installed @rsdoctor/rspack-plugin 1.x version is older:
  configure output.mode='brief' and include 'json' in output.options.type; build with RSDOCTOR=true only
else: # no build plugin installed
  choose a compatible Rspack plugin, then configure brief JSON output and build with RSDOCTOR=true only

プラグインを含まない Rspack 2.x プロジェクトでは、互換性のある @rsdoctor/core 2.x バージョンをインストールしてください。@rsdoctor/rspack-plugin はインストールしないでください。Rspack 1.x の場合は、互換性のある 1.x プラグインを使用してください。インストール済みのバージョンまたはバンドラーとの互換性を特定できない場合は、インストール前に作業を中止してください。パッケージのバージョンとアクティブな設定に矛盾があると思われる場合に限り、プラグインのインポートパスを確認してください。

Rspack のビルドでは、RSDOCTOR_OUTPUT=json を使用できるのは、バージョンが判明している 1.x プラグインの >= 1.5.11 の場合のみです。2.x、プラグインがない場合、バージョンが不明な場合、または古いバージョンの場合は使用できません。明示的な JSON 設定が必要な場合は、既存の簡易出力形式に 'json' を追加し、HTML を削除しないでください。通常のレポートを一時的に変更する場合は、データを生成した後、以前の出力設定に戻してください。

output: {
  mode: 'brief',
  options: {
    type: ['json'],
  },
}

エビデンスとコマンドの範囲

デフォルトのエビデンスセット：

Summary key	Evidence source	Bounds
buildCost	build summary	フィルタリングしたフィールドのみ
assetsTop	raw/gzip サイズによる上位アセット	固定の Top-N
packagesTop	gzip サイズによる上位パッケージ	固定の Top-N。packages list の全ページ取得は避ける
duplicatePackages	E1001 重複パッケージの概要	初回の概要のみ
crossChunkPackages	E1002 チャンク間の重複の概要	初回の概要のみ
retainedModulesTop	tree-shaking retained-modules --limit 10	フィルタリングしたフィールドのみ。--compact は指定しない

スコープのルール：

• バンドルデータへのアクセスには、rsdoctor-data.json が存在する場合に限り rsdoctor-agent を使用します。独立した取得は並列で行うことを優先し、--filter、ページネーション、--limit で出力を制限します。検出後は、そのエビデンス取得で選択したコンパイラーをすべての直接コマンドと query 呼び出しに --compiler <name> として渡します。検出された名前が null のレガシーレポートの場合のみ、省略します。
• デフォルトの分析は、デフォルトのエビデンスセットの範囲内に留めます。デフォルト以外の分析では、references/rsdoctor-data-types.md から必要最小限のフィールドを、references/common-analysis-patterns.md からパターンを選択します。
• チェーンの追跡、広範なコマンド、最適化の変更、splitChunks の実験、ビルドの再実行は、ユーザーの確認が必要な任意の追加調査として扱います。
• 重複パッケージとツリーシェイキングの問題については、まず問題を特定します。参照／インポートのチェーン追跡は、ユーザーの確認後にのみ行います。
• 副作用の調査には、狭い範囲の --filter を指定して tree-shaking retained-modules --emitted-only --category side-effects --limit 10 を優先します。
• 出力対象の保持モジュールには、tree-shaking retained-modules を使用し、--emitted-only、範囲を限定した --category、--sort gzipSize、--limit、狭い範囲の --filter を指定します。--compact は渡さないでください。
• tree-shaking summary は、フィールドが不足している場合や集計コンテキストが必要な場合のフォールバックとしてのみ使用します。tree-shaking bailout-reasons は出力量が多いため、明示的に要求された場合にのみ実行し、対象の --modules（最大 100）を渡します。
• いずれかのコマンドが 5k トークン、500 KB の生出力、または数百行程度の文字起こしを超える場合は、広範な取得を中止し、対象を絞ったコンパクトなクエリに切り替えます。

出力と復旧

出力形式：

1. 現在のビルドで見つかった問題と推奨される修正：
   • 各問題とその修正案をまとめてください。
   • 具体的な根拠（サイズ／時間／件数／パス／ルールコード）と優先度を記載してください。
   • 重複パッケージとツリーシェイキングの問題については、「調査を続けるか、ここで止めるか」を簡潔に選択できるようにしてください。
2. さらに詳細な分析が必要かどうか：
   • 残っている問題のカテゴリのみを列挙し、コマンドは記載しないでください。

Top-N の分析情報には、表を優先してください：Name | Volume/Time | Count | Recommendation

復旧ルール：

• rsdoctor-data.json が見つからない場合：rsdoctor-agent を実行せず、データのパスを尋ねるか、Generation Gate を実行してから、セットアップが必要であれば該当するインストールリファレンスを使用してください。
• コマンドが見つからない場合：Analysis Gate を実行してから、rsdoctor-agent で再試行してください。
• query で不明なツールが報告された場合：list を実行してカタログにあるツール名を使用するか、直接の <group> <subcommand> モードに切り替えてください。
• COMPILER_REQUIRED：compilers list を実行し、上記のルールに従って要求されたコンパイラーを選択してから、各エビデンスパスを一貫して独自の --compiler を指定して再試行してください。
• COMPILER_NOT_FOUND：コンパイラーの一覧を更新し、返された正確な名前を使用してください。displayName から推測してはいけません。
• COMPILER_DATA_NOT_FOUND：選択したコンパイラーのデータファイルを復元または再生成するよう、ユーザーに依頼してください。
• JSON の読み取りエラー：ファイルパス、JSON の有効性、権限を確認してください。
• インストール、ビルド、バージョン確認、および rsdoctor-agent... コマンドは、必要なプロジェクト、依存関係、ネットワークへのアクセスがある場合に限り、ホストの許可されたコマンド環境でのみ実行してください。利用可能な環境にそのアクセス権がない場合は、サンドボックスや権限の境界を回避しようとせず、停止してユーザーに依頼してください。不足している権限またはアクセスを明確に示してください。Rsdoctor の依存関係をインストールする必要がある場合は、必要な依存関係と、ユーザーが実行するための適切なパッケージマネージャーコマンドを伝えてください。

リファレンス：コマンド／オプション references/command-map.md；インストール／設定／データの場所 references/install-rsdoctor.md、references/install-rsdoctor-rspack.md、references/install-rsdoctor-webpack.md、references/install-rsdoctor-common.md；生データのフィールド references/rsdoctor-data-types.md；一般的な分析パターン references/common-analysis-patterns.md。