Communitygithub.com

UIKit アニメーションデバッグ

CAAnimation の完了ハンドラが呼び出されない、実機でのスプリング物理演算の挙動がおかしい、アニメーション時間が実際と合わない、ジェスチャーとアニメーションの連携でカクつく、シミュレータと実機でタイミングが異なる場合に、CATransaction パターン、フレームレート認識、デバイス固有の動作を考慮した体系的な CAAnimation 診断を行います。

UIKit アニメーションデバッグ とは?

このスキルは、UIKit の CAAnimation に関する問題を体系的に診断し解決するためのものです。Completion handler が呼び出されない、アニメーションの持続時間が宣言と実際で異なる、スプリングアニメーションが実機でカクつく、ジェスチャーとアニメーションの連携がスムーズでないなど、Core Animation のバグではなく、CATransaction のタイミング、レイヤーの状態、フレームレートの仮定に起因する問題が90%を占めるという原則に基づいています。このスキルでは、原因を特定するための必須の初動診断手順、決定木によるパターン選択、そして7つの一般的な問題パターン(完了ハンドラの基本、CATransaction と duration のミスマッチ、isRemovedOnCompletion と fillMode、weak self の必須使用、複数アニメーションの競合、CADisplayLink による同期、デバイス性能に応じたスプリング調整)を提供します。また、シミュレータは60Hz固定であるため実際のタイミング問題を隠蔽しやすいという警告に基づき、必ず実機(サポート対象最古モデル)でのテストを必須としています。問題解決に行き詰まった場合のチェックリストも用意されており、診断結果の誤解釈やパターンの誤適用を防ぎます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/Axiom/.claude-plugin/plugins/axiom/skills/uikit-animation-debugging

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

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

ドキュメント

UIKit アニメーションデバッグ は何をしますか?

概要

CAAnimation の問題は、特定の条件下で、完了ハンドラが呼び出されない、タイミングがおかしい、カクつくといった形で現れます。核となる原則 CAAnimation の問題の90%は、Core Animation のバグではなく、CATransaction のタイミング、レイヤーの状態、またはフレームレートの仮定に起因します。

警告サイン — CAAnimation の問題を疑うべきケース

以下のいずれかに該当する場合は、デバイスの動作ではなくアニメーションロジックに問題があると疑ってください:

  • シミュレータでは完了ハンドラが呼ばれるが、実機では呼ばれない
  • アニメーションの持続時間(0.5秒)が実際の見た目の持続時間(1.2秒)と一致しない
  • スプリングアニメーションが iPhone 15 Pro では正しく見えるが、古いデバイスではカクつく
  • ジェスチャーとアニメーションを同時に行うとカクつく(個別では問題ない)
  • 完了ハンドラで [weak self] を使っているが、その理由がわからない
  • ❌ 禁止 実際の動作に合わせるために duration や値をハードコーディングすること
    • これは異なるハードウェアのユーザーにデバイス固有のバグを出荷することになります
    • これを「一時的な修正」や「十分良い」と正当化しないでください

重要な区別 シミュレータはタイミング問題を隠蔽することがよくあります(60Hz固定、スロットリングなし)。実機ではこれらの問題が露呈します(可変フレームレート、CPUスロットリング、バックグラウンドプレッシャー)。必須: 出荷前に必ず実機(サポート対象の最古モデル)でテストしてください。

必須の初動診断

コードを変更する前に、常にこれらを最初に実行してください:

// 1. 完了ハンドラが呼ばれているか確認
animation.completion = { [weak self] finished in
    print("🔥 完了ハンドラ呼び出し: finished=\(finished)")
    guard let self = self else {
        print("🔥 self が nil でした")
        return
    }
    // 元のコード
}

// 2. 実際の持続時間と宣言された持続時間を確認
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5  // 宣言
layer.add(anim, forKey: "test")

DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
    print("経過時間: \(Date().timeIntervalSince(startTime))")  // 実際
}

// 3. アクティブなアニメーションを確認
if let keys = layer.animationKeys() {
    print("アクティブなアニメーション: \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key): duration=\(anim.duration), removed=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. レイヤーの状態を確認
print("レイヤーの速度: \(layer.speed)")  // != 1.0 はタイミングが変更されている
print("レイヤーのtimeOffset: \(layer.timeOffset)")  // != 0 はアニメーションがオフセットされている

これが示すこと

  • 完了ハンドラの print が表示される → ハンドラは呼ばれている。問題はコールバックコードにある。
  • 完了ハンドラの print が表示されない → ハンドラが呼ばれていない。CATransaction/レイヤーの状態を確認。
  • 経過時間 == 宣言時間 → 持続時間は正しい。見た目のカクつきはフレームレートの問題。
  • 経過時間 != 宣言時間 → CATransaction のラッピングが持続時間を変更している。
  • layer.speed != 1.0 → 何かがアニメーションを遅くしている。
  • アクティブなアニメーションのリストが長い → 複数のアニメーションが競合している。

必須の解釈

コードを変更する前に、以下の1つの診断が根本原因であることを特定する必要があります:

  1. 完了ハンドラが呼ばれるが、経過時間が宣言時間と異なる場合 → パターン2(CATransaction)を適用
  2. 完了ハンドラが呼ばれず、isRemovedOnCompletion が true の場合 → パターン3を適用
  3. 完了ハンドラが呼ばれるが見た目がカクつく場合 → 必ず最初に Instruments でプロファイルする
    • 「おそらくフレームレートの問題でしょう」と推測してはいけません。データで証明してください。
    • プロファイル > Core Animation インストゥルメントでフレームドロップを確実に確認できます。
    • Instruments をスキップするなら、それは推測です。

診断結果が矛盾または不明瞭な場合

  • 止まってください。まだパターンに進まないでください。
  • 原因を絞り込むために print 文を追加してください。
  • 自問してください: 「診断結果は X と Y を示しているが、Z が一致しない。何を見落としているのか?」
  • 不明な場合は Instruments > Core Animation でプロファイルしてください。

決定木

CAAnimation の問題?
├─ 完了ハンドラが呼ばれない?
│  ├─ シミュレータのみ?
│  │  └─ シミュレータのタイミングは異なる(60Hz)。実機でテスト。
│  ├─ 実機のみ?
│  │  ├─ 確認: isRemovedOnCompletion と fillMode
│  │  ├─ 確認: CATransaction のラッピング
│  │  └─ 確認: アニメーション中にアプリがバックグラウンドに移行するか
│  └─ シミュレータと実機の両方?
│     ├─ 確認: 完了ハンドラがアニメーション追加前に設定されているか
│     └─ 確認: [weak self] が実際にキャプチャされているか(完了前に nil になっていないか)
│
├─ 持続時間のミスマッチ (宣言 != 見た目)?
│  ├─ layer.speed != 1.0?
│  │  └─ 何かがアニメーションの持続時間を変更している。見つけて修正。
│  ├─ アニメーションが CATransaction でラップされている?
│  │  └─ CATransaction.setAnimationDuration() が animation.duration を上書きする
│  └─ 見た目の持続時間が宣言より長い?
│     └─ シミュレータ(60Hz) vs デバイス(120Hz)。実際のハードウェアに合わせて再計算。
│
├─ スプリング物理演算が実機でおかしい?
│  ├─ 値が1つのデバイス用にハードコーディングされている?
│  │  └─ モデルではなくデバイスのパフォーマンスクラスを使用
│  ├─ damping/stiffness の値が mass/stiffness と入れ替わっている?
│  │  └─ CASpringAnimation のパラメータの意味を確認
│  └─ シミュレータでは動作するが実機では動作しない?
│     └─ シミュレータは60Hz。デバイスは120Hzの場合がある。再計算。
│
└─ ジェスチャー + アニメーションのカクつき?
   ├─ アニメーションが競合している (同じ keyPath)?
   │  └─ 新しいアニメーションを追加する前に古いアニメーションを削除
   ├─ アニメーション実行中にジェスチャーがレイヤーを更新している?
   │  └─ 同期更新に CADisplayLink を使用
   └─ ジェスチャーがメインスレッドをブロックしている?
      └─ Instruments > Core Animation でプロファイル

一般的なパターン

パターン選択ルール(必須)

パターンは1つずつ、この順序で適用すること

  1. 常にパターン1から始める(完了ハンドラの基本)

    • 完了ハンドラが絶対に呼ばれない場合 → パターン1
    • print 文(33行目)を使用して、完了ハンドラが add() の前に設定されていることを確認する
    • 完了ハンドラが呼ばれているが、タイミングがおかしい場合のみパターン2に進む
  2. 次にパターン2(CATransaction の持続時間ミスマッチ)

    • 完了ハンドラが呼ばれるが、経過時間が宣言時間と異なる場合のみ
    • 必須の初動診断のログ(40-47行目)を確認する
  3. 次にパターン3(isRemovedOnCompletion)

    • アニメーションは完了するが、視覚的な状態が元に戻る場合のみ
  4. パターン4-7 特定の症状に基づいて適用(91行目以降の決定木を参照)

禁止事項

  • ❌ 複数のパターンを同時に適用すること(「パターン2とパターン4を一緒に試そう」)
  • ❌ 「すでにそうでないとわかっている」という理由でパターン1をスキップすること
  • ❌ それぞれのパターンが必要な理由を理解せずにパターンを組み合わせること
  • ❌ パターンをランダムに試して、どれかがうまくいくことを期待すること

パターン1: 完了ハンドラの基本

❌ 間違い(アニメーション追加後にハンドラを設定)

layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in  // ❌ 遅すぎる!
    print("完了")
}

✅ 正しい(追加前にハンドラを設定)

animation.completion = { [weak self] finished in
    print("🔥 アニメーション完了: \(finished)")
    guard let self = self else { return }
    self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")

理由 完了ハンドラは、アニメーションがレイヤーに追加される前に設定する必要があります。追加後に設定しても何も起こりません。


パターン2: CATransaction と animation.duration

❌ 間違い(CATransaction がアニメーションの持続時間を上書き)

CATransaction.begin()
CATransaction.setAnimationDuration(2.0)  // ❌ すべてのアニメーションを上書き!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5  // これは無視される
layer.add(anim, forKey: nil)
CATransaction.commit()  // アニメーションは0.5秒ではなく2.0秒かかる

✅ 正しい(トランザクションではなくアニメーションに持続時間を設定)

let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// CATransaction のラッピングなし

理由 CATransaction.setAnimationDuration() は、トランザクションブロック内のすべてのアニメーションに影響します。すべてのアニメーションを均一に変更したい場合にのみ使用してください。


パターン3: isRemovedOnCompletion と fillMode

❌ 間違い(完了後にアニメーションが消える)

let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// 0.5秒後、アニメーションが削除され、レイヤーが元の状態に戻る

✅ 正しい(アニメーションの状態を維持)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // アニメーション後の最終状態を維持
layer.add(anim, forKey: nil)
// 0.5秒後、アニメーションの状態が保持される

理由 デフォルトでは、アニメーションは削除され、レイヤーは元の状態に戻ります。永続的な状態変更には、isRemovedOnCompletion = false と fillMode = .forwards を設定します。


パターン4: 完了ハンドラでの弱参照 self(必須)

❌ 禁止(強参照 self は循環参照を引き起こす)

anim.completion = { finished in
    self.property = "value"  // ❌ 循環参照が確実
}

✅ 必須(常に弱参照 self を使用)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "value"  // 安全にアクセス
}

これが必須であり、オプションではない理由

  • CAAnimation はアニメーションが完了するまで完了ハンドラを保持し続ける
  • 完了ハンドラは self を強参照でキャプチャする(明示的に弱参照にしない限り)
  • 循環参照が発生: self → アニメーション → 完了ハンドラ → self
  • アニメーションが短時間(0.3秒)でもメモリリークが発生する

禁止される正当化

  • ❌ 「アニメーションが短いので循環参照のリスクはない」
  • ❌ 「手動でアニメーションを削除するので問題ない」
  • ❌ 「このコードパスは一度しか実行されない」

完了ハンドラでは常に [weak self] を使用してください。例外はありません。


パターン5: 複数のアニメーション(同じ keyPath)

❌ 間違い(アニメーションが競合)

// アニメーション1を追加
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")

// 後でアニメーション2を追加
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")  // ❌ 同じキー。anim1 を置き換える!

✅ 正しい(追加前に古いアニメーションを削除)

layer.removeAnimation(forKey: "slide")  // 最初に古いものを削除

let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")

または一意のキーを使用:

let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")

let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2")  // 異なるキー

理由 同じキーでアニメーションを追加すると、以前のアニメーションが置き換えられます。古いアニメーションを削除するか、一意のキーを使用してください。


パターン6: ジェスチャーとアニメーションの同期のための CADisplayLink

❌ 間違い(ジェスチャーが直接更新し、アニメーションが異なるレートで更新)

func handlePan(_ gesture: UIPanGestureRecognizer) {
    let translation = gesture.translation(in: view)
    view.layer.position.x = translation.x  // ❌ 同期の問題
}

// 別途:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // 非同期によるカクつき

✅ 正しい(同期に CADisplayLink を使用)

var displayLink: CADisplayLink?

func startSyncedAnimation() {
    displayLink = CADisplayLink(
        target: self,
        selector: #selector(updateAnimation)
    )
    displayLink?.add(to: .main, forMode: .common)
}

@objc func updateAnimation() {
    // 同じフレームでジェスチャーとアニメーションの両方を更新
    let gesture = currentGesture
    let position = calculatePosition(from: gesture)
    layer.position = position  // 同期された更新
}

理由 ジェスチャー認識機能と CAAnimation は異なるフレームレートで実行される可能性があります。CADisplayLink は両方を画面のリフレッシュレートに同期します。


パターン7: スプリングアニメーションのデバイス差

❌ 間違い(1つのデバイス用にハードコーディング)

let springAnim = CASpringAnimation()
springAnim.damping = 0.7  // iPhone 15 Pro 用にハードコーディング
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil)  // iPhone 12 でカクつく

✅ 正しい(デバイスのパフォーマンスに適応)

let springAnim = CASpringAnimation()

// デバイスのパフォーマンスクラスを使用(モデルではなく)
if ProcessInfo.processInfo.processorCount >= 6 {
    // 最新のAシリーズ(A14+)
    springAnim.damping = 0.7
    springAnim.stiffness = 100
} else {
    // 古いAシリーズ
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

理由 スプリング物理演算は60Hzと120Hzで異なるフィーリングになります。モデルではなくデバイスクラス(コア数、GPU)を使用してください。


クイックリファレンステーブル

問題確認項目修正方法
完了ハンドラが呼ばれないadd() の前にハンドラが設定されているかcompletion = を add() の前に移動
持続時間のミスマッチCATransaction でラップされているかCATransaction を削除するか、アニメーションをトランザクションから外す
古いデバイスでのカクつき値がハードコーディングされているかProcessInfo でデバイスクラスを判定
アニメーションが消えるisRemovedOnCompletion が true かfalse に設定し、fillMode = .forwards を使用
ジェスチャー + アニメーションのカクつき更新が同期されているかCADisplayLink を使用
複数のアニメーションの競合同じキーか?一意のキーを使用するか、先に removeAnimation() を実行
ハンドラでの weak self完了ハンドラが正しくキャプチャされているか完了ハンドラでは常に [weak self] を使用

30分経っても行き詰まった場合

30分以上経過してもアニメーションがまだ壊れている場合:

止まってください。以下のいずれかの可能性があります:

  1. 必須の手順をスキップした(最も一般的)
  2. 診断出力を誤って解釈した
  3. 症状に合わないパターンを適用した
  4. Instruments によるプロファイリングが必要な5%のエッジケースに該当する

「スキルが機能しなかった」と主張する前の必須チェックリスト

  • 必須の初動診断の4つの診断ブロックすべてを実行した(28-63行目)
  • 診断の正確な出力(ログ、print 文)を貼り付けた
  • 「これが示すこと」(66-72行目)から1つの根本原因を特定した
  • 決定木(91行目以降)から最初に一致するパターンを適用した
  • シミュレータだけでなく、実際のデバイスでパターンをテストした
  • アプリケーションのバックグラウンド移行が完了ハンドラに影響するかどうかを確認した

エスカレーション手順(上記のすべてを実行しても問題が解決しない場合)

  1. Instruments > Core Animation ですべての診断を再度実行する

    • フレームレート、GPU 使用率、CPU 使用率を確認する
    • 正確な診断データを収集する
  2. 収集したデータを構造化して提示する:

問題: [完了ハンドラが呼ばれない / 持続時間のミスマッチ / カクつき / その他]
デバイス: [モデル, iOS バージョン]

診断結果:
- 完了ハンドラの print: [表示される / 表示されない]
- 経過時間 vs 宣言: [数値]
- レイヤー速度: [layer.speed の値]
- アクティブなアニメーション: [キーのリスト]
- isRemovedOnCompletion: [true/false]

Instruments データ:
- フレームレート: [数値]
- GPU 使用率: [数値]
- CPU 使用率: [数値]
- その他の観察結果: [自由記述]

試したパターン: [パターン番号とその結果]
  1. 上記の情報を提供する新しいプロンプトを送信する

禁止

  • ❌ 「うまくいかなかった」とだけ言って新しいプロンプトを開始する(診断データなし)
  • ❌ 実行した診断や試したパターンを記載せずに「もう一度試す」
  • ❌ 問題を理解せずに値をランダムに変更する

Individual skills in this repo

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

IGTA-Tech/claude-skills-research

Use when localizing apps, using String Catalogs, generating type-safe symbols (Xcode 26+), handling plurals, RTL layouts, locale-aware formatting, or migrating from .strings files - comprehensive i18n patterns for Xcode 15-26

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

関連スキル