argent-react-native-app-workflow

物理 iPhone（kind: "device"）：Metro のデバッグツールとプロファイリングツールでは使用できません。シミュレーターを使用してください。

1. React Native アプリの起動

1.1 設定の確認（必須：最初に実行）

コマンドを実行する前に、argent-environment-inspector サブエージェントの結果から、プロジェクトのビルドおよび実行設定を確認してください。

カスタムスクリプトやワークフローを確認せずに、npx react-native start や npx react-native run-ios をデフォルトとして使用しないでください。

手動で確認する場合（エージェントもツールも利用できない場合）：package.json のスクリプトをすべて確認し、start:local、start:dev、ios、build:ios、フレーバーなどのカスタムスクリプトを探してください。カスタムスクリプトをデフォルトコマンドより優先してください。また、metro.config.js でデフォルト以外のポートや watchFolders が設定されていないか確認してください。iOS のビルドでは、.xcodeproj より .xcworkspace を優先して開いてください（CocoaPods によってワークスペースが生成されます）。

プロジェクトの構成が複雑な場合は、続行する前にユーザーに確認してください。

ワークフローを忘れずに：プロジェクトのビルド／実行ワークフローを確認したら、毎回再確認せずに済むよう、プロジェクトのメモリーに保存してください。

起動前のチェックリスト：

• node_modules が存在する（存在しない場合：npm install または yarn）
• iOS の場合：ios/Podfile が存在する。ios/Pods がない、または古い場合は、cd ios && pod install && cd .. を実行する
• Metro がデフォルトポートで競合していない（1.2 を参照）

1.2 Metro の起動

1. 設定で確認したポートですでに Metro が実行中か確認し、実行中の場合は別のサーバーを起動しないでください。2.1 を参照してください。

2. プロジェクトにカスタムの起動スクリプトがある場合は、それを使用してください（例：npm run start:local、yarn start:dev）。カスタムスクリプトが定義されていない場合は、デフォルトコマンドを使用してください。

   npx react-native start
   

   任意：キャッシュに問題があると思われる場合は、npx react-native start --reset-cache を実行してください。

3. Metro の準備完了を確認する：debugger-status ツールを使用してください。このツールはエラーではなく status の結果を返します。status: "connected"、または reason: "no_app_connected" を伴う status: "not_connected" は、どちらも Metro が起動していることを示します（アプリがまだ接続していないだけです）。reason: "metro_not_running" は Metro に接続できないことを示します。結果に記載された guidance に従ってください。

4. フレーバーやカスタム設定があるプロジェクト：プロジェクト固有の起動スクリプトがある場合はそれを使用し（例：npm run start:local）、アプリを実行する前に Metro を起動してください。

1.3 アプリの実行

Metro は最初のターミナルで起動したままにして、別のターミナルで実行してください。

プロジェクトにカスタムのビルド／実行スクリプトがある場合は、それを使用してください（例：npm run ios、npm run android、yarn ios:debug）。カスタムスクリプトが定義されていない場合に限り、以下のデフォルトを使用してください。

対象デバイスを明示的に指定してください：list-devices から対象を特定します（<device_selection_rule> を参照）。

npx react-native run-ios --simulator="<name>"        # iOS (or --udid <UDID>)
npx react-native run-android --deviceId=<adb-serial> # Android

Android のみ：インストール後、adb -s <serial> reverse tcp:8081 tcp:8081 を実行して、エミュレーター／デバイスがホスト上の Metro に接続できるようにしてください。デバイスの再起動後、または adb の接続が切れた後は、再度実行してください。

エージェントのチェックリスト：

• Metro がすでに起動しており、「ready」と表示されている
• コマンドをプロジェクトのルートから実行している
• デバイスがまだ起動していない場合：iOS の udid または Android の avdName を指定して boot-device を使用する。argent-ios-simulator-setup／argent-android-emulator-setup のスキルを参照する
• Android：adb -s <serial> reverse tcp:8081 tcp:8081 を実行済み

---

2. Metro の確認／デバッグ

2.1 Metro がすでに起動しているか確認する

Metro を起動する前に、「ポートがすでに使用されています」というエラーを避けてください。確認するデフォルトのポートは :8081 です。ドキュメントからポートを判断してください。

lsof -i :PORT

• 出力なし → ポートは空いています。Metro を安全に起動できます。
• PID を含む出力 → 別のプロセスがポートを使用しています。

debugger-status ツールを使って、そのポートのプロセスが実際に Metro サーバーかどうかを確認してください。このツールはエラーではなく、構造化された結果を返します。status: "connected" または reason: "no_app_connected" → プロセスは Metro です。lsof にリスナーが表示されているのに reason: "metro_not_running" → ポートは Metro ではない何かによって使用されています。結果の detail フィールドには、プロセスが返した内容が表示されます（Metro at port ... is not running (got: ...)）。この場合は、プロセスを終了してもよいかユーザーに確認してください。

Metro プロセスを終了するには、stop-metro ツールを使ってください（ユーザーの確認が必要です）。

2.2 正しいサーバー接続を確認する

• アプリは、実行中の Metro と同じホスト／ポートを指定する必要があります。 デフォルトは同じマシンのポート 8081 です。
• iOS シミュレーター： デフォルトで localhost を使用するため、同じマシン上の Metro には追加設定は不要です。

Metro に接続できることを確認する： debugger-status ツールを使ってください。reason: "metro_not_running" は、そのポートで Metro が応答しなかったことを意味します。Metro を起動してください（§2.1）。"no_app_connected" は、Metro は応答したものの、アプリがまだ接続されていないことを意味します（§2.3）。それ以外の理由の場合は、結果の guidance に従ってください（この結果だけでは Metro が起動している証拠にはなりません）。

2.3 アプリを再読み込みする（新しいバンドルを確実に読み込む）

コードまたは設定を変更した後は、アプリに新しいバンドルを読み込ませる必要があります。

方法	手順
再読み込みツール	debugger-reload-metro ツールを使います
アプリを再起動	restart-app ツールを使うか、シミュレーターでアプリを終了し、再度 npx react-native run-ios を実行します

エージェントのチェックリスト：

• Metro プロセスは 1 つだけ（ポートで重複していない）
• Metro の準備ができてからアプリを起動した
• 再読み込みが必要な場合：2.3 を参照する

---

3. ビルド／インストール／再試行（React Native と iOS ネイティブ）

3.1 ビルドに失敗した場合（例：xcodebuild の終了コード 65）

操作の順序（簡単なものから）：

1. ビルドフォルダーをクリーンアップしてから、ビルドコマンドを再試行します
2. キャッシュをクリアして依存関係を再インストールします：Metro のキャッシュをリセットし、watchman watch-del-all を実行し、node_modules とロックファイルを削除して、npm install を実行した後、cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update を実行します
3. CocoaPods の問題：pod deintegrate を実行してから、pod install --repo-update を実行します
4. Xcode で ios/*.xcworkspace を開き、Report ナビゲーターで詳細なエラーを確認します

3.2 ユーザーに確認するタイミング

ビルドまたは実行に 2～3 回失敗したら、作業を止めてユーザーに指示を求めてください。 必要な環境変数、Xcode のバージョン要件、カスタムビルド設定、モノレポ固有のセットアップ、または必要な外部サービスについて、ユーザーが把握している可能性があります。

プロジェクトの構成が複雑で、適切なビルド方法が明らかでない場合は、推測するのではなく、早めにユーザーに確認してください。

3.3 ビルドのワークフローを後で使えるように保存する

プロジェクトに適したビルド／実行のワークフローがわかったら、プロジェクトのメモリに保存してください。 Metro の起動コマンド、アプリのビルド／実行コマンド、必要な環境設定を記録します。

3.4 再インストールとリフレッシュの使い分け

状況	操作
JS/React のみを変更した場合	debugger-reload-metro ツールを使用します。再ビルドは不要です。
ネイティブコード、または pod install / プロジェクト設定を変更した場合	再ビルドします：npx react-native run-ios（Metro は起動したままでかまいません）。
node_modules または package.json を変更した場合	npm install を実行し、ネイティブ依存関係も変更した場合は cd ios && pod install を実行します。その後、再ビルドします。
.app パスからアプリを再インストールする必要がある場合	UDID、バンドル ID、.app パスを指定して reinstall-app ツールを使用します。
ネイティブビルドエラーが継続する場合	完全なクリーンアップと再インストールを行います（上記の手順 2）。

3.5 デバイスの制御

操作	ツール／コマンド
デバイスを一覧表示する	list-devices ツール（iOS + Android）
iOS シミュレーターを起動する	udid を指定して boot-device ツールを使用します。
Android エミュレーターを起動する	avdName を指定して boot-device ツールを使用します。
アプリを起動する	launch-app ツールを使用します（デバイス ID + バンドル ID／パッケージ名を渡します）。
アプリを再起動する	restart-app ツールを使用します（デバイス ID + バンドル ID／パッケージ名を渡します）。
URL／ディープリンクを開く	open-url ツールを使用します（デバイス ID + URL を渡します）。
デバイスを回転する	rotate ツール
シミュレーターサーバーを停止する	stop-simulator-server ツール（iOS の UDID または Android のシリアル番号を指定。デバイスは 1 台）
すべてのシミュレーターサーバーを停止する	stop-all-simulator-servers ツール：devices: [...] を渡すと、このセッションのデバイスに対象を限定して終了できます（対象を指定しない呼び出しでは他のエージェントのデバイスも終了するため、マシン全体をクリーンアップする場合にのみ使用してください）。

シミュレーターのセットアップワークフロー全体については、argent-ios-simulator-setup スキルを参照してください。

---

4. アプリの実行時の問題

4.1 確認する場所

問題の種類	ツール／確認する場所
JavaScript のエラー／ログ	debugger-log-registry を使って概要とログファイルのパスを取得し、その後 Grep で検索します。status: "not_connected" が返された場合、ログファイルは返されません。まず guidance に従って再接続してください。
React コンポーネントの階層	テキスト形式のツリーには debugger-component-tree ツールを、特定の論理ピクセル座標（正規化された 0～1 の値ではありません）には debugger-inspect-element を使います。
アプリの視覚的な状態	screenshot ツールを使って現在の画面をキャプチャします。ただし、実際のナビゲーションや対象の特定には describe または debugger-component-tree を優先してください。権限プロンプトやシステムが所有するモーダルオーバーレイを確実に確認できない場合は、screenshot を使ってください。
アプリ内での JS の評価	debugger-evaluate ツールを使って、アプリのランタイムで JavaScript を実行します。
ネイティブクラッシュ／ネイティブスタック	npx react-native log-ios または iOS Simulator：Debug → Open System Log。
ビルド／ランタイムの設定	metro.config.js、babel.config.js、package.json のスクリプト、ios/Podfile。

コンポーネントの検査、コンソールログ、JS の評価など、包括的な Metro のデバッグワークフローについては、argent-metro-debugger スキルを参照してください。

4.2 JS コンソールログ（ログレジストリ）

ログは、ディスク上の ~/.argent/tmp/ にあるフラットなログファイルに書き込まれます。ログをインラインで読み込む代わりに、log-registry → grep のパターンを使ってください。

ワークフロー全体、フラットエントリーの形式、grep の例については、argent-metro-debugger スキルの §5 を参照してください。

4.3 React Native アプリで、デフォルトで DevMenu を使おうとしないでください。

代わりに argent ツールを使ってください。

---

5. アプリのテスト

argent-environment-inspector の結果でテストコマンドを確認してください。自動スクリーンショット検証を使ったインタラクティブな UI テストには、argent-test-ui-flow スキルを使ってください。

• ユニットテスト：package.json で Jest（"test": "jest"、jest の設定）を確認します。実行するには、npm test または yarn test を使います。
• E2E：Detox（.detoxrc.js など）またはその他の E2E 設定を確認します。依存関係：detox、detox-cli、iOS では多くの場合 applesimutils も必要です。
• 目に見える UI の変更：手動 QA には argent-test-ui-flow を使います。screenshot-diff のルールとパラメーターについては、argent-screenshot-diff スキルに従ってください。安定した変更前後のスクリーンショットによって、ピクセル上で意味のある証拠を追加できる場合に使用してください。
• UI フローテスト：自動スクリーンショット検証を使ったインタラクティブな UI テストについては、argent-test-ui-flow スキルを参照してください。

5.2 テストの実行（一般的な手順）

ユーザーの意図が曖昧な場合（既存のテストの実行、新しいテストの作成、カバレッジ不足の確認など）は、作業を進める前に確認してください。

• Jest：npm test または npx jest。
• Detox（例）：
  • ビルド：detox build --configuration ios.sim.release（または debug）。
  • 実行：detox test --configuration ios.sim.release。
  • シミュレーターが起動しており、ほかのプロセスで使用されていないことを確認してください。

5.3 エージェントのテストチェックリスト

• package.json とテスト設定（Jest、Detox など）を読みます。
• E2E の場合は、シミュレーター／デバイスとビルド設定を確認します。
• 不明な場合は、既存のワークフローを使うか、新しいテストを作成するか確認します。

---

クイックリファレンス：ツールとコマンド

目的	ツール／コマンド
ポート 8081 を確認する	lsof -i :8081
Metro を停止する	stop-metro ツール
Metro を起動する	npx react-native start
Metro を起動する（キャッシュをリセット）	npx react-native start --reset-cache
iOS アプリを実行する	npx react-native run-ios
Android アプリを実行する	npx react-native run-android
デバイス一覧を表示する	list-devices ツール（iOS + Android）
デバイスを起動する	boot-device ツール（iOS の場合は udid、Android の場合は avdName を渡します）
スクリーンショットを撮る	screenshot ツール
表示中の UI の変更を比較する	screenshot-diff ツール。ベースライン／現在のキャプチャの選択については、argent-screenshot-diff スキルに従ってください。
画面を説明する（a11y ツリー）	通常のアプリ画面とアプリ内モーダルには describe ツールを使用します。権限／システムのオーバーレイが安定して公開されない場合に限り、screenshot を使用してください。
JS コンソールログを読む	debugger-log-registry ツール
JS バンドルを再読み込みする	debugger-reload-metro ツール
Metro の状態を確認する	debugger-status ツール
React コンポーネントツリーを調べる	debugger-component-tree ツール
アプリ内で JS を実行する	debugger-evaluate ツール
iOS ネイティブログ	npx react-native log-ios
Android ネイティブログ	npx react-native log-android または adb -s <serial> logcat
クリーンアップして再インストールする（最終手段）	§3.1 の手順 3 を参照

---

関連スキル

スキル	使用する場面
argent-ios-simulator-setup	iOS シミュレーターの初回起動と接続の設定
argent-android-emulator-setup	Android エミュレーターの初回起動と接続の設定
argent-device-interact	シミュレーター／エミュレーターでのタップ、スワイプ、文字入力、ハードウェアボタン、ジェスチャー
argent-metro-debugger	JS ランタイムの CDP デバッグ（iOS／Android の Metro。移植された 4 つのツールは Chromium／CDP アプリも操作可能）：コンポーネントの調査、コンソールログ、JS の評価
argent-react-native-profiler	パフォーマンスのプロファイリング、再レンダリングの問題や CPU のボトルネックの特定
argent-test-ui-flow	各操作後にスクリーンショットを自動検証する、対話型 UI テスト

テストを実行する前にユーザーに確認してください。どのテストスイート（ユニット、E2E、または両方）を使うか、既存の CI コマンドを使用するか、既存のテストを実行するか、新しいテストを書くか、それとも自分でテストケースを調査するかを確認してください。