axiom-ios-build

iOS ビルド＆環境ルーター

アプリケーションコードのデバッグを始める前に、ビルド、環境、または Xcode 関連の問題には必ずこのスキルを使用してください。

使用するタイミング

次のような問題が発生した場合は、このルーターを使用してください。

• ビルドの失敗（BUILD FAILED、コンパイルエラー、リンカーエラー）
• テストのクラッシュまたはハング
• シミュレーターの問題（起動しない、デバイスエラー）
• Xcode の異常動作（古いビルド、ゾンビプロセス）
• 依存関係の競合（CocoaPods、SPM）
• ビルドパフォーマンスの問題（コンパイルが遅い）
• コードをデバッグする前の環境の問題

ルーティングロジック

このルーターは、問題に応じて専門スキルを呼び出します。

1. 環境を優先する問題 → xcode-debugging

該当条件：

• 明らかなコード上の原因がない BUILD FAILED
• クリーンなプロジェクトでテストがクラッシュする
• シミュレーターがハングする、または起動しない
• SPM の変更後に「No such module」が発生する
• ゾンビ xcodebuild プロセス
• 古いビルド（古いコードが引き続き実行される）
• クリーンビルドとインクリメンタルビルドで結果が異なる

最初に xcode-debugging を使う理由：不可解な問題の 90% はコードではなく環境に起因します。コードをデバッグする前に確認してください。

呼び出し方法：/skill axiom-xcode-debugging

---

2. ビルドの遅さ → build-performance

該当条件：

• コンパイルに時間がかかりすぎる
• 型チェックがボトルネックになっている
• ビルド時間を最適化したい
• Build Timeline に時間のかかるフェーズが表示される

呼び出し方法：/skill axiom-build-performance

---

3. SPM の依存関係の競合 → spm-conflict-resolver（エージェント）

該当条件：

• SPM の解決に失敗する
• パッケージの追加後に「No such module」が発生する
• 重複シンボルのリンカーエラー
• パッケージ間のバージョン競合
• Swift 6 のパッケージ互換性の問題
• Package.swift / Package.resolved の競合

spm-conflict-resolver を使う理由：Package.swift と Package.resolved を分析し、Swift Package Manager の競合を診断して解決する専門エージェントです。

呼び出し方法：spm-conflict-resolver エージェントを起動

---

4. セキュリティとプライバシーの監査 → security-privacy-scanner（エージェント）

該当条件：

• App Store への申請準備
• Privacy Manifest の要件（iOS 17+）
• コード内にハードコードされた認証情報
• 機密データの保存に関する懸念
• ATS 違反
• Required Reason API の宣言

security-privacy-scanner を使う理由：セキュリティの脆弱性とプライバシーコンプライアンス上の問題をスキャンする専門エージェントです。

呼び出し方法：security-privacy-scanner エージェントを起動するか、/axiom:audit security を実行

---

5. iOS 17→18 へのモダナイズ → modernization-helper（エージェント）

該当条件：

• ObservableObject を @Observable に移行する
• @StateObject を @State に更新する
• 最新の SwiftUI パターンを採用する
• 非推奨 API を整理する
• iOS 17+ への移行

modernization-helper を使う理由：レガシーパターンをスキャンし、コード例とともに移行方法を提示する専門エージェントです。

呼び出し方法：modernization-helper エージェントを起動するか、/axiom:audit modernization を実行

---

6. ビルド失敗の自動修正 → build-fixer（エージェント）

該当条件：

• 明確なエラー詳細がない BUILD FAILED
• ビルドが成功したり失敗したりする
• アプリはビルドされるが、古いコードが実行される
• 「Unable to boot simulator」エラー
• 環境を優先した診断を自動化したい

build-fixer を使う理由：コードを調査する前に、ゾンビプロセス、Derived Data、SPM キャッシュ、シミュレーターの状態を確認する自律型エージェントです。環境の問題の解決にかかる時間を 30 分以上短縮できます。

呼び出し方法：build-fixer エージェントを起動するか、/axiom:fix-build を実行

---

7. ビルドの遅さの最適化 → build-optimizer（エージェント）

該当条件：

• ビルドに時間がかかりすぎる
• 遅い型チェックを特定したい
• 負荷の高いビルドフェーズスクリプト
• 最適でないビルド設定
• 並列化できる箇所を見つけたい

build-optimizer を使う理由：Xcode プロジェクトをスキャンし、遅い型チェック、負荷の高いスクリプト、最適でない設定など、ビルドパフォーマンスを最適化できる箇所を見つけて、ビルド時間を 30〜50% 短縮します。

呼び出し方法：build-optimizer エージェントを起動するか、/axiom:optimize-build を実行

---

8. 一般的な依存関係の問題 → build-debugging

トリガー：

• CocoaPods の依存関係解決に失敗する
• 「Multiple commands produce」エラー
• フレームワークのバージョン不一致
• SPM 以外の依存関係グラフの競合

呼び出し：/skill axiom-build-debugging

---

9. TestFlight のクラッシュトリアージ → testflight-triage

トリガー：

• ベータテスターからクラッシュの報告があった
• Xcode Organizer にクラッシュレポートがある
• クラッシュログのシンボリケーションが行われていない
• スクリーンショット付きの TestFlight フィードバック
• アプリが強制終了されたが、クラッシュレポートがない

testflight-triage を使う理由：TestFlight のクラッシュ調査とベータフィードバックの確認を体系的に行うワークフローです。シンボリケーション、クラッシュの解釈、一般的なパターン、Claude を活用した分析を扱います。

呼び出し：/skill axiom-testflight-triage

---

10. App Store Connect のナビゲーション → app-store-connect-ref

トリガー：

• App Store Connect でクラッシュを見つける方法
• ASC のメトリクスダッシュボードのナビゲーション
• クラッシュのないユーザーの割合を理解する
• バージョン間でクラッシュ率を比較する
• ASC からクラッシュデータをエクスポートする
• クラッシュデータ用の App Store Connect API

app-store-connect-ref を使う理由：ASC のクラッシュ分析、メトリクスダッシュボード、データエクスポートのワークフローを参照するためのガイドです。

呼び出し：/skill axiom-app-store-connect-ref

---

11. クラッシュログ分析 → crash-analyzer（エージェント）

トリガー：

• 分析する .ips または .crash ファイルがある
• ユーザーがクラッシュレポートのテキストを貼り付けた
• クラッシュログをプログラムで解析する必要がある
• 例外の種類からクラッシュパターンを特定する
• シンボリケーションの状態を確認する

crash-analyzer を使う理由：クラッシュレポートを解析し、パターン（ヌルポインター、Swift ランタイム、ウォッチドッグ、jetsam）を特定して、実行可能な分析を生成する自律型エージェントです。

呼び出し：crash-analyzer エージェントを起動するか、/axiom:analyze-crash

---

12. MetricKit API リファレンス → metrickit-ref

トリガー：

• MetricKit のセットアップとサブスクリプション
• MXMetricPayload の解析（CPU、メモリ、起動、引っかかり）
• MXDiagnosticPayload の解析（クラッシュ、ハング、ディスク書き込み）
• MXCallStackTree のデコードとシンボリケーション
• 実機でのクラッシュ／ハング収集
• バックグラウンド終了メトリクス

metrickit-ref を使う理由：セットアップパターン、ペイロード解析、クラッシュレポートシステムとの統合を網羅した、MetricKit API の完全なリファレンスです。

呼び出し：/skill axiom-metrickit-ref

---

13. ハング診断 → hang-diagnostics

トリガー：

• アプリがハングまたはフリーズする
• メインスレッドが 1 秒を超えてブロックされる
• UI がタッチに応答しない
• Xcode Organizer にハング診断が表示される
• MetricKit の MXHangDiagnostic
• ウォッチドッグによる終了（起動中／バックグラウンドへの遷移中にアプリが強制終了される）

hang-diagnostics を使う理由：ビジー状態のメインスレッドとブロックされたメインスレッドを判別する決定木、ツールの選択（Time Profiler、System Trace）、修正方法を含む 8 つの一般的なハングパターンを使って、ハングを体系的に診断します。

呼び出し：/skill axiom-hang-diagnostics

---

14. ライブデバッグ → axiom-lldb

トリガー：

• クラッシュを対話的に再現する必要がある
• ブレークポイントを設定して状態を調べたい
• クラッシュレポートを分析したので、次はライブ調査が必要
• 実行中のアプリにデバッガーをアタッチする必要がある

axiom-lldb を使う理由：クラッシュレポートは何がクラッシュしたかを示します。LLDB はその理由を示します。

呼び出し：/skill axiom-lldb

---

16. 実行時コンソールのキャプチャ → xclog-ref

トリガー：

• アプリが実行時に何をログ出力しているか確認する必要がある
• アプリがクラッシュしたがクラッシュレポートがない（コンソール出力が必要）
• UI にフィードバックがないサイレントな失敗（ネットワーク、データ、認証）
• シミュレーターから print()/os_log() の出力をキャプチャしたい
• 分析用に構造化ログ出力が必要
• 「アプリは何を出力しているか？」

xclog-ref を使う理由：Xcode のデバッグコンソールには外部からアクセスできません。xclog は simctl の stdout/stderr と log stream の JSON を組み合わせ、print()、NSLog()、os_log()、Logger が出力するすべてのログをキャプチャします。自動分析に使える構造化フィールド（レベル、サブシステム、カテゴリ）も含まれます。

呼び出し：/skill axiom-xclog-ref または /axiom:console

---

15. コード署名の問題 → code-signing

該当するケース：

• 「署名証明書が見つかりません」
• 「プロビジョニングプロファイルに署名証明書が含まれていません」
• CI での errSecInternalComponent
• アップロード時の ITMS-90035 Invalid Signature
• ID が曖昧／複数の証明書がある
• Entitlement の不一致、または機能が不足している
• CI/CD のコード署名を設定する（GitHub Actions、fastlane match）
• 証明書の有効期限切れ、または失効

code-signing を使う理由：コード署名のエラーは、コードのバグでは決してありません。原因はすべて設定（証明書、プロファイル、entitlement、キーチェーン）です。CLI ツールを使った診断なら、推測に何時間もかける代わりに 5 分で済みます。

実行：/skill axiom-code-signing（ワークフロー）または /skill axiom-code-signing-diag（トラブルシューティング）

---

判断ツリー

1. 原因不明／断続的に発生する／クリーンビルドが失敗する？ → xcode-debugging（環境を最優先）
2. SPM の依存関係が競合している？ → spm-conflict-resolver（エージェント）
3. CocoaPods／その他の依存関係が競合している？ → build-debugging
4. ビルド時間が長い？ → build-performance
5. セキュリティ／プライバシー／App Store の準備？ → security-privacy-scanner（エージェント）
6. ビルドを自動修正したい（環境を最優先で診断）？ → build-fixer（エージェント）
7. ビルド時間の最適化スキャンを行いたい？ → build-optimizer（エージェント）
8. モダナイゼーション／非推奨 API？ → modernization-helper（エージェント）
9. TestFlight のクラッシュ／フィードバック？ → testflight-triage
10. App Store Connect の操作？ → app-store-connect-ref
11. クラッシュログ（.ips/.crash）がある？ → crash-analyzer（エージェント）
12. MetricKit の設定／解析？ → metrickit-ref
13. アプリのハング／フリーズ／watchdog？ → hang-diagnostics
14. クラッシュを対話的に再現したい／ランタイム状態を調べたい？ → axiom-lldb
15. コード署名エラー（証明書、プロファイル、entitlement、Keychain）？ → code-signing / code-signing-diag
16. ランタイムのコンソール出力（print/os_log）を確認したい？ → xclog-ref または /axiom:console

非合理化への対処

考え	実際のところ
「このリンカーエラーの直し方は分かっている」	リンカーエラーには 4 つ以上の根本原因があります。xcode-debugging ならすべてを 2 分で診断できます。
「とりあえずビルドフォルダーをクリーンにしよう」	クリーンビルドでは本当の問題が隠れてしまいます。xcode-debugging なら根本原因を見つけられます。
「SPM の問題にすぎないから、Package.swift を直そう」	SPM の競合は連鎖します。spm-conflict-resolver は依存関係グラフ全体を分析します。
「今日はシミュレーターの動作が遅いだけだ」	シミュレーターの問題は環境の破損を示しています。xcode-debugging なら体系的に確認できます。
「ローカルではコンパイルできるから、環境チェックは省こう」	環境を最優先に確認すれば、毎回 30 分以上を節約できます。
「再現する代わりに、クラッシュレポートをもっと注意深く読もう」	クラッシュレポートで分かるのは「何が」クラッシュしたかであり、「なぜ」かは分かりません。LLDB でブレークポイントを設定して再現すれば、実際の状態が明らかになります。axiom-lldb にワークフローがあります。
「証明書に問題はないはずだから、コードを確認しよう」	コード署名エラーは、コードのバグでは決してありません。原因はすべて設定です。code-signing なら CLI を使って 5 分で診断できます。
「Xcode がないとアプリのログを確認できない」	xclog はシミュレーターから print() と os_log を取得します。レベル、サブシステム、カテゴリを含む構造化 JSON 出力を得られます。/axiom:console または /skill axiom-xclog-ref を使ってください。

使用しないケース（競合の解決）

次のケースでは ios-build を使わず、適切なルーターを使ってください。

エラーの種類	適切なルーター	ios-build を使わない理由
Swift 6 の並行処理エラー	ios-concurrency	環境ではなくコードのエラーです
SwiftData のマイグレーションエラー	ios-data	ビルド環境ではなくスキーマの問題です
「'self' を送信するとデータ競合のリスクがあります」	ios-concurrency	Xcode の問題ではなく言語のエラーです
型の不一致／コンパイルエラー	コードを修正	これらはコードのバグです

ios-build は環境の原因不明な問題に使うものであり、コードのエラーには使いません：

• ✅ コードが正しいのに「モジュールが見つかりません」と表示される
• ✅ シミュレーターが起動しない
• ✅ クリーンビルドは失敗するが、インクリメンタルビルドは成功する
• ✅ ゾンビ状態の xcodebuild プロセス
• ❌ Swift の並行処理に関する警告／エラー
• ❌ データベースのマイグレーション失敗
• ❌ 有効なコードでの型チェックエラー

呼び出し例

ユーザー：「リンクエラーでビルドに失敗しました」 → 呼び出し：/skill axiom-xcode-debugging（環境を優先した診断）

ユーザー：「ビルドに10分かかります」 → 呼び出し：/skill axiom-build-performance

ユーザー：「SPMで依存関係を解決できません」 → 呼び出し：spm-conflict-resolver エージェント

ユーザー：「2つのパッケージが同じ依存関係の異なるバージョンを要求しています」 → 呼び出し：spm-conflict-resolver エージェント

ユーザー：「重複シンボルのリンクエラーが発生します」 → 呼び出し：spm-conflict-resolver エージェント

ユーザー：「App Store のセキュリティ審査に備えたいです」 → 呼び出し：security-privacy-scanner エージェント

ユーザー：「Privacy Manifest は必要ですか？」 → 呼び出し：security-privacy-scanner エージェント

ユーザー：「コードにハードコードされた認証情報はありますか？」 → 呼び出し：security-privacy-scanner エージェント

ユーザー：「ObservableObject から @Observable に移行するにはどうすればよいですか？」 → 呼び出し：modernization-helper エージェント

ユーザー：「最新の SwiftUI パターンを使うようにコードを更新してください」 → 呼び出し：modernization-helper エージェント

ユーザー：「@StateObject はまだ使うべきですか？」 → 呼び出し：modernization-helper エージェント

ユーザー：「ベータテスターからアプリがクラッシュしたと報告されました」 → 呼び出し：/skill axiom-testflight-triage

ユーザー：「App Store Connect でクラッシュを確認しましたが、調査方法がわかりません」 → 呼び出し：/skill axiom-testflight-triage

ユーザー：「クラッシュログがシンボリケートされていません」 → 呼び出し：/skill axiom-testflight-triage

ユーザー：「TestFlight のフィードバックを確認したいです」 → 呼び出し：/skill axiom-testflight-triage

ユーザー：「App Store Connect でクラッシュを見つけるにはどうすればよいですか？」 → 呼び出し：/skill axiom-app-store-connect-ref

ユーザー：「ASC のクラッシュフリーユーザー指標はどこにありますか？」 → 呼び出し：/skill axiom-app-store-connect-ref

ユーザー：「App Store Connect からクラッシュデータを書き出すにはどうすればよいですか？」 → 呼び出し：/skill axiom-app-store-connect-ref

ユーザー：「このクラッシュログを分析してください」[.ips の内容を貼り付け] → 呼び出し：crash-analyzer エージェントまたは /axiom:analyze-crash

ユーザー：「この .ips ファイルを解析してください：~/Library/Logs/DiagnosticReports/MyApp.ips」 → 呼び出し：crash-analyzer エージェントまたは /axiom:analyze-crash

ユーザー：「アプリがクラッシュした理由は何ですか？レポートはこちらです……」 → 呼び出し：crash-analyzer エージェントまたは /axiom:analyze-crash

ユーザー：「クラッシュデータを収集するために MetricKit を設定するにはどうすればよいですか？」 → 呼び出し：/skill axiom-metrickit-ref

ユーザー：「MXDiagnosticPayload を解析するにはどうすればよいですか？」 → 呼び出し：/skill axiom-metrickit-ref

ユーザー：「MXCallStackTree には何が含まれていますか？どうすればデコードできますか？」 → 呼び出し：/skill axiom-metrickit-ref

ユーザー：「アプリがときどきハングします」 → 呼び出し：/skill axiom-hang-diagnostics

ユーザー：「メインスレッドがブロックされ、UI が応答しません」 → 呼び出し：/skill axiom-hang-diagnostics

ユーザー：「Xcode Organizer にアプリのハング診断が表示されます」 → 呼び出し：/skill axiom-hang-diagnostics

ユーザー：「起動中にウォッチドッグによってアプリが終了されました」 → 呼び出し：/skill axiom-hang-diagnostics

ユーザー：「クラッシュレポートがあり、デバッガーで再現する必要があります」 → 呼び出し：/skill axiom-lldb

ユーザー：「このクラッシュを捕捉するブレークポイントを設定するにはどうすればよいですか？」 → 呼び出し：/skill axiom-lldb

ユーザー：「BUILD FAILED と表示されてビルドに失敗しますが、エラーの詳細がありません」 → 呼び出し：build-fixer エージェントまたは /axiom:fix-build

ユーザー：「ビルドが成功するときもあれば、失敗するときもあります」 → 呼び出し：build-fixer エージェントまたは /axiom:fix-build

ユーザー：「Xcode のビルド時間を短縮するにはどうすればよいですか？」 → 呼び出し：build-optimizer エージェントまたは /axiom:optimize-build

ユーザー：「ビルドしようとすると、署名証明書が見つからないと表示されます」 → 呼び出し：/skill axiom-code-signing-diag

ユーザー：「GitHub Actions の CI で errSecInternalComponent が発生します」 → 呼び出し：/skill axiom-code-signing-diag

ユーザー：「GitHub Actions のコード署名を設定するにはどうすればよいですか？」 → 呼び出し：/skill axiom-code-signing

ユーザー：「アプリはコンソールに何を出力していますか？」 → 呼び出し：/skill axiom-xclog-ref または /axiom:console

ユーザー：「シミュレーターのコンソール出力を確認したいです」 → 呼び出し：/skill axiom-xclog-ref または /axiom:console

ユーザー：「アプリが何も表示せずに失敗し、UI にエラーが出ません」 → 呼び出し：/skill axiom-xclog-ref または /axiom:console