SwiftUI エキスパートスキル

動作ルール

• すべてのタスク開始時に references/latest-apis.md を参照して、廃止予定の API を回避する
• UIKit/AppKit ブリッジが必要な場合を除き、ネイティブ SwiftUI API を優先する
• 正確性とパフォーマンスに注力し、特定のアーキテクチャ (MVVM、VIPER など) を強制しない
• ビジネスロジックをビューから分離することを推奨し、テスト容易性を高める (方法は問わない)
• Apple のヒューマンインターフェイスガイドラインと API デザインパターンに従う
• Liquid Glass は、ユーザーが明示的にリクエストした場合のみ採用する (references/liquid-glass.md 参照)
• パフォーマンス最適化を要件ではなく提案として提示する
• iOS 26+ 機能については #available ゲーティングと合理的なフォールバックを使用する

タスクワークフロー

既存の SwiftUI コードをレビューする

• レビュー対象のコードを読み、該当するトピックを特定する
• 廃止予定 API をフラグする (references/latest-apis.md と比較)
• 該当する各トピックについて以下のトピックルーターを実行する
• iOS 26+ 機能の #available ゲーティングとフォールバックパスを検証する

既存の SwiftUI コードを改善する

• 現在の実装をトピックルーターのトピックと照合し、監査する
• references/latest-apis.md の最新の同等物で廃止予定 API を置き換える
• 不要な状態更新を削減するために、ホットパスをリファクタリングする
• 複雑なビューボディを別のサブビューに抽出する
• UIImage(data:) が見つかった場合は画像ダウンサンプリングを提案する (オプション最適化、references/image-optimization.md 参照)

新しい SwiftUI 機能を実装する

• データフローを最初に設計する: 所有する状態 vs 注入される状態を特定する
• 最適な差分化のためにビューを構築する (早期にサブビューを抽出)
• 正しいアニメーションパターンを適用する (暗黙的 vs 明示的、トランジション)
• すべてのタップ可能な要素に Button を使用し、アクセシビリティグループと ラベルを追加する
• バージョン固有 API を #available でゲーティングし、フォールバックを提供する

新しい Instruments トレースを記録する

ユーザーが「トレースを記録する」「アプリをプロファイリングする」「セッションをキャプチャする」などと言った場合にトリガーする。完全なリファレンス: references/trace-recording.md

1. ターゲットを確認する — 実行中のアプリに接続、新しいアプリを起動、またはすべてのプロセスを記録? ユーザーが言及していない場合は確認する。接続されたデバイスを列挙すると便利:

   python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices
   

2. ターゲット種別に基づくテンプレートを選択する — SwiftUI テンプレートは任意の 実デバイス (物理的な iOS/iPadOS デバイス **またはホスト Mac) で SwiftUI レーンを設定します。唯一の例外は iOS Simulator で、SwiftUI レーンは空で返されます — その場合は --template "Time Profiler" に切り替えます (それでも Time Profiler + Hangs + Animation Hitches が得られます)。常に --list-devices を確認してください: simulators 種別 → Time Profiler; devices 種別 (実デバイスとホスト Mac) → デフォルト SwiftUI。完全な判定表は references/trace-recording.md にあります。
3. 記録を開始する。ユーザーが「完了したら教える」と言うエージェント駆動セッションの場合は、バックグラウンドで開始し、停止ファイルを使用します:

   python3 "${SKILL_DIR}/scripts/record_trace.py" \
       --device "<name|udid>" --attach "<AppName>" \
       --stop-file /tmp/stop-trace --output ~/Desktop/session.trace
   

   インタラクティブセッションの場合は、ユーザーに完了時に Ctrl+C を押すよう指示します。
4. 停止をシグナルする — ユーザーがアプリの演習を完了したと言ったら、touch /tmp/stop-trace を実行します。スクリプトは xctrace をクリーンに SIGINT し、最終化を最大 60 秒待ちます。
5. 結果のトレースを分析する (以下の「トレース駆動改善」ワークフローに流れ込む)。

トレース駆動改善 (Instruments .trace ファイルが提供される)

ユーザーのリクエストが .trace ファイルを参照するたびにトリガーします。対象の SwiftUI ソースファイルは オプション です — 指定された場合は特定の行を引用します。指定されない場合は、トレースが既に明らかにしているビュー名とシンボルに基づいて、どこを見るべきかを推奨します。

完全なリファレンス: references/trace-analysis.md。コンポジションパターンの概要:

1. 分析の対象を確定する。 自問してください: ユーザーはトレース全体を望んでいますか、それともスライスを望んでいますか?
   • 「X に焦点を当てる / X 後 / X と Y の間 / X 中」 → 最初にウィンドウを解決します (ステップ 2 参照)。
   • スコーピングの手がかりなし → トレース全体を分析します。
2. ウィンドウを解決する (ユーザーがスコーピングした場合のみ)。 パーサーは 2 つの検出モードを公開します:

   # 関心領域の開始/終了をマークするログを見つけます:
   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
       --list-logs --log-message-contains "loaded feed" --log-limit 5
   # または、os_signpost 間隔 (ペアになった begin/end) を名前でフィルタリング可能にリストします:
   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
       --list-signposts --signpost-name-contains "ImageDecode"
   

   両モードとも --window START_MS:END_MS を受け入れて検出をスコープします。ユーザーの説明に一致する time_ms (ログ用) または start_ms/end_ms (シグナルポスト用) を選択します。--window 10400:11700 のようなウィンドウを構築します。
3. メイン分析を実行する (--window の有無にかかわらず):

   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
       --json-only --top 10 [--window START_MS:END_MS]
   

4. references/trace-analysis.md で解釈する — 主要な診断:
   • 各相関内の main_running_coverage_pct (<25% = ブロック; ≥75% = CPU バウンド)。
   • swiftui-causes.top_sources は更新が継続する 理由 を明らかにします — UserDefaultObserver.send() や広い EnvironmentWriter エントリなどの高エッジカウントソースは構造的無効化バグです。1 つを修正すると、多くの下流のホットビューが頻繁に崩れます。
5. 特定のビューが高価であると表示される場合は、誰が無効化しているかを尋ねます。 --fanin-for "<view name>" を使用して、更新を駆動するソースノードのランク付きリストを取得します。
6. オプションでソースに根拠を置く。 ユーザーがファイルを指した場合は、それを読み、ビュー名 / ユーザーコードシンボルをそこの識別子と照合します。そうでない場合は、SwiftUI が報告したビュー名に基づいて、どのファイルを開くべきかを推奨します。
7. 優先付けられた計画を返す。 証拠 (カバレッジ %、ホットシンボル、重複するビュー、ログタイムスタンプ、原因グラフエッジ) を引用し、各推奨事項をトピックルーターリファレンスにルーティングします。
8. ユーザーがコード編集をリクエストした場合のみ、コードを編集します。

トピックルーター

現在のタスクに関連する各トピックのリファレンスファイルを参照してください:

トピック	リファレンス
状態管理	references/state-management.md
ビューコンポジション	references/view-structure.md
パフォーマンス	references/performance-patterns.md
リストと ForEach	references/list-patterns.md
レイアウト	references/layout-best-practices.md
シートとナビゲーション	references/sheet-navigation-patterns.md
ScrollView	references/scroll-patterns.md
フォーカス管理	references/focus-patterns.md
アニメーション (基本)	references/animation-basics.md
アニメーション (トランジション)	references/animation-transitions.md
アニメーション (高度)	references/animation-advanced.md
アクセシビリティ	references/accessibility-patterns.md
Swift Charts	references/charts.md
Charts アクセシビリティ	references/charts-accessibility.md
画像最適化	references/image-optimization.md
Liquid Glass (iOS 26+)	references/liquid-glass.md
macOS シーン	references/macos-scenes.md
macOS ウィンドウスタイリング	references/macos-window-styling.md
macOS ビュー	references/macos-views.md
テキストパターン	references/text-patterns.md
廃止予定 API 検索	references/latest-apis.md
Instruments トレース分析	references/trace-analysis.md
Instruments トレース記録	references/trace-recording.md

正確性チェックリスト

これらはハードルール — 違反は常にバグです:

• @State プロパティは private
• 子がペアレント状態を変更する場合のみ @Binding を使用
• 渡された値は @State または @StateObject として宣言されない (更新を無視する)
• ビュー所有オブジェクトには @StateObject; 注入されたものには @ObservedObject
• iOS 17+: @State と @Observable; バインディングが必要な注入可観測物には @Bindable
• ForEach は安定した ID を使用 (動的コンテンツに .indices を使用しない)
• ForEach 要素あたりのビュー数は一定
• .animation(_:value:) は常に value パラメーターを含む
• @FocusState プロパティは private
• .focusable() ビューのタップジェスチャーハンドラー内で冗長な @FocusState 書き込みなし
• iOS 26+ API は #available でゲーティングされ、フォールバックが提供される
• チャート型を使用するファイルに import Charts が存在

リファレンス

• references/latest-apis.md — すべてのタスクについて最初に読む。 廃止予定から最新 API への移行 (iOS 15+ から iOS 26+)
• references/state-management.md — プロパティラッパー、データフロー、@Observable マイグレーション
• references/view-structure.md — ビュー抽出、コンテナーパターン、@ViewBuilder
• references/performance-patterns.md — ホットパス最適化、更新制御、_logChanges()
• references/list-patterns.md — ForEach ID、Table (iOS 16+)、インラインフィルタリングの落とし穴
• references/layout-best-practices.md — レイアウトパターン、GeometryReader の代替案
• references/accessibility-patterns.md — VoiceOver、Dynamic Type、グループ化、トレイト
• references/animation-basics.md — 暗黙的/明示的アニメーション、タイミング、パフォーマンス
• references/animation-transitions.md — ビュートランジション、matchedGeometryEffect、Animatable
• references/animation-advanced.md — フェーズ/キーフレームアニメーション (iOS 17+)、@Animatable マクロ (iOS 26+)
• references/charts.md — Swift Charts マーク、軸、選択、スタイリング、Chart3D (iOS 26+)
• references/charts-accessibility.md — Charts VoiceOver、Audio Graph、フォールバック戦略
• references/sheet-navigation-patterns.md — シート、NavigationSplitView、Inspector
• references/scroll-patterns.md — ScrollViewReader、プログラマティックスクロール
• references/focus-patterns.md — フォーカス状態、focusable ビュー、フォーカス値、デフォルトフォーカス、一般的な落とし穴
• references/image-optimization.md — AsyncImage、ダウンサンプリング、キャッシング
• references/liquid-glass.md — iOS 26+ Liquid Glass エフェクトとフォールバックパターン
• references/macos-scenes.md — Settings、MenuBarExtra、WindowGroup、マルチウィンドウ
• references/macos-window-styling.md — ツールバースタイル、ウィンドウサイズ、Commands
• references/macos-views.md — HSplitView、Table、PasteButton、AppKit 相互運用
• references/text-patterns.md — Text イニシャライザー選択、逐語的 vs ローカライズ
• references/trace-analysis.md — scripts/analyze_trace.py を使用して Instruments .trace ファイルを解析; メインスレッドカバレッジ、高重大度 SwiftUI 更新、ヒッチナラティブを解釈; ソースファイルに検出結果をマップバック
• references/trace-recording.md — scripts/record_trace.py を使用して新しいトレースを記録: 実行中のアプリに接続、新しいアプリを起動、または手動で停止されたセッションをキャプチャ; エージェント駆動フローの停止ファイルをサポート