axiom-xcode-debugging

Xcode のデバッグ

概要

コードをデバッグする前に、ビルド環境を確認してください。基本原則： Xcode の「原因不明」な問題の 80% はコードのバグではなく、環境の問題（古い Derived Data、停止したシミュレーター、ゾンビプロセス）です。

プロンプトの例

このスキルで解決できる、開発者から実際に寄せられる質問を紹介します。

1. 「エラーの詳細が表示されず、ビルドが BUILD FAILED で失敗します。何も変更していないのに、何が起きているのでしょうか？」

→ このスキルでは、コードを調べる前に Derived Data、シミュレーターの状態、ゾンビプロセスを確認する、環境優先の診断方法を紹介します

2. 「コードを変更していないのに、昨日は成功したテストが今日は失敗します。困っています。どうすれば直せますか？」

→ このスキルでは、古い Derived Data と断続的な失敗について説明し、2～5 分でできる解決方法（Derived Data のクリーンアップ）を紹介します

3. 「アプリは問題なくビルドできますが、変更前の古いコードが実行されています。Xcode を再起動しても同じです。」

→ このスキルでは、Derived Data が古いビルドをキャッシュすることを示し、削除してクリーンビルドを強制する方法を紹介します

4. 「シミュレーターに Unable to boot simulator と表示され、テストを実行できません。どうすれば復旧できますか？」

→ このスキルでは、simctl を使ったシミュレーター状態の診断と、安全な復旧手順（消去／シャットダウン／再起動）を説明します

5. 「SPM の依存関係を更新した後、No such module: SomePackage エラーが発生します。どうすれば直せますか？」

→ このスキルでは、SPM のキャッシュに関する問題と、「幻の」モジュールエラーを解決する Derived Data のクリーンアップ手順を説明します

---

注意すべき兆候 — まず環境を確認

次のいずれかに当てはまる場合は、コードではなく環境に問題があると考えてください。

• 「自分のマシンでは動くのに、CI では動かない」
• 「コードを変更していないのに、昨日は成功したテストが今日は失敗する」
• 「ビルドは成功するが、古いコードが実行される」
• 「ビルドが成功したり失敗したりする」（断続的な失敗）
• 「シミュレーターがスプラッシュ画面で停止する」または「アプリをインストールできない」
• 30 分以上経過した xcodebuild プロセスが複数（10 個以上）ある

最初に必ず行う手順

必ず最初に、以下のコマンドを実行してください（コードを読む前に）。

# 1. Check processes (zombie xcodebuild?)
ps aux | grep -E "xcodebuild|Simulator" | grep -v grep

# 2. Check Derived Data size (>10GB = stale)
du -sh ~/Library/Developer/Xcode/DerivedData

# 3. Check simulator states (stuck Booting?)
xcrun simctl list devices | grep -E "Booted|Booting|Shutting Down"

これらの結果からわかること

• プロセスが 0 個＋Derived Data が小さい＋起動済みのシミュレーターがない → 環境はクリーンです。コードを調査してください
• プロセスが 10 個以上、または Derived Data が 10 GB 超、またはシミュレーターが停止している → 環境の問題です。まずクリーンアップしてください
• 古いコードが実行される、または断続的な失敗がある → サイズにかかわらず Derived Data をクリーンアップしてください

まず環境を確認する理由

• 環境のクリーンアップ：2～5 分 → 問題を解決
• 環境の問題をコードのデバッグで解決しようとする：30～120 分 → 時間の無駄

クイック修正の手順

スキーム名を確認する

スキーム名がわからない場合：

# List available schemes
xcodebuild -list

古いビルド／「No such module」エラーの場合

# Clean everything
xcodebuild clean -scheme YourScheme
rm -rf ~/Library/Developer/Xcode/DerivedData/*
rm -rf .build/ build/

# Rebuild
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16'

シミュレーターの問題の場合

# Shutdown all simulators
xcrun simctl shutdown all

# If simctl command fails, shutdown and retry
xcrun simctl shutdown all
xcrun simctl list devices

# If still stuck, erase specific simulator
xcrun simctl erase <device-uuid>

# Nuclear option: force-quit Simulator.app
killall -9 Simulator

ゾンビプロセスの場合

# Kill all xcodebuild (use cautiously)
killall -9 xcodebuild

# Check they're gone
ps aux | grep xcodebuild | grep -v grep

テストが失敗する場合

# Isolate failing test
xcodebuild test -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -only-testing:YourTests/SpecificTestClass

シミュレーターでの確認（任意）

修正を適用した後、シミュレーターで目視確認します。

スクリーンショットによる簡易確認

# 1. Boot simulator (if not already)
xcrun simctl boot "iPhone 16 Pro"

# 2. Build and install app
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

# 3. Launch app
xcrun simctl launch booted com.your.bundleid

# 4. Wait for UI to stabilize
sleep 2

# 5. Capture screenshot
xcrun simctl io booted screenshot /tmp/verify-build-$(date +%s).png

Axiom ツールを使用する

スクリーンショットを撮る：

/axiom:screenshot

シミュレーターの詳細なテスト（ナビゲーション、状態の設定を含む）：

/axiom:test-simulator

シミュレーターでの確認が必要な場合

次のような場合に使用します。

• 表示の修正 — レイアウトの変更、UI の更新、スタイルの微調整
• 状態に依存するバグ — 「特定の画面でのみ発生する」
• 断続的な失敗 — 特定の条件を再現する必要がある
• リリース前 — 修正が実際に機能することを最終確認する

ヒント：デバッグ用のディープリンクがある場合（axiom-deep-link-debugging スキルを参照）、問題が発生していた画面に直接移動できます。

xcrun simctl openurl booted "debug://problem-screen"
sleep 1
xcrun simctl io booted screenshot /tmp/fix-verification.png

判断フロー

Test/build failing?
├─ BUILD FAILED with no details?
│  └─ Clean Derived Data → rebuild
├─ Build intermittent (sometimes succeeds/fails)?
│  └─ Clean Derived Data → rebuild
├─ Build succeeds but old code executes?
│  └─ Delete Derived Data → rebuild (2-5 min fix)
├─ "Unable to boot simulator"?
│  └─ xcrun simctl shutdown all → erase simulator
├─ "No such module PackageName"?
│  └─ Clean + delete Derived Data → rebuild
├─ Tests hang indefinitely?
│  └─ Check simctl list → reboot simulator
├─ Tests crash?
│  └─ Check ~/Library/Logs/DiagnosticReports/*.crash
└─ Code logic bug?
   └─ Use systematic-debugging skill instead

よくあるエラーパターン

エラー	修正方法
BUILD FAILED（詳細なし）	Derived Data を削除
Unable to boot simulator	xcrun simctl erase <uuid>
No such module	クリーンアップして Derived Data を削除
テストが停止する	simctl list を確認し、シミュレーターを再起動
古いコードが実行される	Derived Data を削除

便利な CLI ツール

# Show build settings
xcodebuild -showBuildSettings -scheme YourScheme

# List schemes/targets
xcodebuild -list

# Verbose output
xcodebuild -verbose build -scheme YourScheme

# Build without testing (faster)
xcodebuild build-for-testing -scheme YourScheme
xcodebuild test-without-building -scheme YourScheme

# Version and build number management (agvtool)
xcrun agvtool what-marketing-version          # Current version (e.g., 2.0)
xcrun agvtool what-version                    # Current build number
xcrun agvtool next-version -all               # Bump build number
xcrun agvtool new-version -all 42             # Set specific build number
xcrun agvtool new-marketing-version 2.1       # Set marketing version

# Validate asset catalogs
xcrun amlint Assets.xcassets                   # Lint for issues before build

物理デバイス管理（devicectl）

devicectl は、物理デバイスの操作に使用する最新の CLI です（従来の idevice* ツールに代わるものです）。

# List connected devices
xcrun devicectl list devices

# Install app on device
xcrun devicectl device install app --device <udid> MyApp.app

# Launch app on device
xcrun devicectl device process launch --device <udid> com.your.bundleid

# List installed apps
xcrun devicectl device info apps --device <udid>

# List running processes
xcrun devicectl device info processes --device <udid>

使用する場面：問題が Simulator では再現しない場合の物理デバイスのデバッグ。CLI からインストール、起動、調査を行います。

クラッシュログの分析

# Recent crashes
ls -lt ~/Library/Logs/DiagnosticReports/*.crash | head -5

# Symbolicate a single address (if you have .dSYM)
xcrun atos -o YourApp.app.dSYM/Contents/Resources/DWARF/YourApp \
  -arch arm64 -l 0x100000000 0x<address>

# Symbolicate an entire crash log at once (LLDB Python script, may vary by Xcode version)
xcrun crashlog MyCrash.ips

よくある間違い

❌ 環境を確認する前にコードをデバッグする — 必ず最初に必須手順を実行してください

❌ シミュレーターの状態を無視する — 「Booting」のまま 10 分以上停止することがあります。その場合はすぐにシャットダウンして再起動してください

❌ 問題の原因は git の変更だと思い込む — コードを変更しても、Derived Data に古いビルドがキャッシュされていることがあります

❌ 1 つのテストが失敗したときにテストスイート全体を実行する — -only-testing を使って対象を絞り込んでください

実際の効果

実施前 「なぜ古いコードが実行されるのか」のデバッグに 30 分以上
実施後 環境を 2 分で確認 → Derived Data をクリーンアップ → 問題を解決

重要なポイント まず環境を確認し、その後にコードをデバッグします。