Communitygithub.com

UIKit 애니메이션 디버깅

CAAnimation 완료 핸들러가 실행되지 않거나, 실제 기기에서 스프링 물리 효과가 부자연스럽거나, 애니메이션 지속 시간이 실제 시간과 다르거나, 제스처와 애니메이션 상호작용이 끊기거나, 시뮬레이터와 실제 하드웨어 간 타이밍이 다를 때 사용합니다. CATransaction 패턴, 프레임 레이트 인식, 기기별 동작을 포함한 체계적인 CAAnimation 진단을 제공합니다.

UIKit 애니메이션 디버깅란 무엇인가요?

이 스킬은 UIKit에서 CAAnimation 문제를 체계적으로 진단하고 해결하는 방법을 제공합니다. CAAnimation 문제의 90%는 Core Animation 버그가 아니라 CATransaction 타이밍, 레이어 상태, 또는 프레임 레이트 가정으로 인해 발생한다는 핵심 원칙을 기반으로 합니다. 완료 핸들러가 실행되지 않거나, 애니메이션 지속 시간이 잘못되었거나, 스프링 물리 효과가 기기마다 다르거나, 제스처와 애니메이션이 함께 사용될 때 끊김 현상이 발생하는 경우에 유용합니다. 이 스킬은 시뮬레이터와 실제 기기 간의 타이밍 차이를 강조하며, 코드 변경 전에 반드시 실제 기기에서 테스트할 것을 요구합니다. 또한, 4가지 진단 블록을 먼저 실행하고, 의사 결정 트리와 7가지 패턴을 사용하여 문제를 단계별로 해결하도록 안내합니다. 특히 `[weak self]` 사용을 강제하고, 하드코딩된 지속 시간 값을 금지하며, 진단 출력을 정확히 해석하지 않고 무작정 패턴을 적용하는 것을 금지합니다.

지원 대상✓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]를 사용하고 있고, 그 이유를 확신하지 못함
  • ❌ 금지: "실제 동작과 일치하도록" 지속 시간/값을 하드코딩하는 행위
    • 이는 다른 하드웨어를 사용하는 사용자에게 기기별 버그를 배포하는 것입니다.
    • 이를 "임시 수정" 또는 "충분히 좋은" 방법이라고 합리화하지 마십시오.

중요한 차이점: 시뮬레이터는 종종 타이밍 문제를 숨깁니다(60Hz만 지원, 조절 없음). 실제 기기는 이를 드러냅니다(가변 프레임 레이트, CPU 조절, 백그라운드 압력). 필수: 배포 전에 반드시 실제 기기(지원되는 가장 오래된 모델)에서 테스트하세요.

필수 첫 번째 단계

항상 다음을 먼저 실행하세요 (코드 변경 전):

// 1. 완료 핸들러가 실행되는지 확인
animation.completion = { [weak self] finished in
    print("🔥 COMPLETION FIRED: finished=\(finished)")
    guard let self = self else {
        print("🔥 SELF WAS 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("Elapsed: \(Date().timeIntervalSince(startTime))")  // 실제
}

// 3. 활성 애니메이션 확인
if let keys = layer.animationKeys() {
    print("Active animations: \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key): duration=\(anim.duration), removed=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. 레이어 상태 확인
print("Layer speed: \(layer.speed)")  // != 1.0이면 타이밍이 조정된 것
print("Layer timeOffset: \(layer.timeOffset)")  // != 0이면 애니메이션이 오프셋된 것

이 정보가 알려주는 것

  • 완료 출력 나타남 → 핸들러 실행됨, 문제는 콜백 코드에 있음
  • 완료 출력 없음 → 핸들러 실행되지 않음, CATransaction/레이어 상태 확인
  • 경과 시간 == 선언된 시간 → 지속 시간은 정확, 시각적 끊김은 프레임 문제
  • 경과 시간 != 선언된 시간 → CATransaction 래핑이 지속 시간을 변경함
  • layer.speed != 1.0 → 애니메이션을 늦추는 무언가가 있음
  • 활성 애니메이션 목록이 긺 → 여러 애니메이션이 경쟁함

필수 해석

코드를 변경하기 전에 다음 중 어떤 진단이 근본 원인인지 반드시 식별해야 합니다:

  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) 대 기기 프레임 레이트(120Hz). 실제 하드웨어에 맞게 다시 계산하세요.
│
├─ 기기에서 스프링 물리 효과가 잘못됩니까?
│  ├─ 값이 하나의 기기에 하드코딩되었습니까?
│  │  └─ 모델이 아닌 기기 성능 클래스를 사용하세요.
│  ├─ 감쇠/강성 값이 질량/강성과 바뀌었습니까?
│  │  └─ CASpringAnimation 매개변수 의미를 확인하세요.
│  └─ 시뮬레이터에서는 작동하지만 기기에서는 작동하지 않습니까?
│     └─ 시뮬레이터는 60Hz를 사용합니다. 기기는 120Hz를 사용할 수 있습니다. 다시 계산하세요.
│
└─ 제스처 + 애니메이션 끊김?
   ├─ 애니메이션이 경쟁하고 있습니까(동일한 keyPath)?
   │  └─ 새 애니메이션을 추가하기 전에 이전 애니메이션을 제거하세요.
   ├─ 제스처가 애니메이션 실행 중에 레이어를 업데이트합니까?
   │  └─ 동기화된 업데이트를 위해 CADisplayLink를 사용하세요.
   └─ 제스처가 메인 스레드를 차단하고 있습니까?
      └─ Instruments > Core Animation으로 프로파일링하세요.

일반적인 패턴

패턴 선택 규칙 (필수)

한 번에 하나의 패턴을 다음 순서로 적용하세요

  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("Done")
}

✅ 올바름 (추가 전에 핸들러 설정)

animation.completion = { [weak self] finished in
    print("🔥 Animation finished: \(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: 완료 핸들러에서 Weak Self (필수)

❌ 금지 (Strong self는 순환 참조 생성)

anim.completion = { finished in
    self.property = "value"  // ❌ 확정적인 순환 참조
}

✅ 필수 (항상 weak self 사용)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "value"  // 안전하게 접근
}

이것이 선택 사항이 아닌 필수인 이유

  • CAAnimation은 애니메이션이 완료될 때까지 완료 핸들러를 유지합니다.
  • 완료 핸들러는 self를 강하게 캡처합니다(명시적으로 weak로 하지 않는 한).
  • 순환 참조 생성: self → animation → completion → 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: 스프링 애니메이션 기기 차이

❌ 잘못됨 (하나의 기기에 하드코딩)

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?false로 설정, fillMode = .forwards 사용
제스처 + 애니메이션 끊김동기화된 업데이트?CADisplayLink 사용
여러 애니메이션 충돌동일한 키?고유 키 사용 또는 removeAnimation() 먼저 호출
핸들러에서 Weak self완료 핸들러가 올바르게 캡처되었습니까?완료 핸들러에서 항상 [weak self] 사용

30분 후에도 막혔을 때

30분 이상 애니메이션이 여전히 고장나 있다면:

중단하세요. 다음 중 하나일 가능성이 높습니다.

  1. 필수 단계를 건너뛰었습니다(가장 흔함).
  2. 진단 출력을 잘못 해석했습니다.
  3. 증상에 맞지 않는 잘못된 패턴을 적용했습니다.
  4. Instruments 프로파일링이 필요한 5%의 특수한 경우에 해당합니다.

"스킬이 작동하지 않았다"고 주장하기 전 필수 체크리스트

  • 필수 첫 번째 단계(라인 28-63)의 4가지 진단 블록을 모두 실행했습니다.
  • 진단 결과(로그, print 문)의 정확한 출력을 붙여넣었습니다.
  • "이 정보가 알려주는 것"(라인 66-72)에서 하나의 근본 원인을 식별했습니다.
  • 의사 결정 트리(라인 91+)에서 첫 번째로 일치하는 패턴을 적용했습니다.
  • 시뮬레이터가 아닌 실제 기기에서 패턴을 테스트했습니다.
  • [ ]

...

[번역을 위해 잘림]

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.

관련 스킬