argent-react-native-profiler

このスキルは argent-react-native-optimization を補完するものであり、置き換えるものではありません。

実機の iPhone：サポート対象外です。react-profiler-* は kind: "device" を拒否します。シミュレーターでプロファイリングしてください。

2. ツールの概要

React Profiler（Hermes／React のコミット）

ツール	目的
react-profiler-start	CPU サンプリングを開始し、React のコミットキャプチャーフックを挿入します。オプション：sample_interval_us（デフォルトは 100）。
react-profiler-stop	記録を停止し、cpuProfile と commitTree をセッションに保存します。
react-profiler-status	フローの途中で中断された場合にのみ呼び出してください。それ以外の状況では呼び出さないでください（デバッガーの切断、Metro の再読み込み、一時停止、サブエージェントへの引き継ぎ、少しでも不確かな場合）。session_status: "active" | "taken_over" | "stopped" | "no_react_runtime" を返します。副作用はありません。
react-profiler-analyze	パイプラインを実行し、CPU 情報を付加したホットコミットを totalRenderMs の降順で並べたレポートを生成します。生データをディスクに保存します。
react-profiler-component-source	AST 検索：コンポーネントのファイル、行番号、メモ化の状態、およびソースの 50 行分を表示します。
react-profiler-renders	ライブ Fiber ウォーク：コンポーネントごとのレンダー回数と所要時間を表示します（プロファイリングセッションは不要）。
react-profiler-fiber-tree	ライブ Fiber ウォーク：コンポーネント階層全体を JSON として表示します。

詳細調査用クエリツール（analyze の実行後に呼び出します）

ツール	目的
profiler-cpu-query	CPU の詳細調査：上位関数、時間範囲を指定した CPU 情報、コールツリー、コンポーネントごとの CPU。
profiler-commit-query	コミットの詳細調査：コンポーネント、時間範囲、コミットインデックス、またはカスケードツリーで検索します。
profiler-stack-query	iOS Instruments の詳細調査：ハング時のスタック、関数の呼び出し元、スレッドの内訳、リークの詳細。
profiler-combined-report	React Profiler とネイティブプロファイラーを並行して実行した場合の相関レポート。
profiler-load	過去のプロファイリングセッションをディスクから一覧表示して再読み込みし、クエリツールで再調査します。

ネイティブのプロファイリング（CPU のホットスポット、UI のハング、メモリーリーク）については、argent-native-profiler スキルを参照してください。

---

3. エージェントの動作ガイドライン

プロファイリングのワークフロー全体を通して、以下のルールに従ってください。

• react-profiler-start と native-profiler-start を並行して開始します（1つのメッセージで2つのツール呼び出し）。どちらにも device_id が必要です。後でデータを関連付けられるよう、両方に同じ UDID を使用してください。こうすることで、最も広範囲をカバーできます。
• ユーザーがネイティブプロファイリングのみを希望する場合は、argent-native-profiler スキルのワークフローを使用します。このセッションではネイティブプロファイリングを希望しないとユーザーがすでに明示している場合に限り、native-profiler-start を省略してください。

分析後：次のステップを尋ねる

分析レポートを提示した後は、必ず次に何をしたいかをユーザーに尋ねてください。次の選択肢を提示します。

1. さらに調査する：クエリツール（CPU コールツリー、コミットのカスケード、ハング時のスタックなど）を使って特定の所見を掘り下げ、変更を加える前に根本原因を確実に特定します。
2. 修正を実装する：現在の所見に基づいて変更を適用し、その後、再度プロファイリングを行って指標が変化したか（改善、悪化、または横ばい）を測定します。
3. 今回はここまでにする：レポートをそのまま受け入れます。

レポートの後、何も言わずに先へ進んではいけません。レポートは出発点であり、終着点ではありません。クエリツールを使えば、レポートで指摘された内容をさらに詳しく調査できます。

調査中：クエリツールを積極的に使う

調査を掘り下げる際は、見つかった内容に基づいてクエリツールを連鎖的に呼び出してください。

• 負荷の高いコミットが見つかった場合 → profiler-commit-query の mode=by_index で全コンポーネントを確認 → 最も遅いコンポーネントに対して profiler-cpu-query の mode=component_cpu を実行 → 負荷の高い関数に対して profiler-cpu-query の mode=call_tree を実行 → ソースファイルを読み、修正案を提示します。
• メモリリークが見つかった場合 → profiler-stack-query の mode=leak_stacks で原因となっているモジュールを特定 → 対応可能な場合はネイティブソースを読みます。
• ネイティブのハングが見つかった場合 → profiler-stack-query の mode=hang_stacks でネイティブのコールチェーンを取得 → React のコミットタイミングと関連付けます。

修正後：必ず再度プロファイリングする

修正を適用した場合は、必ず同じシナリオを再度プロファイリングしてください。修正前後の指標（コミット時間、CPU 時間、レンダー回数）を比較し、対象の指標が改善したか、横ばいだったか、悪化したかを正直に報告してください。_ほかの_指標が悪化していないかも報告します。元のデータを参照する必要がある場合は、profiler-load を使って修正前のセッションを再読み込みしてください。修正による改善が見られなかった場合や、リグレッションが発生した場合は、そのことを明示し、アプローチを見直してください。

再現可能なプロファイリングには E2E テストを使う

プロファイリングに特定の操作手順（リストのスクロール、画面の移動、アニメーションの実行など）が必要な場合は、最初のプロファイリングを実行する前に、argent-create-e2e スキルを使ってその操作を E2E テストとして記録してください。その後の実行では毎回、同じ E2E テストを再生します。これにより操作のばらつきによる交絡を排除し、修正前後を意味のある形で比較できます。特に次の場合に重要です。

• 修正を適用した後、再度プロファイリングを行う場合（ステップ 8）。
• ユーザーから複数のプロファイリングセッションを比較するよう求められた場合。
• 操作手順が 2～3 ステップを超える場合。

---

4. 標準的なプロファイリングのワークフロー

すべてのステップを順番どおりに完了し、途中で中断しないでください。

Step 1: プロファイリングを開始する

セッションの開始時に、前述の react-native プロファイラーと ios-native プロファイラーの選択に注意し、ツールを開始してください。応答から startedAtEpochMs を保存してください。アノテーションのオフセットを計算する際に必要になります。このセッションで以降に行うすべてのプロファイラー／クエリ呼び出しでは、同じ device_id を使用する必要があります。開始する前に、ユーザーと簡潔な成功基準を定めてください。最も重要な指標（例：totalRenderMs、特定のコミットの所要時間、コンポーネントのレンダー回数）と、意味のあるしきい値を決めます。これにより、後の評価の基準を明確にできます。成功した場合：

• ユーザーからプロファイリングを依頼された場合は、argent-device-interact スキルで説明されているツールを使って、自分でプロファイリングする方法を判断します。
• ユーザーが自分で操作を行うと述べている場合は、行う操作（例：「リストをスクロールする」「タブを切り替える」）を提案し、返答を待ちます。 別のエージェントが所有する既存のプロファイリングセッションについて情報を受け取った場合：
• セッションが「stale」とマークされている場合は、ユーザーに許可を求めずに引き継いでもかまいません。
• セッションが「stale」ではない場合は、操作して別のセッションを終了する前に、いったん止まり、どうすべきかユーザーに確認してください。状況も説明します。

すべての操作にアノテーションを付ける

gesture-tap または gesture-swipe の呼び出しごとに、返された timestampMs を使ってアノテーションを記録してください。offsetMs = timestampMs - startedAtEpochMs を計算します。主要な操作だけでなく、戻るためのスワイプも含め、すべての操作について記録してください。収集したアノテーションはすべて、Step 3 で react-profiler-analyze に渡します。

Step 2: 停止してデータを収集する

react-profiler-stop と native-profiler-stop を並行して呼び出してください。Step 1 で native-profiler-stop を開始していない場合に限り、省略できます。 duration_ms と fiber_renders_captured を確認してください。 fiber_renders_captured: 0 の場合は、React のコミットデータが欠落している可能性があることをユーザーに警告してください。

Step 3: 分析する

port、device_id、project_root、platform、rn_version を指定して react-profiler-analyze を呼び出してください。レポートには reactCompilerEnabled、strictModeEnabled、buildMode などのメタデータが含まれます。返された Markdown レポートでこれらを確認してください。

gesture-tap／gesture-swipe を使って操作を行った場合は、各操作の実行時点を示すために annotations を渡してください。各アノテーションの offsetMs は、tapTimestampMs - startedAtEpochMs で計算する必要があります。tapTimestampMs は gesture-tap／gesture-swipe ツールが返した timestampMs、startedAtEpochMs は react-profiler-start が返した値です。この計算に Date.now() は使用せず、ツールの戻り値に含まれるサーバー側のタイムスタンプだけを使用してください。

デュアルプロファイリングを行った場合は、native-profiler-analyze も呼び出し、その後、相互相関を確認するために必ず profiler-combined-report を呼び出してください。両方のプロファイラーを実行した場合、この手順を省略しないでください。統合レポートでは、個別のレポートでは見つからない相関が明らかになります。

分析レポートには、コミットごとの CPU ホットスポットが含まれます。各 React の低速なコミット中に実行された JS 関数が正確に示されます。生データは後で再読み込みできるよう、自動的にディスクに保存されます。

Step 4: 結果を評価する

結果からアプリケーションの問題を適切に把握できているか分析してください。改善の余地が必ずあると決めつけず、react-native の仕組みを踏まえて、結果を論理的に検証してください。率直なフィードバックを行い、必要であればアプローチを変更できるようにしてください。

Step 5: 調査結果を提示し、次のステップを尋ねる

主な調査結果を簡潔にまとめ、改善の可能性があるか、さらに操作を行うとパフォーマンスにどのような影響があるかを示してください。その後、「分析後」のガイドラインに従い、さらに調査するか、修正を実装するか（可能な場合）、それとも終了するかを尋ねてください。

ステップ 6：詳細調査（反復）

レポートの調査結果をもとに、クエリツールを使ってさらに深く調査します。

• 遅いコンポーネントはありますか？ -> profiler-cpu-query mode=component_cpu component_name=AppNavigator：そのコンポーネントのコミット中に実行された JS 関数を表示します。
• 呼び出しツリーを確認しますか？ -> profiler-cpu-query mode=call_tree function_name=expensiveFunction：呼び出し元と呼び出し先を表示します。
• 特定の時間帯に何が起きましたか？ -> profiler-commit-query mode=by_time_range：指定した範囲のすべてのコミットを一覧表示します。
• コミットの詳細を確認しますか？ -> profiler-commit-query mode=by_index commit_index=38：すべてのコンポーネント、props の変更、親からのカスケードを表示します。
• どのコンポーネントが別のコンポーネントをトリガーしましたか？ -> profiler-commit-query mode=cascade_tree：親子のカスケードを視覚的に表示します。
• iOS のハングに関する詳細を確認しますか？ -> profiler-stack-query mode=hang_stacks：ハング中のネイティブのコールスタックを表示します。

根本原因となる関数とファイルを特定するまで、必要に応じて繰り返します。適切な評価についてはステップ 4 を参照してください。調査を一巡するたびに、さらに調査を続けるか、修正に進むかをユーザーに尋ねてください。

ステップ 7：以前のセッションを再読み込みする

複数のシナリオをプロファイリングしていて、以前のデータを再確認する必要がある場合：

1. profiler-load mode=list を呼び出して、保存済みセッションとタイムスタンプの一覧を確認します（一覧には、適切なセッションを識別しやすいよう、Runtime／Device／Metro bundle の列も表示されるようになりました）。
2. profiler-load mode=load_react session_id=<timestamp> device_id=<UDID> を呼び出して、React データを再読み込みします。device_id によって、再読み込み先は port:device_id のキャッシュスロットに限定されます。
3. profiler-load mode=load_native session_id=<timestamp> device_id=<UDID> を呼び出して、ネイティブプロファイラーのデータを再読み込みします。
4. これ以降、クエリツールは再読み込みしたセッションデータを対象に動作します。キャッシュを正しく参照できるよう、読み込み時と同じ device_id を渡してください。

これは修正前後を比較する際に便利です。プロファイリングを行い、修正してから再度プロファイリングし、元のセッションを再読み込みして指標を並べて比較できます。

ステップ 8：修正を適用して再プロファイリングする

修正を行う場合は、react-profiler-component-source または Read ツールを使って、特定したボトルネックのソースコードを読みます。修正を適用してから、再度プロファイリングします（ステップ 1 → ユーザー操作 → ステップ 2 → ステップ 3 → ステップ 4）。対象の指標が改善したか、横ばいだったか、悪化したかを報告してください。また、修正によってほかの指標にリグレッションが生じていないかも確認します（例：レンダー回数は減ったものの CPU 時間が増えた、または別のコンポーネントの再レンダー回数が増えた）。修正による全体的なメリットがない、または許容できないトレードオフが生じた場合は、変更を取り消して再検討してください。

ヒント： 操作手順が e2e テストとして記録されている場合（上記の「Use e2e tests for reproducible profiling」を参照）、手動で手順を繰り返す代わりに e2e-execute で再生してください。これにより、比較時の操作条件を同一にできます。再生中に e2e テストが失敗した場合（例：UI の修正によってレイアウトが変わった場合）、プロファイリングのサイクルを再試行する前に、argent-create-e2e のリプレイ失敗の診断に従って e2e テストを修復してください。

ユーザーが変更を望まないと述べた場合は、プロファイリングレポートを提示し、修正は行わず、ユーザーに修正を提案してください。

React Compiler のルール： 分析レポートで React Compiler が有効だと示されている場合は、そのコンポーネントでコンパイラーの最適化が適用されていないことを確認しない限り、useCallback／useMemo／React.memo を提案しないでください（そのコンポーネントに useMemoCache がないことを react-profiler-fiber-tree で確認してください）。

---

5. 重要な注意事項

• 開発モードによる増加：buildMode: "dev" のレンダリングは、本番環境より約3倍遅くなります。normalizedRenderCount が大きいものを優先してください。この値は本番環境にも適用できます。
• 修正後に再実行：変更後は必ず再度プロファイリングしてください。指標が改善したか、悪化したか、変化しなかったかを正直に報告し、改善したと決めつけないでください。
• excluded は参考情報です：animatedSubtrees と recyclerChildren のコンポーネントは、設計上再レンダリングされます。
• Strict Mode：レンダリングを2回実行します。検出された場合、パイプラインが normalizedRenderCount を自動的に半分にします。
• デバッガーの接続：中断されると、開始済みのプロファイリングも終了します。復旧を試みる前に react-profiler-status を呼び出してください。セッションが active、taken_over、stopped、no_react_runtime のどの状態かがわかるため、最初に停止、再起動、再接続のどれを行うべきか判断できます。
• 注意すべき交絡要因：
  • 実行ごとにライブ API データが異なる場合（ペイロードのサイズやコンテンツ数の違いなど）、修正とは無関係にレンダリング回数や時間が変動します。データに依存するコンポーネントにばらつきが見られる場合は、その旨を記録してください。
  • プロファイラーのオーバーヘッドにより、CPU 測定値が増加します。iOS Instruments で JSLexer、JSONEmitter、または Hermes の内部処理が JS スレッドの大半を占めている場合、それはアプリの処理ではなく、プロファイラーの計測コストを反映しています。これらの項目は割り引いて評価してください。
  • 実行結果を完全に再現することはできません。コミット時間の小さな変動（約10～15％未満）はノイズである可能性があります。一貫して同じ方向に変化している場合のみ、シグナルとして扱ってください。

単独で使用できる診断ツール（ライブレンダリング統計、fiber ツリー、CPU サマリー）については、references/diagnostic-tools.md を参照してください。