Communitygithub.com

ComeOnOliver/SwiftUIDebug

Diagnóstico sistemático y flujos de trabajo avanzados para depuración de vistas SwiftUI, incluyendo actualizaciones que no funcionan, problemas intermitentes, dependencias complejas y análisis con Instruments.

¿Qué es SwiftUIDebug?

Este skill proporciona un conjunto estructurado de patrones de diagnóstico para la depuración exhaustiva de problemas en vistas SwiftUI que no se resuelven con técnicas básicas. Está diseñado para desarrolladores que enfrentan fallos intermitentes, dependencias de estado complejas, vistas que se actualizan incorrectamente o rendimiento deficiente. Incluye cinco patrones principales: análisis con `Self._printChanges()`, investigación en profundidad con el instrumento SwiftUI de Xcode, verificación de identidad de vistas (causa común de reseteo de estado y fallos de animación), comprobación de dependencias del entorno y diagnóstico de vistas previas (previews) en Xcode 26. El skill también detalla acciones prohibidas, como adivinar con cambios aleatorios de estado o usar `.id(UUID())` para forzar actualizaciones, ya que ocultan los problemas en lugar de resolverlos. Las instrucciones cubren la configuración del entorno, el uso de comandos de terminal para construir en modo Release y la interpretación de gráficos de causa y efecto en Instruments. Está orientado a plataformas iOS, macOS y iPadOS con SwiftUI, recomendando Xcode 26+ para el instrumento SwiftUI. El objetivo es eliminar la depuración de prueba y error, y garantizar que cada corrección se base en un diagnóstico preciso.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Diagnóstico de Depuración SwiftUI

Cuándo usar este skill de diagnóstico

Usa este skill cuando:

  • La solución básica falló — Aplicaste los patrones del skill axiom-swiftui-debugging pero el problema persiste
  • Self._printChanges() muestra patrones inesperados — La vista se actualiza cuando no debería, o no se actualiza cuando debería
  • Problemas intermitentes — Funciona a veces, falla otras veces ("heisenbug")
  • Cadenas de dependencia complejas — Necesitas rastrear el flujo de datos a través de múltiples vistas/modelos
  • Investigación de rendimiento — Las vistas se actualizan demasiado seguido o tardan demasiado
  • Misterios en la vista previa (preview) — Bloqueos o fallos que no son inmediatamente evidentes

Acciones PROHIBIDAS

Bajo presión, te sentirás tentado a tomar atajos que ocultan problemas en lugar de diagnosticarlos. NUNCA hagas esto:

❌ Adivinar con cambios aleatorios de @State/@Observable

  • "Déjame probar añadiendo @Observable aquí y ver si funciona"
  • "Quizás si cambio esto a @StateObject se soluciona"

❌ Usar .id(UUID()) para forzar actualizaciones

  • Crea una nueva identidad de vista en cada renderizado
  • Destruye la preservación del estado
  • Enmascara la causa raíz

❌ Usar ObservableObject cuando @Observable funcionaría (iOS 17+)

  • Añade complejidad innecesaria
  • Pierdes el seguimiento automático de dependencias

❌ Ignorar problemas intermitentes ("funciona a veces")

  • "Solo lo fusionaré y espero que no ocurra en producción"
  • Intermitente = error sistemático, no aleatoriedad

❌ Enviar sin entender

  • "La corrección funciona, no sé por qué"
  • La producción es demasiado costosa para prueba y error

Pasos Obligatorios Iniciales

Antes de sumergirte en los patrones de diagnóstico, establece el entorno base:

# 1. Verificar la configuración de Instruments
xcodebuild -version  # Debe ser Xcode 26+ para el instrumento SwiftUI

# 2. Compilar en modo Release para perfilado
xcodebuild build -scheme TuEsquema -configuration Release

# 3. Borrar datos derivados si investigas problemas de vista previa
rm -rf ~/Library/Developer/Xcode/DerivedData

Costo de tiempo: 5 minutos Por qué: Una versión incorrecta de Xcode o el modo Debug produce datos de perfilado engañosos


Árbol de Decisión de Diagnóstico

¿Problema de vista SwiftUI después de solución básica?
│
├─ ¿La vista no se actualiza?
│  ├─ Verificación básica: Añadir Self._printChanges() temporalmente
│  │  ├─ Muestra "@self changed" → El valor de la vista cambió
│  │  │  └─ Patrón D1: Analizar qué causó la recreación de la vista
│  │  ├─ Muestra una propiedad de estado específica → Ese estado activó la actualización
│  │  │  └─ Verificar: ¿Debería ese estado activar la actualización?
│  │  └─ Nada registrado → El cuerpo no se está llamando en absoluto
│  │     └─ Patrón D3: Investigación de identidad de vista
│  └─ Avanzado: Usar el instrumento SwiftUI
│     └─ Patrón D2: Investigación con el instrumento SwiftUI
│
├─ ¿La vista se actualiza demasiado seguido?
│  ├─ Patrón D1: Análisis con Self._printChanges()
│  │  └─ Identificar dependencias de estado innecesarias
│  └─ Patrón D2: Instrumento SwiftUI → Gráfico de causa y efecto
│     └─ Rastrear flujo de datos, encontrar dependencias amplias
│
├─ ¿Problemas intermitentes (funciona a veces)?
│  ├─ Patrón D3: Investigación de identidad de vista
│  │  └─ Verificar: ¿Cambia la identidad inesperadamente?
│  ├─ Patrón D4: Verificación de dependencias del entorno
│  │  └─ Verificar: ¿Los valores del entorno cambian con frecuencia?
│  └─ Reproducir en vista previa 30+ veces
│     └─ Si no se puede reproducir: Probablemente problema de sincronización/condición de carrera
│
└─ ¿Bloqueos en vista previa (después de correcciones básicas)?
    ├─ Patrón D5: Diagnóstico de vista previa (Xcode 26)
    │  └─ Verificar botón de diagnóstico, registros de bloqueo
    └─ Si aún falla: Patrón D2 (perfilar compilación de vista previa)

Patrones de Diagnóstico

Patrón D1: Análisis con Self._printChanges()

Costo de tiempo: 5 minutos

Síntoma: Necesitas entender exactamente por qué se ejecuta el cuerpo de la vista

Cuándo usarlo:

  • La vista se actualiza más seguido de lo esperado
  • La vista no se actualiza cuando debería
  • Verificar dependencias después de refactorizar

Técnica:

struct MiVista: View {
    @State private var contador = 0
    @Environment(ModeloApp.self) private var modelo

    var body: some View {
        let _ = Self._printChanges()  // Añadir temporalmente

        VStack {
            Text("Contador: \(contador)")
            Text("Valor del modelo: \(modelo.valor)")
        }
    }
}

Interpretación de la salida:

# Escenario 1: El parámetro de la vista cambió
MiVista: @self changed
→ El padre pasó una nueva instancia de MiVista
→ Verificar el código del padre: ¿qué activó la recreación?

# Escenario 2: Una propiedad de estado cambió
MiVista: contador changed
→ El @State local activó la actualización
→ Esperado si modificaste el contador

# Escenario 3: Una propiedad del entorno cambió
MiVista: @self changed  # El entorno es parte de @self
→ Un valor del entorno cambió (esquema de color, configuración regional, valor personalizado)
→ Patrón D4: Verificar dependencias del entorno

# Escenario 4: Nada registrado
→ El cuerpo no se está llamando
→ Patrón D3: Investigación de identidad de vista

Descubrimientos comunes:

  1. "@self changed" cuando no lo esperas

    • El padre recrea la vista innecesariamente
    • Verificar la gestión de estado del padre
  2. La propiedad cambió pero no la cambiaste

    • Dependencia indirecta (leyendo de un objeto que cambió)
    • Patrón D2: Usar Instruments para rastrear
  3. Múltiples propiedades cambiando juntas

    • Dependencia amplia (ej., leyendo todo un arreglo cuando solo necesitas un elemento)
    • Corrección: Extraer dependencia específica

Verificación:

  • Eliminar la llamada a Self._printChanges() antes de hacer commit
  • Nunca enviar a producción con este código

Referencia cruzada: Para casos complejos, usar Patrón D2 (Instrumento SwiftUI)


Patrón D2: Investigación con el Instrumento SwiftUI

Costo de tiempo: 25 minutos

Síntoma: Patrones de actualización complejos que Self._printChanges() no puede explicar completamente

Cuándo usarlo:

  • Múltiples vistas se actualizan cuando solo una debería
  • Necesitas rastrear el flujo de datos a través de la aplicación
  • Las vistas se actualizan pero no sabes qué dato las activó
  • Actualizaciones largas del cuerpo de la vista (problema de rendimiento)

Requisitos previos:

  • Xcode 26+ instalado
  • Dispositivo actualizado a iOS 26+ / macOS Tahoe+
  • Compilar en modo Release

Pasos:

1. Iniciar Instruments (5 min)

# Compilar Release
xcodebuild build -scheme TuEsquema -configuration Release

# Iniciar Instruments
# Presiona Comando-I en Xcode
# Elige la plantilla "SwiftUI"

2. Grabar traza (3 min)

  • Haz clic en el botón Grabar
  • Realiza la acción que activa las actualizaciones inesperadas
  • Detén la grabación (10-30 segundos de interacción son suficientes)

3. Analizar actualizaciones largas del cuerpo de la vista (5 min)

  • Mira en el carril Long View Body Updates
  • ¿Hay barras naranjas/rojas? Esas son vistas costosas
  • Haz clic en una actualización larga → El panel de detalle muestra el nombre de la vista
  • Haz clic derecho → "Establecer rango de inspección y acercar"
  • Cambia a la pista Time Profiler
  • Encuentra tu vista en la pila de llamadas
  • Identifica la operación costosa (creación de formateador, cálculo, etc.)

Corrección: Mueve la operación costosa a la capa del modelo, almacena en caché el resultado

4. Analizar actualizaciones innecesarias (7 min)

  • Resalta el rango de tiempo de la acción del usuario (ej., tocar botón de favorito)
  • Expande la jerarquía en el panel de detalle
  • Cuenta las actualizaciones — ¿más de las esperadas?
  • Pasa el cursor sobre la vista → Haz clic en la flecha → "Mostrar gráfico de causa y efecto"

5. Interpretar el gráfico de causa y efecto (5 min)

Nodos del gráfico:

[Nodo azul] = Tu código (gesto, cambio de estado, cuerpo de vista)
[Nodo del sistema] = SwiftUI/trabajo del sistema
[Flecha etiquetada "update"] = Causó esta actualización
[Flecha etiquetada "creation"] = Causó que la vista apareciera

Patrones comunes:

# Patrón A: Una sola vista se actualiza (BUENO)
[Gesto] → [Cambio de estado en ViewModelA] → [Cuerpo de VistaA]

# Patrón B: Todas las vistas se actualizan (MALO - dependencia amplia)
[Gesto] → [Cambio de arreglo] → [Todas las vistas de elementos de la lista se actualizan]
└─ Corrección: Usar modelos de vista granulares, uno por elemento

# Patrón C: Cascada a través del entorno (VERIFICAR)
[Cambio de estado] → [Escritura en entorno] → [Muchos cuerpos de vista verifican]
└─ Si el valor del entorno cambia con frecuencia → Corrección del Patrón D4

Haz clic en los nodos:

  • Nodo de cambio de estado → Ver el backtrace de dónde se estableció el valor
  • Nodo de cuerpo de vista → Ver qué propiedades leyó (dependencias)

Verificación:

  • Grabar una nueva traza después de la corrección
  • Comparar conteos de actualizaciones antes/después
  • Verificar que las barras rojas/naranjas se redujeron o eliminaron

Referencia cruzada: Skill axiom-swiftui-performance para flujos de trabajo detallados con Instruments


Patrón D3: Investigación de Identidad de Vista

Costo de tiempo: 15 minutos

Síntoma: Los valores de @State se restablecen inesperadamente, o las vistas no animan

Cuándo usarlo:

  • El contador se restablece a 0 cuando no debería
  • Las animaciones no funcionan (la vista aparece de golpe en lugar de animarse)
  • Los elementos de ForEach saltan
  • El campo de texto pierde el foco

Causa raíz: La identidad de la vista cambió inesperadamente

Pasos de investigación:

1. Verificar colocación condicional (5 min)

// ❌ PROBLEMA: La identidad cambia con la condición
if mostrarDetalles {
    VistaContador()  // Obtiene nueva identidad cada vez que se alterna mostrarDetalles
}

// ✅ CORRECCIÓN: Usar .opacity()
VistaContador()
    .opacity(mostrarDetalles ? 1 : 0)  // Siempre la misma identidad

Encontrar: Busca en el código base vistas dentro de if/else que mantienen estado

2. Verificar modificadores .id() (5 min)

// ❌ PROBLEMA: .id() cambia cuando los datos cambian
VistaDetalle()
    .id(elemento.id + "-\(estáEditando)")  // ID cambia con estáEditando

// ✅ CORRECCIÓN: ID estable
VistaDetalle()
    .id(elemento.id)  // ID estable

Encontrar: Busca en el código base .id( — verifica si los valores de ID cambian

3. Verificar identificadores de ForEach (5 min)

// ❌ INCORRECTO: ID basado en índice
ForEach(Array(elementos.enumerated()), id: \.offset) { indice, elemento in
    Text(elemento.nombre)
}

// ❌ INCORRECTO: ID no único
ForEach(elementos, id: \.categoria) { elemento in  // Múltiples elementos por categoría
    Text(elemento.nombre)
}

// ✅ CORRECTO: ID único y estable
ForEach(elementos, id: \.id) { elemento in
    Text(elemento.nombre)
}

Encontrar: Busca ForEach — verifica IDs únicas y estables

Patrones de corrección:

ProblemaCorrección
Vista en condicionalUsar .opacity() en su lugar
.id() cambia demasiado seguidoUsar identificador estable
ForEach saltandoUsar IDs únicas y estables (UUID o ID del servidor)
Estado se restablece en navegaciónVerificar gestión de la ruta de NavigationStack

Verificación:

  • Añadir Self._printChanges() — NO deberías ver "@self changed" repetidamente
  • Las animaciones deberían funcionar sin problemas
  • Los valores de @State deberían persistir

Patrón D4: Verificación de Dependencias del Entorno

Costo de tiempo: 10 minutos

Síntoma: Muchas vistas se actualizan cuando cambian datos no relacionados

Cuándo usarlo:

  • El gráfico de causa y efecto muestra un nodo "Environment" que activa muchas actualizaciones
  • Rendimiento lento en desplazamiento o animaciones
  • Actualizaciones en cascada inesperadas

Causa raíz: Un valor que cambia con frecuencia en el entorno O demasiadas vistas leyendo el entorno

Pasos de investigación:

1. Encontrar escrituras en el entorno (3 min)

# Buscar modificadores de entorno en el proyecto actual
find . -name "*.swift" -exec grep -l "\.environment(" {} \;

Buscar:

// ❌ MALO: Valores que cambian con frecuencia
.environment(\.desplazamientoScroll, desplazamientoScroll)  // Se actualiza 60+ veces/segundo
.environment(modelo)  // Si el modelo se actualiza con frecuencia

// ✅ BUENO: Valores estables
.environment(\.esquemaColor, .oscuro)
.environment(modeloApp)  // Si modeloApp cambia raramente

2. Verificar qué hay en el entorno (3 min)

Usando el Patrón D2 (Instruments), verifica el gráfico de causa y efecto:

  • Haz clic en el nodo "Environment"
  • Mira qué propiedades cambiaron
  • Cuenta cuántas vistas verificaron si hay actualizaciones

Preguntas:

  • ¿Este valor cambia en cada fotograma de desplazamiento/animación?
  • ¿Todas estas vistas realmente necesitan este valor?

3. Aplicar corrección (4 min)

Corrección A: Eliminar del entorno (si cambia con frecuencia):

// ❌ Antes: Entorno
.environment(\.desplazamientoScroll, desplazamientoScroll)

// ✅ Después: Parámetro directo
VistaHija(desplazamientoScroll: desplazamientoScroll)

Corrección B: Usar modelo @Observable (si lo necesitan muchas vistas):

// En lugar de almacenar un primitivo en el entorno:
@Observable class ModeloScrollView {
    var desplazamiento: CGFloat = 0
}

// Las vistas dependen de propiedades específicas:
@Environment(ModeloScrollView.self) private var modeloVista

var body: some View {
    Text("\(modeloVista.desplazamiento)")  // Solo se actualiza cuando cambia el desplazamiento
}

Verificación:

  • Grabar una nueva traza en Instruments
  • Verificar el gráfico de causa y efecto — menos vistas deberían actualizarse
  • El rendimiento debería mejorar (desplazamiento/animaciones más suaves)

Patrón D5: Diagnóstico de Vista Previa (Xcode 26)

Costo de tiempo: 10 minutos

Síntoma: La vista previa no carga o se bloquea con un error poco claro

Cuándo usarlo:

  • La vista previa falla después de correcciones básicas (skill swiftui-debugging)
  • El mensaje de error es poco claro o genérico
  • La vista previa funcionaba antes, dejó de funcionar repentinamente

Pasos de investigación:

1. Usar el botón de Diagnóstico de Vista Previa (2 min)

Ubicación: Menú Editor → Canvas → Diagnostics

Qué muestra:

  • Mensajes de error detallados
  • Dependencias faltantes
  • Problemas de inicialización de estado
  • Problemas específicos de vista previa

2. Verificar registros de bloqueo (3 min)

# Abrir el directorio de registros de bloqueo
open ~/Library/Logs/DiagnosticReports/

# Buscar archivos .crash recientes que contengan "Preview"
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5

Qué buscar:

  • Errores fatales (arreglo fuera de límites, force unwrap nil)
  • Importaciones de módulos faltantes
  • Fallos de inicialización del framework

3. Aislar el problema (5 min)

Crear vista previa mínima:

// Comenzar con una vista previa vacía
#Preview {
    Text("Prueba")
}

// Si esto funciona, añadir gradualmente:
#Preview {
    MiVista()  // Tu vista real, pero con datos simulados
        .environment(ModeloSimulado())  // Proporcionar todas las dependencias
}

// Encontrar qué dependencia causa el bloqueo

Problemas comunes:

ErrorCausaCorrección
"Cannot find in scope"Dependencia faltanteAñadir a la vista previa (ver ejemplo abajo)
"Fatal error: Unexpectedly found nil"Optional unwrap fallidoProporcionar valor no nil en la vista previa
"No such module"Importación faltanteAñadir declaración import
Bloqueo silencioso (sin error)Inicialización de estado con valor inválidoUsar valores predeterminados seguros

Patrones de corrección:

// @Environment faltante
#Preview {
    VistaPrincipal()
        .environment(ModeloApp())  // Proporcionar dependencia
}

// @EnvironmentObject faltante (pre-iOS 17)
#Preview {
    VistaPrincipal()
        .environmentObject(ModeloApp())
}

// ModelContainer faltante (SwiftData)
#Preview {
    let config = ModelConfiguration(isStoredInMemoryOnly: true)
    let container = try! ModelContainer(for: ModeloElemento.self, configurations: config)
    VistaListaElementos()
        .modelContainer(container)
}

Verificación:

  • La vista previa debería cargarse y mostrarse correctamente
  • Interactúa con ella 10+ veces para verificar estabilidad

Referencia cruzada: Patrón D2 (Instrumento SwiftUI) para vista previa con perfilado de rendimiento

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

Skills relacionados