Communitygithub.com

ComeOnOliver/skillshub - SwiftUI デバッグ診断

SwiftUI ビューのデバッグにおいて、基本的なトラブルシューティングで解決しない場合、断続的なUI問題、複雑な状態依存関係、または Self._printChanges() が予期しない更新パターンを示す場合に、Instruments と連携した体系的な診断ワークフローを提供します。

skillshub - SwiftUI デバッグ診断 とは?

このスキルは、SwiftUI のビュー更新問題を体系的に診断するためのワークフローを提供します。基本的なトラブルシューティングで解決しない場合、断続的に発生するUIの問題、複雑な依存関係チェーン、パフォーマンス調査、またはプレビューのクラッシュなど、高度な問題に対応します。主な診断パターンとして、D1: Self._printChanges() 分析でビュー更新の原因を特定、D2: SwiftUI Instrument で複雑な更新パターンを可視化、D3: ビューの同一性調査で @State の予期しないリセットを防止、D4: 環境依存関係のチェックで不要な更新を削減、D5: プレビュー診断でクラッシュ原因を特定します。このスキルは Xcode 26+、iOS 26+ / macOS Tahoe+ を前提としており、推奨されない回避策(.id(UUID()) の使用や無作為な @State/@Observable の変更など)を禁止し、根本原因を理解したうえで修正することを重視しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-debugging-diag

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

SwiftUI デバッグ診断

この診断スキルを使用すべき時

以下の場合に使用します:

  • 基本的なトラブルシューティングが失敗した — axiom-swiftui-debugging スキルのパターンを適用したが問題が続く
  • Self._printChanges() が予期しないパターンを示す — ビューが更新されるべきでない時に更新される、または更新されるべき時に更新されない
  • 断続的な問題 — 動作したりしなかったりする(「ハイゼンバグ」)
  • 複雑な依存関係チェーン — 複数のビュー/モデルを通じたデータフローを追跡する必要がある
  • パフォーマンス調査 — ビューが頻繁に、または長時間かけて更新される
  • プレビューの謎 — すぐには明らかでないクラッシュや障害

禁止行為

プレッシャーがかかると、問題を診断する代わりに隠すショートカットに誘惑されるでしょう。絶対にこれらを行わないでください:

❌ 無作為な @State/@Observable の変更による推測

  • 「ここで @Observable を追加して、動くか試してみましょう」
  • 「これを @StateObject に変えれば直るかもしれない」

❌ 強制更新のための .id(UUID()) の追加

  • レンダリングのたびに新しいビュー識別子を作成
  • 状態の保存を破壊
  • 根本原因を隠蔽

❌ iOS 17+ で @Observable で十分な場合の ObservableObject の使用

  • 不要な複雑さを追加
  • 自動依存関係トラッキングを逃す

❌ 断続的な問題の無視(「動作したりしなかったりする」)

  • 「とりあえずマージして、本番で起きないことを祈ろう」
  • 断続的 = ランダムではなく、体系的なバグ

❌ 理解せずに出荷する

  • 「修正は動いている、理由はわからない」
  • 本番環境は試行錯誤には高すぎる

必須の最初のステップ

診断パターンに入る前に、ベースライン環境を確立します:

# 1. Instruments のセットアップを確認
xcodebuild -version  # SwiftUI Instrument には Xcode 26+ が必要

# 2. プロファイリング用に Release モードでビルド
xcodebuild build -scheme YourScheme -configuration Release

# 3. プレビューの問題を調査する場合、派生データをクリア
rm -rf ~/Library/Developer/Xcode/DerivedData

所要時間: 5分 理由: 間違った Xcode バージョンや Debug モードは誤解を招くプロファイリングデータを生成します


診断決定木

基本的なトラブルシューティング後の SwiftUI ビューの問題?
│
├─ ビューが更新されない?
│  ├─ 基本チェック: 一時的に Self._printChanges() を追加
│  │  ├─ "@self changed" と表示 → ビューの値が変更された
│  │  │  └─ パターン D1: ビューの再作成を引き起こした原因を分析
│  │  ├─ 特定の状態プロパティが表示 → その状態が更新をトリガー
│  │  │  └─ 確認: その状態が更新をトリガーすべきか?
│  │  └─ 何もログに出力されない → body が呼び出されていない
│  │     └─ パターン D3: ビュー同一性調査
│  └─ 高度: SwiftUI Instrument を使用
│     └─ パターン D2: SwiftUI Instrument 調査
│
├─ ビューが頻繁に更新される?
│  ├─ パターン D1: Self._printChanges() 分析
│  │  └─ 不要な状態依存関係を特定
│  └─ パターン D2: SwiftUI Instrument → 原因と影響グラフ
│     └─ データフローを追跡し、広範な依存関係を見つける
│
├─ 断続的な問題(動作したりしなかったりする)?
│  ├─ パターン D3: ビュー同一性調査
│  │  └─ 確認: 同一性が予期せず変化するか?
│  ├─ パターン D4: 環境依存関係チェック
│  │  └─ 確認: 環境の値が頻繁に変化するか?
│  └─ プレビューで30回以上再現
│     └─ 再現できない場合: タイミング/競合状態の可能性
│
└─ プレビュークラッシュ(基本的な修正後)?
    ├─ パターン D5: プレビュー診断(Xcode 26)
    │  └─ 診断ボタン、クラッシュログを確認
    └─ それでも失敗する場合: パターン D2(プレビュービルドをプロファイル)

診断パターン

パターン D1: Self._printChanges() 分析

所要時間: 5分

症状: ビューの body が正確にどのような理由で実行されるかを理解する必要がある

使用すべき時:

  • ビューが予想より頻繁に更新される
  • ビューが更新されるべき時に更新されない
  • リファクタリング後の依存関係の確認

手法:

struct MyView: View {
    @State private var count = 0
    @Environment(AppModel.self) private var model

    var body: some View {
        let _ = Self._printChanges()  // 一時的に追加

        VStack {
            Text("Count: \(count)")
            Text("Model value: \(model.value)")
        }
    }
}

出力の解釈:

# シナリオ 1: ビューパラメータが変更された
MyView: @self changed
→ 親が新しい MyView インスタンスを渡した
→ 親のコードを確認 - 何が再作成をトリガーしたか?

# シナリオ 2: 状態プロパティが変更された
MyView: count changed
→ ローカルの @State が更新をトリガー
→ count を変更した場合、予想通り

# シナリオ 3: 環境プロパティが変更された
MyView: @self changed  # 環境は @self の一部
→ 環境の値が変更された(カラースキーム、ロケール、カスタム値)
→ パターン D4: 環境依存関係を確認

# シナリオ 4: 何もログに出力されない
→ body が呼び出されていない
→ パターン D3: ビュー同一性調査

よくある発見:

  1. 予期しない時に "@self changed" が表示される

    • 親が不必要にビューを再作成している
    • 親の状態管理を確認
  2. 変更していないプロパティが変更されたと表示される

    • 間接的な依存関係(変更されたオブジェクトから読み取っている)
    • パターン D2: Instruments を使用して追跡
  3. 複数のプロパティが一緒に変更される

    • 広範な依存関係(例:1つだけ必要なのに配列全体を読み取っている)
    • 修正:特定の依存関係を抽出

確認:

  • コミット前に Self._printChanges() 呼び出しを削除
  • このコードを本番環境に出荷しないでください

相互参照: 複雑なケースでは、パターン D2(SwiftUI Instrument)を使用


パターン D2: SwiftUI Instrument 調査

所要時間: 25分

症状: Self._printChanges() だけでは完全に説明できない複雑な更新パターン

使用すべき時:

  • 複数のビューが、1つだけ更新されるべき時に更新される
  • アプリを通じたデータフローを追跡する必要がある
  • ビューが更新されているが、どのデータがトリガーしたかわからない
  • ビュー body の更新が長い(パフォーマンス問題)

前提条件:

  • Xcode 26+ がインストールされている
  • デバイスが iOS 26+ / macOS Tahoe+ にアップデートされている
  • Release モードでビルド

手順:

1. Instruments を起動(5分)

# Release ビルド
xcodebuild build -scheme YourScheme -configuration Release

# Instruments を起動
# Xcode で Command-I を押す
# 「SwiftUI」テンプレートを選択

2. トレースを記録(3分)

  • Record ボタンをクリック
  • 予期しない更新をトリガーするアクションを実行
  • 記録を停止(10〜30秒のインタラクションで十分)

3. 長いビュー body の更新を分析(5分)

  • Long View Body Updates レーンを確認
  • オレンジまたは赤いバーがあるか? それらは高コストなビュー
  • 長い更新をクリック → 詳細ペインにビュー名が表示
  • 右クリック → 「Inspection Range and Zoom を設定」
  • Time Profiler トラックに切り替え
  • コールスタックでビューを見つける
  • 高コストな操作(フォーマッタ作成、計算など)を特定

修正: 高コストな操作をモデル層に移動し、結果をキャッシュ

4. 不要な更新を分析(7分)

  • ユーザーアクションの時間範囲をハイライト(例:お気に入りボタンをタップ)
  • 詳細ペインで階層を展開
  • 更新回数をカウント — 予想より多いか?
  • ビューにホバー → 矢印をクリック → 「原因と影響グラフを表示」

5. 原因と影響グラフを解釈(5分)

グラフのノード:

[青いノード] = あなたのコード(ジェスチャー、状態変更、ビュー body)
[システムノード] = SwiftUI/システムのワーク
[「update」とラベル付けされた矢印] = この更新を引き起こした
[「creation」とラベル付けされた矢印] = ビューの表示を引き起こした

一般的なパターン:

# パターン A: 単一のビューのみ更新(GOOD)
[Gesture] → [State Change in ViewModelA] → [ViewA body]

# パターン B: すべてのビューが更新(BAD - 広範な依存関係)
[Gesture] → [Array change] → [All list item views update]
└─ 修正: アイテムごとに細かいビューモデルを使用

# パターン C: 環境を通じたカスケード(CHECK)
[State Change] → [Environment write] → [Many view bodies check]
└─ 環境の値が頻繁に変わる場合 → パターン D4 で修正

ノードをクリック:

  • 状態変更ノード → 値が設定された場所のバックトレースを表示
  • ビュー body ノード → 読み取ったプロパティ(依存関係)を表示

確認:

  • 修正後に新しいトレースを記録
  • 修正前後の更新回数を比較
  • 赤/オレンジのバーが減少または排除されたことを確認

相互参照: 詳細な Instruments ワークフローについては axiom-swiftui-performance スキルを参照


パターン D3: ビュー同一性調査

所要時間: 15分

症状: @State の値が予期せずリセットされる、またはビューがアニメーションしない

使用すべき時:

  • カウンターがリセットされるべきでない時に0にリセットされる
  • アニメーションが機能しない(ビューがアニメーションではなくポップ表示される)
  • ForEach のアイテムが飛び回る
  • テキストフィールドのフォーカスが外れる

根本原因: ビューの同一性が予期せず変更された

調査手順:

1. 条件付き配置を確認(5分)

// ❌ 問題: 条件によって同一性が変わる
if showDetails {
    CounterView()  // showDetails がトグルされるたびに新しい同一性を得る
}

// ✅ 修正: .opacity() を使用
CounterView()
    .opacity(showDetails ? 1 : 0)  // 常に同じ同一性

検索: 状態を保持する if/else 内のビューをコードベースから探す

2. .id() モディファイアを確認(5分)

// ❌ 問題: データが変わると .id() も変わる
DetailView()
    .id(item.id + "-\(isEditing)")  // isEditing で ID が変わる

// ✅ 修正: 安定した ID
DetailView()
    .id(item.id)  // 安定した ID

検索: コードベースで .id( を検索 — ID 値が変化するか確認

3. ForEach の識別子を確認(5分)

// ❌ 間違い: インデックスベースの ID
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
    Text(item.name)
}

// ❌ 間違い: 一意でない ID
ForEach(items, id: \.category) { item in  // カテゴリごとに複数のアイテム
    Text(item.name)
}

// ✅ 正しい: 一意で安定した ID
ForEach(items, id: \.id) { item in
    Text(item.name)
}

検索: ForEach を検索 — 一意で安定した ID を確認

修正パターン:

問題修正
条件内のビュー代わりに .opacity() を使用
.id() が頻繁に変わる安定した識別子を使用
ForEach が飛び回る一意で安定した ID を使用(UUID またはサーバー ID)
ナビゲーションで状態がリセットされるNavigationStack のパス管理を確認

確認:

  • Self._printChanges() を追加 — "@self changed" が繰り返し表示されるべきではない
  • アニメーションがスムーズに動作するようになるはず
  • @State の値が維持されるはず

パターン D4: 環境依存関係チェック

所要時間: 10分

症状: 無関係なデータが変更されたときに多くのビューが更新される

使用すべき時:

  • 原因と影響グラフで「Environment」ノードが多くの更新をトリガーしている
  • スクロールやアニメーションのパフォーマンスが遅い
  • 予期しないカスケード更新

根本原因: 頻繁に変化する値が環境にある、またはあまりに多くのビューが環境を読み取っている

調査手順:

1. 環境への書き込みを探す(3分)

# 現在のプロジェクトで環境モディファイアを検索
grep -r "\.environment(" --include="*.swift" .

確認すべきもの:

// ❌ 悪い例: 頻繁に変化する値
.environment(\.scrollOffset, scrollOffset)  // 毎秒60回以上更新
.environment(model)  // モデルが頻繁に更新される場合

// ✅ 良い例: 安定した値
.environment(\.colorScheme, .dark)
.environment(appModel)  // appModel の変更が稀な場合

2. 環境にあるものを確認(3分)

パターン D2(Instruments)を使用して、原因と影響グラフを確認:

  • 「Environment」ノードをクリック
  • どのプロパティが変更されたか確認
  • 更新をチェックしたビューの数をカウント

質問:

  • この値はスクロール/アニメーションのフレームごとに変化していますか?
  • これらすべてのビューが実際にこの値を必要としていますか?

3. 修正を適用(4分)

修正 A: 環境から削除(頻繁に変化する場合):

// ❌ 修正前: 環境
.environment(\.scrollOffset, scrollOffset)

// ✅ 修正後: 直接パラメータ
ChildView(scrollOffset: scrollOffset)

修正 B: @Observable モデルを使用(多くのビューで必要な場合):

// 環境にプリミティブを保存する代わりに:
@Observable class ScrollViewModel {
    var offset: CGFloat = 0
}

// ビューは特定のプロパティに依存:
@Environment(ScrollViewModel.self) private var viewModel

var body: some View {
    Text("\(viewModel.offset)")  // offset が変更された時のみ更新
}

確認:

  • Instruments で新しいトレースを記録
  • 原因と影響グラフを確認 — 更新されるビューが減少しているはず
  • パフォーマンスが向上しているはず(スクロール/アニメーションがよりスムーズに)

パターン D5: プレビュー診断(Xcode 26)

所要時間: 10分

症状: プレビューが読み込まれない、または不明瞭なエラーでクラッシュする

使用すべき時:

  • 基本的な修正(swiftui-debugging スキル)後もプレビューが失敗する
  • エラーメッセージが不明瞭または一般的
  • プレビューが以前は動作していたが、突然停止した

調査手順:

1. プレビュー診断ボタンを使用(2分)

場所: Editor メニュー → Canvas → Diagnostics

表示されるもの:

  • 詳細なエラーメッセージ
  • 不足している依存関係
  • 状態の初期化の問題
  • プレビュー固有の問題

2. クラッシュログを確認(3分)

# クラッシュログディレクトリを開く
open ~/Library/Logs/DiagnosticReports/

# 「Preview」を含む最近の .crash ファイルを探す
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5

確認すべきもの:

  • 致命的なエラー(配列の範囲外、強制アンラップ nil)
  • 不足しているモジュールのインポート
  • フレームワークの初期化失敗

3. 問題を分離する(5分)

最小限のプレビューを作成:

// 空のプレビューから開始
#Preview {
    Text("Test")
}

// これが動作する場合、徐々に追加:
#Preview {
    MyView()  // 実際のビュー、ただしモックデータを使用
        .environment(MockModel())  // すべての依存関係を提供
}

// どの依存関係がクラッシュを引き起こすか特定

よくある問題:

エラー原因修正
"Cannot find in scope"依存関係の不足プレビューに追加(下記の例参照)
"Fatal error: Unexpectedly found nil"オプショナルのアンラップ失敗プレビューで非 nil の値を提供
"No such module"インポート不足import 文を追加
サイレントクラッシュ(エラーなし)無効な値での状態初期化安全なデフォルトを使用

修正パターン:

// @Environment の不足
#Preview {
    ContentView()
        .environment(AppModel())  // 依存関係を提供
}

// @EnvironmentObject の不足(iOS 17 未満)
#Preview {
    ContentView()
        .environmentObject(AppModel())
}

// ModelContainer の不足(SwiftData)
#Preview {
    let config = ModelConfiguration(isStoredInMemoryOnly: true)
    let container = try! ModelContainer(for: Item.self, configurations: config)
    
    ContentView()
        .modelContainer(container)
}

確認:

  • プレビューがロードされ、インタラクティブになる
  • クラッシュログに新しいエントリがない
  • 同じ問題が発生した場合、パターン D2 に進む

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

関連スキル