Crear apps para iOS con agentes de IA: guía práctica

TL;DR: Tres entornos de ejecución de agentes ya entregan código para iOS: Claude Code CLI con MCP, Codex CLI con MCP, y los agentes nativos de Intelligence de Xcode: Agent de Claude, Codex y, desde Xcode 26.6, Google Gemini o cualquier agente de Agent Client Protocol (ACP).¹⁷ Dos servidores MCP (XcodeBuildMCP con 82 herramientas y xcrun mcpbridge de Apple con 20 herramientas) brindan a los agentes acceso estructurado a compilaciones, pruebas, simuladores y depuración. Esta guía cubre patrones reales de CLAUDE.md, configuraciones de hooks y evaluaciones honestas sobre lo que funciona y lo que se rompe, a partir de 8 apps de iOS en producción que suman 293 archivos Swift.³² Los agentes destacan en vistas SwiftUI, modelos SwiftData, refactorización y diagnóstico de errores de compilación. Fallan en modificaciones de .pbxproj, firma de código y depuración visual. La brecha entre «el agente escribe Swift» y «el agente entrega una app de iOS» se salva mediante la configuración, no mediante prompts. Desde WWDC 2026 (8 de junio), iOS 27 está en beta — beta 5 (24A5408d) al 10 de agosto — y añade frameworks relevantes para agentes (control de llamadas a herramientas de Foundation Models, ejecución en segundo plano de App Intents y los nuevos frameworks Core AI y Evaluations) que vale la pena nombrar en el contexto de tu agente, ya que un modelo entrenado antes de junio de 2026 no los conocerá. Xcode 26.6 (2026-06-25, Swift 6.3) es la cadena de herramientas estable actual; la beta de Xcode 27 (Swift 6.4, iOS 27 SDKs) sigue el ciclo de iOS 27.¹⁷¹⁸

He creado 8 apps de iOS con agentes de programación de IA. No son prototipos: son apps en la App Store, con integraciones de HealthKit, shaders de Metal, física de SpriteKit, sincronización con iCloud, Live Activities, clasificaciones de Game Center y destinos multiplataforma que abarcan iOS, watchOS y tvOS. Cada línea de Swift en estas apps fue escrita por un agente y revisada por mí, o escrita por mí y refactorizada por un agente. Según mi estimación, los agentes se encargaron de la mayor parte de la autoría a nivel de línea; yo me encargué de la revisión, el alcance y las partes que requieren criterio humano (pulido visual, firma, ajuste de rendimiento y envío a la App Store).

Esta guía es la referencia que me habría gustado tener cuando empecé. Cubre toda la pila: qué entorno de ejecución de agentes usar, cómo configurar servidores MCP para tener acceso estructurado a la compilación, qué incluir en tu CLAUDE.md, qué hooks evitan que el agente destruya tu proyecto de Xcode y, fundamentalmente, dónde fallan los agentes y necesitas tomar el control.

Conclusiones clave

Para desarrolladores de iOS que se inician en los agentes de IA:

• Empieza con Claude Code CLI + XcodeBuildMCP. Es el entorno más maduro y el que ofrece la cobertura de herramientas MCP más profunda. Instala dos comandos, agrega un CLAUDE.md a tu proyecto y el agente podrá compilar, probar y depurar sin que tengas que copiar mensajes de error.
• Nunca dejes que un agente modifique .pbxproj. Esta es la regla más importante. Un hook PreToolUse que bloquee escrituras en .pbxproj y .xcodeproj/ te ahorrará horas de recuperación.
• Tu CLAUDE.md es el documento de incorporación del agente. Las horas que dediques a este archivo se amortizan en cada sesión de agente que toque el proyecto.

Para usuarios experimentados de agentes que incorporan iOS a su flujo de trabajo:

• MCP transforma el ciclo de compilación de iOS. Antes de MCP, los agentes escribían Swift, pero no podían verificar que compilara. Con XcodeBuildMCP, el agente escribe código, lo compila, lee errores estructurados, los corrige y ejecuta pruebas de forma autónoma.
• Tres entornos cubren necesidades distintas. Claude Code CLI para sesiones agentivas profundas, Codex CLI para trabajo por lotes sin interfaz, y los propios agentes de Xcode, que dejaron de ser una herramienta de correcciones en línea en Xcode 27, donde obtuvieron plug-ins, servidores MCP y la capacidad de controlar simuladores.²²
• La infraestructura de hooks se conserva. Tus formateadores PostToolUse, bloqueadores PreToolUse y hooks de ejecución de pruebas existentes funcionan de forma idéntica en proyectos de iOS con pequeños ajustes de rutas.

Para líderes de equipo que evalúan el desarrollo de iOS asistido por IA:

• La efectividad de los agentes escala con la documentación del proyecto, no con su tamaño. Una app de 63 archivos con un CLAUDE.md detallado produce mejores resultados de agentes que una app de 14 archivos sin uno.
• El límite de .pbxproj no es negociable. Los agentes no pueden editar de forma confiable los archivos de proyecto de Xcode. Tu flujo de trabajo debe contemplar la adición manual de archivos a los destinos de Xcode.
• Evaluación honesta ROI: los agentes se encargan de la mayor parte de la implementación en proyectos bien documentados — como se ve en la app de TV de 15 archivos entregada en 3 horas de trabajo asistido por agentes (caso de estudio más abajo). El trabajo restante — pulido visual, firma, ajuste de rendimiento y envío a la App Store — requiere criterio humano.

Elige tu ruta

Cómo usar esta guía

Esta es una referencia de más de 3.000 líneas. Empieza donde encaje tu nivel de experiencia:

Tabla de contenido

1. El portafolio: 8 apps, 293 archivos
2. Requisitos previos
3. Tres entornos de agentes para iOS
4. Configuración de MCP: la configuración completa
5. Patrones de CLAUDE.md para proyectos de iOS
6. Tu primera sesión con un agente
7. En qué destacan los agentes en iOS
8. En qué fallan los agentes en iOS
9. Hooks para desarrollo de iOS
10. Patrones de arquitectura que funcionan con agentes
11. Contexto específico de frameworks
12. Patrones multiplataforma
13. Flujos de trabajo avanzados
14. Casos de estudio del mundo real
15. Ciclo de vida del proyecto con agentes
16. Configuración de definiciones de agentes
17. Patrones de pruebas para iOS asistido por agentes
18. Gestión de la ventana de contexto para proyectos de iOS
19. Resolución de problemas
20. Errores comunes de los agentes en iOS y cómo prevenirlos
21. La evaluación honesta
22. Preguntas frecuentes
23. Tarjeta de referencia rápida
24. Referencias

Recursos relacionados

Serie del ecosistema Apple. 21 publicaciones de producción sobre apps SwiftUI que se integran con Apple Intelligence, MCP, Foundation Models, Vision, Core ML y la pila de frameworks de iOS 26. Extraídas de Water, Get Bananas, Return y el resto del portafolio 941:

Centro de la serie: Serie del ecosistema Apple

Apple agéntico (E4):

Frameworks (E2/E3):

Código entregado (E1):

Síntesis (E5):

iOS 27 y WWDC 2026: con qué construye ahora tu agente

WWDC 2026 (8 de junio de 2026) puso iOS 27 en beta. El flujo de desarrollo con agentes de esta guía no cambia: sigues dirigiendo Claude Code, Codex o los agentes Intelligence de Xcode mediante MCP, sigues escribiendo un CLAUDE.md y sigues protegiendo las operaciones destructivas con hooks. Lo que cambia es la superficie sobre la que escribe tu agente. iOS 27 incorpora varios frameworks nuevos relevantes para agentes, y lo práctico es dirigir tu agente de programación hacia ellos de forma deliberada, porque un modelo entrenado antes de junio de 2026 no sabrá que existen. iOS 26 sigue siendo la versión publicada; considera los elementos siguientes como objetivos para cuando desarrolles con la beta de iOS 27 SDK.

La superficie de iOS 27 relevante para agentes, cada una con una referencia detallada:

• Foundation Models obtuvo control de llamadas a herramientas. GenerationOptions.ToolCallingMode te permite orientar cuán agresivamente el modelo en el dispositivo llama herramientas en cada solicitud, y el framework puede cambiar de modo después de la primera llamada para limitar la actividad de herramientas de una solicitud. El framework Vision ahora incluye OCRTool y BarcodeReaderTool listos para usar, que conectas a una LanguageModelSession sin escribir el código de reconocimiento. Consulta Foundation Models en iOS 27: control de llamadas a herramientas.¹²
• App Intents superó la barrera de los 30 segundos. LongRunningIntent (mediante performBackgroundTask(options:operation:), que requiere informar el progreso) amplía el tiempo de ejecución en segundo plano de un intent para sincronización, trabajo con archivos e inferencia en el dispositivo; SyncableEntity le da a un AppEntity una identidad entre dispositivos; IndexedEntityQuery permite que el sistema solicite a tu consulta reparar su índice de Spotlight. Consulta App Intents en iOS 27: segundo plano, sincronización y Spotlight.¹³
• Core AI es un nuevo framework para ejecutar modelos en Apple Silicon. Se encuentra por debajo de Foundation Models para los casos en los que aportas tu propio modelo en lugar de usar el modelo de sistema de Apple. Consulta Core AI: ejecución de modelos en Apple Silicon.¹⁴
• Evaluations es XCTest para la calidad de los modelos. Un nuevo framework (macOS 27) para medir la calidad de las salidas de un modelo como parte de tu suite de pruebas, la pieza que faltaba para lanzar funciones de IA que un agente te ayudó a construir. Consulta Evaluations: XCTest para la calidad de los modelos.¹⁵
• SwiftData, HealthKit y SwiftUI también avanzaron. SwiftData añade observación e historial en iOS 27; HealthKit añade zonas de entrenamiento y tipos nuevos; las incorporaciones de SwiftUI en iOS 27 abarcan, como de costumbre, una superficie amplia. Consulta SwiftData en iOS 27, HealthKit en iOS 27 y Novedades de SwiftUI para iOS 27.¹⁶

La cadena de herramientas para trabajar con iOS 27 es la beta de Xcode 27. Xcode 27 se lanzó como beta el primer día de WWDC (8 de junio, compilación 27A5194q) y está en la beta 5 al 10 de agosto (27A5237l). Incluye Swift 6.4 y los SDKs de iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27, y requiere macOS Tahoe 26.4 o una versión posterior.¹⁸ Cuatro elementos de las notas de la versión importan para los flujos de trabajo con agentes: Coding Intelligence incorpora un modo de planificación; las notas lo muestran mediante un problema conocido con la barra de confirmación «Implement the plan?» (178673449), así que espera a que el agente termine de transmitir antes de confirmar o descartar un plan; la herramienta MCP RenderPreview ahora renderiza grupos de Preview (174692209) y puede previsualizar tu UI en otra localización (181040291); la herramienta orientada a agentes «Prepare Project for Localization» ahora informa las claves de String Catalog eliminadas porque ya no aparecen en el código fuente (179755385); y Address Sanitizer puede no iniciarse en destinos 27.0 cuando la app se compiló con Xcode 26.4 o anterior; usa Xcode 26.5+ para ejecuciones de ASan (178072780).¹⁸ La beta 5 añade dos elementos más que importan aquí. Ahora los agentes pueden verificar apps de watchOS, «including rotating and pressing the Digital Crown, and pressing the side and Action buttons (Apple Watch Ultra)» (181147968): la primera vez que los agentes de Apple pueden interactuar con las entradas físicas de una app de watch, lo que cierra parte de la brecha de verificación visual que documenta esta guía. Además, Apple presentó un servidor MCP que ya no necesita tener Xcode abierto; consulta la sección sobre el servidor MCP de Apple más abajo.²² Las herramientas MCP también se han puesto al día con la beta: XcodeBuildMCP v2.7.0 (2026-07-23) hizo que sus herramientas de automatización de UI funcionaran por completo con los simuladores de Xcode 27 mediante Device Hub, incluido el inicio de ventanas del simulador y los controles de teclado; antes de esa versión, la automatización de UI en tiempo de ejecución solo era fiable con simuladores de Xcode 26, lo que hacía que la verificación de UI impulsada por agentes en la beta de iOS 27 fuera una tarea manual.²¹

La lección para quien opera el flujo es la misma que plantea el resto de esta guía: el agente escribe el código, pero tú aportas el conocimiento que le falta. Para las betas de iOS 27, eso implica mencionar estos frameworks en tu prompt o CLAUDE.md y enlazar al agente a la documentación de Apple, porque de lo contrario el modelo recurrirá a la forma que tenía cada API en iOS 26. Todo lo demás de esta guía (runtimes, MCP, hooks y modos de fallo) se mantiene sin cambios para el trabajo con iOS 27.

El portafolio: 8 apps, 293 archivos

Antes de entrar en la configuración, esto es de donde surge esta guía. No son proyectos de juguete: abarcan cinco frameworks de Apple, tres plataformas y toda la gama de complejidad de iOS, desde un rastreador de entrenamientos de 14 archivos hasta un temporizador de meditación multiplataforma de 63 archivos.

Por qué importan los recuentos de archivos: La eficacia de los agentes se correlaciona con la legibilidad del proyecto, no con su tamaño. Return (63 archivos) produce mejores resultados de agentes que amp97 (41 archivos) porque Return tiene un CLAUDE.md detallado con anotaciones de archivos, diagramas de arquitectura y patrones explícitos. Los shaders de Metal de amp97 son intrínsecamente más difíciles de razonar para los agentes, independientemente de la calidad de la documentación.

Requisitos previos

Antes de configurar cualquier runtime de agente para el desarrollo de iOS:

Fecha límite de App Store Connect: A partir del 2026-04-28, las cargas de apps a App Store Connect deben compilarse con Xcode 26 o posterior utilizando SDKs para iOS 26, iPadOS 26, tvOS 26, visionOS 26 o watchOS 26.²⁶ (Los envíos de macOS no están incluidos en este requisito). Si tu equipo sigue usando Xcode 16.x, la cadena de herramientas asistida por agentes de esta guía funciona también como un impulsor del cambio: ninguno de los servidores MCP siguientes funciona sin Xcode 26.3+ de todos modos.

Obligatorio: - macOS 15+ (Sequoia) o macOS Tahoe (Xcode 26.6 requiere macOS Tahoe 26.2+; la beta de Xcode 27 requiere Tahoe 26.4+) - Xcode 26.3+ instalado y configurado (el mínimo para xcrun mcpbridge); se recomienda Xcode 26.6+. Xcode 26.6 (2026-06-25, compilación 17F113) es la última versión estable e incorpora tres cambios de Coding Intelligence relevantes para agentes: Google Gemini como proveedor de asistente de programación, compatibilidad con Agent Client Protocol (ACP) y renderizado de variantes —claro/oscuro, orientación, tamaños de texto— en la herramienta de Preview MCP; también corrige dos fallos durante turnos de agentes y el bloqueo cuando un agente hace una pregunta, e incluye Swift 6.3 con los SDKs de la generación iOS 26.5.¹⁷ Las mejoras de flujo de trabajo de 26.5 —colas de mensajes en el asistente de programación y compatibilidad con preguntas de aclaración—, así como los adjuntos de imágenes de Swift Testing de 26.4, la gravedad de incidencias registradas, las advertencias de fallos en pruebas de UI con crashlogs y las mejoras del editor de String Catalog, también se mantienen.²⁷²⁸ Versiones estables anteriores: 26.5 (2026-05-11, compilación 17F42) y 26.4.1 (2026-04-16, compilación 17E202).²⁹ - Al menos un runtime de iOS Simulator instalado - Una cuenta de Anthropic API (para Claude Code) o una cuenta de OpenAI (para Codex)

Recomendado: - SwiftFormat instalado (brew install swiftformat): se usa en hooks de formato al guardar - SwiftLint instalado (brew install swiftlint): opcional, pero útil para aplicar el estilo - Familiaridad con la terminal: los tres runtimes funcionan desde la línea de comandos o se integran con ella

Verifica tu instalación de Xcode:

# Check Xcode version
xcodebuild -version
# Expected: Xcode 26.3 or later (26.6+ recommended)

# Check available simulators
xcrun simctl list devices available
# Expected: at least one iPhone simulator

# Verify xcrun mcpbridge is available
xcrun mcpbridge --help
# Expected: usage information (not "command not found")

Si xcrun mcpbridge devuelve «command not found», necesitas Xcode 26.3 o posterior. Instala o actualiza Xcode mediante App Store o developer.apple.com. Nota: xcode-select --install solo instala Command Line Tools, que no incluyen mcpbridge; necesitas la aplicación Xcode.app completa.

Tres entornos de ejecución de agentes para iOS

Tres entornos de ejecución distintos pueden escribir, compilar y probar código de iOS. No son intercambiables: cada uno tiene fortalezas diferentes, patrones de integración de MCP distintos y casos de uso ideales diferentes.

1. Claude Code CLI

Qué es: El asistente de programación agéntico basado en terminal de Anthropic. Lee tu base de código, ejecuta comandos, modifica archivos y se conecta a herramientas externas mediante MCP.⁷

**Integración de MCP: ** Compatibilidad total tanto con XcodeBuildMCP como con el MCP de Xcode de Apple. El agente descubre herramientas mediante el protocolo MCP y las llama con parámetros estructurados. 82 + 20 herramientas entre ambos servidores.

Configuración:

# Install Claude Code (if not already installed)
claude --version  # verify installation

# Add XcodeBuildMCP (82 tools — builds, tests, simulators, debugging)
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Add Apple Xcode MCP (20 tools — file ops, diagnostics, Swift REPL, previews)
claude mcp add --transport stdio xcode \
  -s user -- xcrun mcpbridge

Alternativa: instalador automático xcodebuildmcp init (v2.1.0+, 2026-02-23):

Si prefieres omitir la configuración manual de MCP, XcodeBuildMCP v2.1.0+ incluye un subcomando init que detecta automáticamente Claude Code, Cursor o Codex e instala las skills del agente y la configuración de MCP en un solo paso:

xcodebuildmcp init
# Or without a global install:
npx -y xcodebuildmcp@latest init

Opciones: --print (escribe la configuración en stdout para clientes no compatibles), --uninstall (elimina). Omite esto si quieres controlar explícitamente qué servidores de MCP se conectan y en qué alcance; las invocaciones manuales de claude mcp add anteriores te dan ese control.³⁰

Ideal para: Sesiones de implementación profundas: crear nuevas funciones, refactorizar varios archivos, depurar problemas complejos y ejecutar ciclos de compilación-prueba-corrección de forma autónoma. La ventana de contexto de 1M de Claude Code (con Opus 5) permite al agente mantener en memoria de trabajo la mayoría de los proyectos de iOS pequeños o medianos; según mi experiencia, hasta aproximadamente 50 archivos, según el tamaño de estos.²⁵

Sesión típica:

You: Add a new SettingsView with toggles for notifications and haptic feedback.
     Use the existing Settings.swift pattern from TimerManager.
     Build for simulator after implementation and fix any errors.

Claude: [reads Settings.swift, TimerManager.swift, existing views]
        [creates SettingsView.swift]
        [calls build_sim via MCP]
        [reads structured error: missing import HealthKit]
        [fixes import]
        [calls build_sim again — success, 0 errors, 1 warning]
        [calls test_sim — all tests pass]

La diferencia clave frente al flujo de trabajo anterior a MCP: el agente nunca te pide que compiles manualmente ni que pegues la salida de errores. El ciclo de compilación-error-corrección es autónomo.

2. Codex CLI

Qué es: El agente de programación basado en terminal de OpenAI. Es similar en concepto a Claude Code, pero ejecuta los modelos Codex de OpenAI y tiene un modelo de permisos diferente. La línea actual incluye GPT-5.6 Sol (insignia, el más potente para programación compleja), GPT-5.6 Terra (opción equilibrada predeterminada para el día a día) y GPT-5.6 Luna (rápido y más económico), junto con GPT-5.3 Codex Spark como vista previa de investigación solo de texto. GPT-5.4 y GPT-5.4-mini se retiran de Codex el 31 de agosto de 2026; migra esas configuraciones a Terra y Luna, respectivamente.²³

Integración de MCP: Codex es compatible con MCP mediante el comando codex mcp add. El MCP de Xcode de Apple funciona directamente:

# Add Apple Xcode MCP to Codex
codex mcp add xcode -- xcrun mcpbridge

XcodeBuildMCP también funciona con Codex mediante el mismo comando npx:

# Add XcodeBuildMCP to Codex
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

Ideal para: Operaciones por lotes sin interfaz, integración de CI/CD y tareas en las que quieras una segunda opinión de una familia de modelos diferente. El modo sandbox de Codex ejecuta código en entornos aislados, lo que resulta útil para operaciones destructivas, como ejecuciones de suites de pruebas que modifican el estado.

Diferencias clave respecto a Claude Code: - Usa modelos de OpenAI en lugar de modelos de Claude - Diferentes tamaños de ventana de contexto y economía de tokens - Modelo de permisos centrado en sandbox (más restrictivo de forma predeterminada) - Ecosistema de MCP más pequeño (menos servidores de la comunidad probados) - Sistema de hooks disponible (v0.119.0+), pero menos maduro que el de Claude Code: menos tipos de eventos y sin campo condicional if

Cuándo usar Codex en lugar de Claude Code para iOS:

Usa Codex cuando quieras diversidad de modelos: contar con un segundo agente que revise código escrito por el primero detecta clases de errores diferentes. El flujo de trabajo colaborativo (Claude compila, Codex revisa) es eficaz para iOS porque los patrones de SwiftUI que parecen correctos para una familia de modelos pueden tener problemas sutiles que otra detecta. Los shaders de Metal y los patrones de concurrencia se benefician especialmente de una revisión con dos modelos.

3. Agentes nativos de Xcode

Qué es: Apple integró agentes de programación con IA directamente en el panel Intelligence de Xcode. A partir de Xcode 26.3, puedes configurar Claude Agent y Codex como proveedores de inteligencia en Xcode Settings > Intelligence.¹⁰ Xcode 26.6 amplía la lista: Google Gemini ahora está disponible en el asistente de programación (171990272), y Xcode añade compatibilidad con Agent Client Protocol (ACP) (178294840), por lo que lo que se lanzó como una integración de dos proveedores ahora son tres proveedores más un protocolo abierto que permite conectar al panel Intelligence cualquier agente compatible con ACP.¹⁷

Configuración:

1. Abre Xcode 26.3+
2. Ve a Settings > Intelligence
3. Añade un proveedor nuevo:
4. Para Claude: selecciona “Claude Agent” e introduce tu clave de API de Anthropic
5. Para Codex: selecciona “Codex” e introduce tu clave de API de OpenAI
6. Para Gemini: selecciona “Google Gemini” (Xcode 26.6+)
7. Para cualquier otra opción: conecta un agente compatible con ACP (Xcode 26.6+)
8. El agente aparece en la barra lateral Intelligence y se puede invocar en línea

Ideal para: Ediciones rápidas en línea, completado de código con razonamiento a nivel de agente y desarrolladores que prefieren no salir de Xcode. La integración nativa implica que el agente tiene acceso directo al contexto del proyecto de Xcode —archivos abiertos, destinos de compilación, configuración de esquemas— sin conectividad mediante MCP.

Limitaciones frente a los agentes de CLI — en Xcode 26.x: - Sin sistema de hooks: no puedes aplicar formato al guardar ni bloquear escrituras en .pbxproj - Sin carga de CLAUDE.md: el agente no lee los archivos de configuración a nivel de proyecto - Autonomía limitada: el agente opera sobre el archivo o selección actual, no en todo el proyecto - Sin delegación de subagentes: las tareas complejas de varios pasos no se pueden paralelizar - Sin configuración de servidores de MCP: el agente solo usa las herramientas integradas de Xcode

Xcode 27 invalida la mayor parte de esa lista. Desde la beta 1 (8 de junio), los agentes de Xcode son una plataforma de extensiones en lugar de un asistente en línea:²²

• Plug-ins: “Los agentes de Xcode ahora se pueden ampliar con plugins que contienen skills, servidores de MCP y configuraciones de agentes ACP. Las skills se pueden invocar como comandos slash con compatibilidad de completado.” (178289210): por tanto, desaparecen las limitaciones de “solo herramientas integradas” y “sin configuración de MCP”.
• Control del Simulator: los agentes “ahora pueden iniciar simuladores, instalar y ejecutar apps, sintetizar eventos táctiles y capturar capturas de pantalla para verificar el comportamiento de la UI” (175179787), y en la beta 5 pueden controlar entradas de hardware de watchOS (181147968).
• Acceso al depurador: el servidor MCP de Xcode incorporó herramientas para manipular el estado de ejecución, leer la consola del depurador, cambiar esquemas y destinos de ejecución, e inspeccionar o modificar “configuración de compilación, flags del compilador, entitlements y claves de Info.plist” (176935844).
• Una capa de seguridad del sistema de archivos “que supervisa y controla el acceso al sistema de archivos de los agentes de programación y de cualquier proceso que estos generen” (178289431), además de planificación de primera clase (172857081) e información del proyecto que abarca cierres inesperados, bloqueos, energía y problemas de inicio (177568662).

Una advertencia que se desprende directamente de 176935844: los agentes de Xcode ahora pueden editar la configuración de compilación, los entitlements y las claves de Info.plist. La protección de .pbxproj que esta guía implementa con un hook PreToolUse no se aplica dentro de Xcode, porque el hook reside en la configuración de tu agente CLI, no en la de Apple. Si dependes de ese hook como red de seguridad, ten presente que no tiene jurisdicción sobre el panel Intelligence.

Cuándo usar los agentes nativos de Xcode:

Para ediciones rápidas y acotadas en las que cambiar a la terminal supone una carga. “Añade una propiedad calculada a este modelo.” “Escribe una prueba unitaria para esta función.” “Refactoriza esta vista para usar @Observable.” Tareas que afectan uno o dos archivos y no requieren un ciclo de compilación-prueba.

Para cualquier tarea que requiera compilar, probar, refactorizar varios archivos o corregir errores de forma autónoma, usa un agente de CLI con MCP.

Matriz comparativa de entornos de ejecución

La recomendación: Usa Claude Code CLI como tu entorno de ejecución principal. Usa los agentes nativos de Xcode para ediciones rápidas en línea. Usa Codex CLI para revisiones y operaciones por lotes. Los tres se complementan, en lugar de competir.

Configuración de MCP: la configuración completa

MCP (Model Context Protocol) es lo que transforma a un agente de «escribe Swift y espera que lo compiles» a «escribe Swift, lo compila, lee errores estructurados y los corrige».² Esta sección profundiza más que la publicación del blog¹¹: cubre ambos servidores, todos los métodos de instalación, la verificación y la configuración del agente que garantiza que las herramientas se utilicen de verdad.

XcodeBuildMCP: 82 herramientas para desarrollo iOS sin interfaz

XcodeBuildMCP integra xcodebuild, xcrun simctl y LLDB en 82 herramientas estructuradas de MCP (inventario anunciado, verificado sin cambios desde v2.6.2 hasta v2.7.0), agrupadas en 12 categorías de flujo de trabajo.³¹⁹²¹ El hogar canónico del proyecto es la organización de GitHub getsentry: Sentry lo mantiene, y la URL original cameroncooke/XcodeBuildMCP ahora redirige allí, algo importante cuando artículos antiguos citan la dirección anterior.²¹ Funciona sin que Xcode esté abierto: todo el ciclo de compilación, pruebas y depuración se ejecuta sin interfaz mediante las herramientas de línea de comandos de Apple. Conviene conocer dos notas sobre el inventario: una sesión stdio predeterminada expone las dos docenas de herramientas del flujo de simulador y mantiene el resto fuera del contexto de tu agente; configura XCODEBUILDMCP_ENABLED_WORKFLOWS (nombres de categorías separados por comas de la tabla siguiente) para cargar más; y el mismo motor se distribuye como una CLI (xcodebuildmcp tools informa 100 comandos, 72 canónicos) si quieres operaciones idénticas sin MCP.⁹

Opciones de instalación:

# Option 1: Via npx (recommended — always uses latest version)
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Option 2: Via Homebrew (pinned version, manual updates)
brew install xcodebuildmcp
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- xcodebuildmcp mcp

# Option 3: Project-scoped (omit -s user)
claude mcp add XcodeBuildMCP \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

La opción -s user hace que el servidor esté disponible globalmente en todos los proyectos. Omítela para una instalación limitada al proyecto (útil si solo quieres MCP en proyectos iOS, no en proyectos web).

La variable de entorno -e XCODEBUILDMCP_SENTRY_DISABLED=true desactiva la telemetría de informes de fallos. XcodeBuildMCP incluye Sentry de forma predeterminada, que envía datos de errores, incluidas rutas de archivos. Exclúyete salvo que quieras aportar diagnósticos al proyecto.¹

Inventario de herramientas (82 herramientas en 12 categorías de flujo de trabajo; herramientas representativas por categoría):

Las herramientas más importantes para el trabajo diario:

1. build_sim: la llamarás cientos de veces. Devuelve JSON con errores categorizados por archivo, línea y gravedad. El agente lee el error, navega al archivo y lo corrige sin que tengas que tocar nada.

2. test_sim: devuelve resultados por método de prueba. El agente sabe exactamente qué prueba falló y por qué, no solo que «las pruebas fallaron».

3. list_sims + boot_sim: gestión de simuladores sin memorizar opciones de xcrun simctl. El agente descubre los runtimes disponibles y elige un dispositivo adecuado.

4. discover_projs + list_schemes: introspección del proyecto. El agente no necesita adivinar el nombre de tu esquema ni la estructura del workspace.

5. debug_attach_sim + debug_stack + debug_variables: depuración LLDB remota. El agente puede establecer puntos de interrupción, inspeccionar variables y recorrer el código sin que abras el depurador.

Lo que cambió v2.6.0 (2026-06-01): automatización de UI en tiempo de ejecución

La versión v2.6.0 reconstruyó la automatización de UI alrededor de contexto reutilizable en lugar de capturas de pantalla de un solo uso.¹⁹ snapshot_ui ahora devuelve referencias estables a elementos y un hash de pantalla, y acepta sinceScreenHash para que el agente pueda omitir una captura completa cuando la pantalla no ha cambiado. Tres herramientas nuevas cierran el ciclo: wait_for_ui consulta hasta que se cumpla un predicado (existencia, estado habilitado, foco, texto visible o diseño estabilizado) en lugar de que el agente adivine con esperas; batch ejecuta una secuencia de acciones de referencia a elementos en una sola llamada; drag realiza gestos de arrastre con referencia a elementos para hojas y desplazamiento de listas. type_text incorporó replaceExisting para reemplazar el valor de un campo en vez de añadirle texto; los controles candidatos se clasifican a partir de datos de accesibilidad; y los resultados estructurados ahora incluyen sugerencias nextSteps (los esquemas de resultados pasaron a la versión v2 en esta versión; desde entonces, v2.7.0 movió los resultados de compilación/pruebas a schemaVersion: 3; consulta más abajo). Configura XCODEBUILDMCP_HEADLESS_LAUNCH=true para iniciar apps en segundo plano sin robar el foco de macOS: la diferencia entre una sesión de agente que puedes dejar ejecutándose y una que sigue trayendo tu ventana de Simulator al frente. En una tarea determinista de una app del clima, el propio benchmark del proyecto afirma aproximadamente un 70 % menos de tiempo total, un 68 % menos de tokens y un 76 % menos de llamadas a herramientas frente al flujo anterior a 2.6: son cifras del proyecto, no una medición independiente, pero el mecanismo (omitir capturas sin cambios y agrupar acciones en la misma pantalla) es exactamente de donde proviene el consumo de tokens de la automatización de UI.¹⁹

Lo que cambió v2.7.0 (2026-07-23): simuladores de Xcode 27, esquema v3 y compilaciones que respetan el esquema

La versión v2.7.0 es más pequeña que la 2.6.0, pero incorpora un cambio incompatible y un cambio de comportamiento que conviene conocer antes de actualizar.²¹ Lo principal: las herramientas de automatización de UI ahora funcionan por completo con simuladores de Xcode 27 mediante Device Hub, incluida la apertura de ventanas del simulador y los controles de teclado; así se cierra la brecha en la que la automatización de UI en tiempo de ejecución solo era fiable con simuladores de Xcode 26. Incompatible: las herramientas de compilación y pruebas ahora devuelven resultados estructurados con schemaVersion: 3 (habían sido v2 desde 2.6.0); todo lo que hayas escrito para validar o analizar resultados fijados a la versión 2 necesita actualizarse. Cambio de comportamiento: las herramientas de compilación, pruebas, limpieza y ruta de app ahora respetan la configuración de la acción del esquema cuando se omite configuration, en lugar de usar siempre Debug de forma predeterminada. Si la acción Test de un esquema está configurada en Release, una llamada no calificada a test_sim ahora compila Release, así que pasa configuration explícitamente cuando tu flujo dependa de una configuración concreta. Más pequeño, pero útil: los paquetes reutilizables de preparación de pruebas .xctestproducts permiten volver a ejecutar pruebas sin recompilar y aun así generar un .xcresult nuevo en cada ejecución; extraArgs predeterminado por sesión te permite establecer opciones comunes de xcodebuild una vez por sesión en lugar de repetirlas en cada llamada; un nuevo comando de CLI xcodebuildmcp purge informa y limpia el almacenamiento de workspace de XcodeBuildMCP (simulación de forma predeterminada, eliminación solo con aceptación explícita); y se corrigió un problema de clientes de MCP que esperaban entre 10 y 17 segundos a que las herramientas estuvieran disponibles, lo cual podía hacer que verificaciones de estado breves informaran una conexión fallida.²¹

Apple Xcode MCP: 20 herramientas que conectan con Xcode

El servidor MCP de Apple se distribuye con Xcode 26.3 mediante xcrun mcpbridge.⁴ Se comunica con un proceso Xcode en ejecución a través de XPC (el framework de comunicación entre procesos de Apple), exponiendo estado interno al que ninguna herramienta de CLI puede acceder.⁵

Instalación:

# Standard installation (global)
claude mcp add --transport stdio xcode \
  -s user -- xcrun mcpbridge

# For Codex CLI
codex mcp add xcode -- xcrun mcpbridge

Requiere Xcode 26.3+ y un proceso Xcode en ejecución. Si Xcode no está abierto, todas las llamadas de MCP a través de este servidor fallarán o se quedarán esperando. XcodeBuildMCP no tiene esta limitación.

La beta 5 de Xcode 27 adelanta una salida a esa restricción. Apple añadió «una nueva experiencia de servidor MCP que se ejecuta sin requerir un workspace de Xcode abierto», habilitada con sudo xcrun mcp-server enable e inspeccionada con xcrun mcp-server status. La misma versión preliminar te permite conceder a agentes con firma de código permiso duradero para trabajar dentro de un árbol de directorios, en lugar de volver a aprobarlos cada vez. Para ejecuciones desatendidas, sudo xcrun mcp-server enable --unsafe-always-allow-all-agents aprueba todo por adelantado; Apple dice explícitamente que «no es una configuración recomendada para uso frente al escritorio», y yo tampoco: elimina el paso de aprobación que mantiene a un agente fuera de directorios que no querías exponer. Trata toda esta superficie como una versión preliminar temprana y mantén XcodeBuildMCP como la vía sin interfaz hasta que deje de estar en vista previa.²²

Inventario de herramientas (20 herramientas en 5 categorías):

Herramientas exclusivas de Apple MCP (no disponibles en XcodeBuildMCP):

1. DocumentationSearch: busca en la documentación para desarrolladores de Apple, incluidas las sesiones de WWDC. Es más rápida y fiable que una búsqueda web para preguntas sobre Apple API. Pregunta «¿es válido HKQuantityType(.dietaryWater)?» y obtendrás una respuesta definitiva de la fuente.

2. ExecuteSnippet: ejecución de Swift REPL dentro del contexto del proyecto. El agente puede verificar el comportamiento de API, probar conversiones de tipos y validar expresiones sin compilar toda la app.

3. RenderPreview: renderiza previews de SwiftUI sin interfaz. El agente puede comprobar si una vista se renderiza sin errores, aunque no puede evaluar la corrección visual (el render se devuelve como datos, no se inspecciona visualmente). A partir de Xcode 26.6, la herramienta MCP de previews (las notas de la versión 26.6 la llaman «Preview Snapshot») renderiza variantes —apariencia clara/oscura, orientación vertical/horizontal y anulaciones de tamaño de texto (178831772)—, por lo que un agente puede verificar una vista en varias apariencias en una sola pasada.¹⁷ La beta de Xcode 27 la amplía aún más: renderiza grupos de Preview y permite previsualizar en una localización diferente.¹⁸

4. XcodeListNavigatorIssues: devuelve diagnósticos en tiempo real del analizador de Xcode, no solo errores de compilación. Detecta problemas como variables sin usar, posibles ciclos de retención y advertencias de obsolescencia que el sistema de compilación no muestra.

Por qué usar ambos servidores

Se superponen en compilaciones y pruebas, pero son fundamentalmente distintos:

┌─────────────────────────────────────────────────────────────────┐
│                     MCP TOOL COVERAGE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  XcodeBuildMCP (82 tools)        Apple Xcode MCP (20 tools)    │
│  ┌─────────────────────┐         ┌─────────────────────┐       │
│  │ Standalone           │         │ Requires Xcode      │       │
│  │ (no Xcode process)  │         │ (XPC bridge)        │       │
│  │                     │         │                     │       │
│  │ ✓ Simulators        │  BOTH   │ ✓ Documentation     │       │
│  │ ✓ Real devices      │ ┌─────┐ │ ✓ Swift REPL        │       │
│  │ ✓ LLDB debugging    │ │Build│ │ ✓ SwiftUI previews  │       │
│  │ ✓ UI automation     │ │Test │ │ ✓ Live diagnostics  │       │
│  │ ✓ Project scaffold  │ └─────┘ │ ✓ Analyzer issues   │       │
│  │ ✓ Screenshot        │         │                     │       │
│  └─────────────────────┘         └─────────────────────┘       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Usa XcodeBuildMCP para: el ciclo de compilación, pruebas y depuración. Funciona sin Xcode abierto, consume menos memoria del sistema y ofrece una gestión más completa de simuladores y dispositivos. Esta es tu herramienta de compilación principal.

Usa Apple Xcode MCP para: consultas de documentación, verificación con Swift REPL, renderizado de previews de SwiftUI y diagnósticos en tiempo real. Mantén Xcode abierto durante las sesiones que necesiten estas capacidades.

En la práctica: uso XcodeBuildMCP para aproximadamente el 90 % de las llamadas de MCP y Apple Xcode MCP para documentación y verificación con REPL. El agente usa XcodeBuildMCP de forma predeterminada para compilaciones y pruebas porque es más rápido (sin sobrecarga de proceso Xcode) y más fiable (sin dependencia de XPC).

El enfoque de dos servidores se está suavizando. XcodeBuildMCP 2.6.x añade una categoría proxy xcode-ide: xcode_ide_list_tools descubre las capacidades de MCP exclusivas de Xcode-IDE y xcode_ide_call_tool las invoca (aparecen con nombres xcode_tools_*, por ejemplo xcode_tools_documentationsearch), de modo que un único registro de XcodeBuildMCP ahora también puede acceder a las herramientas del lado del IDE de Apple.¹⁹ La restricción importante no cambia: esas llamadas mediante proxy siguen requiriendo un proceso Xcode en ejecución, exactamente igual que un registro directo de xcrun mcpbridge. Mantén ambos servidores registrados si quieres que las herramientas de Apple sean de primera clase en la lista de herramientas del agente; el proxy es más útil si quieres una sola entrada de servidor y solo lecturas ocasionales del IDE.

Verificación

Después de instalar ambos servidores, verifica que estén conectados:

# List all configured MCP servers
claude mcp list

# Expected output includes:
# XcodeBuildMCP: npx -y xcodebuildmcp@latest mcp - Connected
# xcode: xcrun mcpbridge - Connected

Si un servidor muestra «Disconnected» o no aparece:

1. XcodeBuildMCP no conecta: asegúrate de que Node.js esté instalado (node --version). El comando npx requiere Node.js 18+.
2. Apple Xcode MCP no conecta: asegúrate de que Xcode 26.3+ esté instalado y de que el comando xcrun mcpbridge funcione en tu terminal. Abre Xcode al menos una vez para aceptar el acuerdo de licencia.
3. Ninguno aparece: reinicia Claude Code (ejecuta claude en una terminal nueva). Es posible que los servidores de MCP registrados a mitad de sesión no aparezcan hasta reiniciar.

Enseñar al agente a usar MCP

Instalar servidores de MCP es necesario, pero insuficiente. Sin indicaciones explícitas, el agente puede volver a ejecutar xcodebuild mediante Bash (salida no estructurada, tokens de contexto desperdiciados) o usar búsquedas web para la documentación de Apple (más lento y menos fiable).

Añade esto a tu CLAUDE.md o definición del agente:

## Build & Test — Always Use MCP

Prefer MCP tools over raw shell commands for ALL build operations:

- **Build**: `build_sim` / `build_device` (NOT `xcodebuild` via Bash)
- **Test**: `test_sim` / `test_device` (NOT `xcodebuild test` via Bash)
- **Simulators**: `list_sims`, `boot_sim`, `open_sim` (NOT `xcrun simctl` via Bash)
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple docs**: `DocumentationSearch` (NOT WebSearch for Apple APIs)
- **Swift verification**: `ExecuteSnippet` (NOT `swift` via Bash)
- **Previews**: `RenderPreview` for headless SwiftUI verification

MCP returns structured JSON. Bash returns unstructured text.
Structured data means fewer tokens consumed and better error diagnosis.

Esta guía garantiza que el agente recurra primero a las herramientas de MCP. Sin ella, observarás al agente construyendo comandos largos de xcodebuild mediante Bash, consumiendo miles de tokens de contexto para analizar la salida y, a veces, identificando erróneamente el error real.⁶

Un cambio de comportamiento de XcodeBuildMCP v2.7.0 pertenece al modelo mental de esta sección: cuando se omite configuration, las herramientas de compilación, pruebas, limpieza y ruta de app ahora respetan la configuración de la acción del esquema en vez de usar siempre Debug.²¹ La mayoría de los esquemas ejecutan y prueban en Debug, así que la mayoría de los proyectos no notarán nada; pero si la acción de un esquema está configurada en Release (algo habitual en esquemas de perfilado o configuraciones cercanas al archivado), un build_sim o test_sim no calificado ahora compila Release. Si tu CLAUDE.md o hooks asumen artefactos Debug, indícalo explícitamente en la llamada a la herramienta o establécelo una vez por sesión con session_set_defaults.

Compilaciones de larga duración: Claude Code ahora las ejecuta en segundo plano

Dos versiones de Claude Code cambiaron el aspecto de una compilación larga dentro de una sesión. Desde la v2.1.212 (2026-07-16), toda llamada a una herramienta de MCP que dure más de 2 minutos pasa automáticamente a segundo plano para que la sesión siga siendo utilizable; el umbral es configurable, o el comportamiento puede desactivarse, mediante CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS.²⁰ Las compilaciones limpias y las ejecuciones completas de pruebas mediante build_sim / test_sim superan habitualmente los 2 minutos en proyectos reales, así que espera que el agente siga trabajando —leyendo archivos y planificando la siguiente edición— mientras la compilación termina en segundo plano en lugar de bloquear el turno. La corrección complementaria importa tanto como esta: antes de la v2.1.206 (2026-07-09), un request_timeout_ms por servidor configurado mediante --mcp-config o .mcp.json se ignoraba en sesiones nuevas, por lo que las llamadas largas de MCP agotaban el tiempo de espera predeterminado de 60 segundos; el síntoma clásico era que una primera compilación limpia agotaba el tiempo de espera y «se arreglaba sola» al reintentarlo.²⁰ Si solucionaste cualquiera de los dos comportamientos con scripts envoltorio o compilaciones precalentadas, puedes eliminar esa solución.

Patrones de CLAUDE.md para proyectos iOS

Tu CLAUDE.md es el archivo más importante del proyecto para el desarrollo asistido por agentes. Es el documento de onboarding del agente: la diferencia entre una contratación nueva que leyó la documentación de arquitectura y una que está adivinando.

Cada proyecto iOS que mantengo tiene un CLAUDE.md. Estos son los patrones que funcionan, extraídos de las 8 apps.

Las secciones esenciales

Todo CLAUDE.md de iOS necesita estas seis secciones. Todo lo demás es opcional.

1. Identidad del proyecto

# Return - Zen Focus Timer

**Bundle ID:** `com.941apps.Return`
**Target:** iOS 26+ / macOS Tahoe / watchOS 26+ / tvOS 26+
**Architecture:** SwiftUI with @Observable pattern, companion Watch and TV apps
**Swift version:** 6.2
**Minimum deployment:** iOS 26.0

Por qué importa: el agente necesita conocer el deployment target antes de escribir cualquier código. Un agente orientado a iOS 17 usará NavigationView y @ObservedObject. Un agente orientado a iOS 26 usará NavigationStack y @Observable. El bundle ID importa para los entitlements y la configuración de HealthKit. La versión de Swift determina el modelo de concurrencia (async/await vs. completion handlers, concurrencia estricta vs. flexible).

2. Estructura de archivos con anotaciones de propósito

## File Structure

```
Return/
├── ReturnApp.swift              # App entry, dark mode enforcement
├── ContentView.swift            # Main timer view with theme backgrounds
├── TimerManager.swift           # Timer state, logic, and repeat handling
├── AudioManager.swift           # Sound playback with AVAudioPlayer
├── Settings.swift               # Centralized settings with validation
├── SettingsSheet.swift          # Settings UI
├── HealthKitManager.swift       # Mindful session logging + cross-device sync
├── LiveActivityManager.swift    # Lock Screen/Dynamic Island
├── Theme.swift                  # Theme definitions
├── ThemeManager.swift           # Theme state management
├── VideoBackgroundView.swift    # AVPlayer video backgrounds
├── GlassTextShape.swift         # Core Text glyph paths for glass effect
├── GlassTimerText.swift         # Timer text with glass material
└── Constants.swift              # App constants
```

Los comentarios en línea después de cada nombre de archivo no son decoración. Son la documentación de mayor impacto que puedes escribir. Cuando el agente decide dónde agregar una función nueva, estas anotaciones lo guían al archivo correcto desde el primer intento, en lugar de obligarlo a leer cada archivo para entender la estructura del proyecto.

Antipatrón: listar archivos sin anotaciones. TimerManager.swift no le dice nada al agente sobre si maneja estado, UI o ambas cosas. TimerManager.swift # Timer state, logic, and repeat handling le dice exactamente qué pertenece ahí y qué no.

3. Comandos de build y test

## Build & Test

Build for iOS simulator:
```bash
xcodebuild -scheme Return -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build
```

Run tests:
```bash
xcodebuild -scheme Return -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test
```

Run tvOS tests:
```bash
xcodebuild -scheme ReturnTV -destination 'platform=tvOS Simulator,name=Apple TV' test
```

**Prefer MCP tools** (`build_sim`, `test_sim`) over these raw commands.
MCP returns structured JSON with categorized errors.

Incluye los comandos sin procesar aunque el agente debería preferir MCP. Los comandos sin procesar funcionan como documentación de respaldo y hacen explícitos los nombres de schemes y destinos.

4. Patrones y reglas clave

## Key Patterns

### Observable Architecture
- ALL view models use `@Observable` (NEVER `ObservableObject`)
- ALL navigation uses `NavigationStack` (NEVER `NavigationView`)
- State management via `@Observable` classes with `@MainActor` isolation

### Settings Pattern
- Centralized `Settings.shared` singleton
- All settings bounded to valid ranges with validation
- Sound names validated against whitelist
- Thread-safe access via @MainActor

### Audio System
- `AVAudioPlayer` with `.playback` category (plays in silent mode)
- Silent audio loop for background execution
- Bell playback with completion callbacks and token-based staleness

Estos patrones evitan que el agente introduzca inconsistencias. Sin documentación explícita de patrones, a veces el agente usará ObservableObject en un archivo y @Observable en otro, o creará un mecanismo de configuración nuevo en lugar de usar el singleton existente Settings.shared.

5. Cosas que el agente nunca debe hacer

## Rules

- **NEVER modify .pbxproj files** — create Swift files, then I will add them to Xcode manually
- **NEVER modify .xcodeproj/ contents directly**
- **NEVER add new package dependencies** without asking first
- **NEVER change the deployment target**
- **NEVER modify entitlements files** unless explicitly asked
- **NEVER use NavigationView** — always NavigationStack
- **NEVER use ObservableObject** — always @Observable
- **NEVER use @StateObject** — always @State with @Observable

Las prohibiciones explícitas son más efectivas que las expectativas implícitas. El agente sigue restricciones negativas con más fiabilidad que sugerencias positivas, porque son binarias (hazlo / no lo hagas) en lugar de heurísticas (prefiere esto / a veces usa aquello).

6. Contexto específico del framework

Esta sección varía según la app. Inclúyela para cualquier framework que tenga configuración no obvia:

Para apps con HealthKit:

## HealthKit Configuration

- Entitlement: `com.apple.developer.healthkit`
- Info.plist keys:
  - `NSHealthShareUsageDescription`: "Return reads your mindful minutes..."
  - `NSHealthUpdateUsageDescription`: "Return logs meditation sessions..."
- Category types: `HKCategoryType(.mindfulSession)`
- Authorization checked on every write (user can revoke at any time)
- HealthKit is unavailable on tvOS — guard with `#if canImport(HealthKit)`

Para apps con SwiftData:

## SwiftData Models

### Model Relationships
- `GroceryList` has many `GroceryItem` (cascade delete)
- `GroceryItem` belongs to one `GroceryList`
- `GroceryItem` has optional `Category`

### Model Container Setup
- Configured in App struct with `modelContainer(for:)`
- Schema versioning: currently V2
- Migration plan: `GroceryMigrationPlan` handles V1 → V2

### Queries
- `@Query(sort: \GroceryItem.name)` for sorted fetches
- `@Query(filter: #Predicate { !$0.isCompleted })` for active items
- Always use `@Query` in views, `modelContext.fetch()` in managers

Para apps con SpriteKit:

## SpriteKit Scene Hierarchy

```
GameScene (SKScene)
├── backgroundLayer (SKNode, zPosition: -100)
│   └── StarfieldNode (custom, parallax scrolling)
├── gameLayer (SKNode, zPosition: 0)
│   ├── playerShip (PlayerNode, zPosition: 10)
│   ├── enemyContainer (SKNode, zPosition: 5)
│   └── bulletPool (SKNode, zPosition: 8)
├── effectsLayer (SKNode, zPosition: 50)
│   └── ParticleManager (manages explosion/trail emitters)
└── hudLayer (SKNode, zPosition: 100)
    ├── scoreLabel (SKLabelNode)
    └── healthBar (HealthBarNode)
```

- Physics categories defined in `PhysicsCategory.swift` as bitmasks
- Contact detection via `didBegin(_ contact:)` on GameScene
- Bullet pooling: pre-allocate 50, recycle via `removeFromParent()` + re-add

Para apps con Metal:

## Metal Pipeline

- Render pipeline: `MetalView` → `Renderer` → `ShaderLibrary`
- Compute pipeline: `AudioAnalyzer` → compute shader → texture output
- Shared uniforms struct: `Uniforms` in `ShaderTypes.h` (bridged to Swift)
- Frame timing: `CADisplayLink` drives render loop
- Buffer triple-buffering: 3 in-flight frames with semaphore

### Shader Files
- `Shaders.metal` — Main render shaders (vertex + fragment)
- `Compute.metal` — Audio analysis compute kernel
- `PostProcess.metal` — Bloom and color grading

### DO NOT modify Metal shaders without testing on device.
Simulator Metal is not representative of device GPU behavior.

CLAUDE.md real: Banana List (SwiftUI + SwiftData + iCloud + servidor MCP)

Aquí tienes un ejemplo anotado que muestra cómo las seis secciones trabajan juntas en una app de complejidad moderada. Este es el patrón de CLAUDE.md que uso para Banana List, una app de lista de compras de 53 archivos con sincronización de iCloud y un servidor MCP personalizado que expone los datos de la app a Claude Desktop:

# Banana List - Grocery List App

**Bundle ID:** `com.941apps.BananaList`
**Target:** iOS 26+
**Architecture:** SwiftUI + SwiftData + iCloud Drive sync
**Swift version:** 6.2
**Minimum deployment:** iOS 26.0

## Core Features

- Grocery lists with items, categories, and quantities
- iCloud Drive sync via SwiftData CloudKit integration
- Custom MCP server exposing list data to Claude Desktop
- Liquid Glass design system
- Haptic feedback on interactions
- Share sheets for list sharing

## File Structure

```
BananaList/
├── BananaListApp.swift           # App entry, model container setup
├── Models/
│   ├── GroceryList.swift         # @Model: list with name, items, color
│   ├── GroceryItem.swift         # @Model: item with name, quantity, category, isCompleted
│   ├── Category.swift            # @Model: user-defined categories
│   └── SampleData.swift          # Preview and test data
├── Views/
│   ├── ListsView.swift           # Main list of grocery lists
│   ├── ListDetailView.swift      # Items within a list
│   ├── ItemRow.swift             # Single item row with swipe actions
│   ├── AddItemSheet.swift        # New item form
│   ├── CategoryPicker.swift      # Category selection with create-new
│   └── SettingsView.swift        # App settings
├── Managers/
│   ├── CloudSyncManager.swift    # iCloud Drive sync status and conflict resolution
│   └── HapticManager.swift       # UIImpactFeedbackGenerator wrapper
├── MCP/
│   ├── MCPServer.swift           # MCP server for Claude Desktop integration
│   ├── ListTools.swift           # MCP tools: list CRUD operations
│   └── ItemTools.swift           # MCP tools: item CRUD operations
└── Extensions/
    ├── Color+Extensions.swift    # Custom color definitions
    └── View+Extensions.swift     # Reusable view modifiers
```

## SwiftData Models

### Relationships
- `GroceryList` has many `GroceryItem` (cascade delete)
- `GroceryItem` belongs to one `GroceryList` (required)
- `GroceryItem` has optional `Category`
- `Category` has many `GroceryItem` (nullify on delete)

### Container Setup
```swift
@main
struct BananaListApp: App {
    var body: some Scene {
        WindowGroup {
            ListsView()
        }
        .modelContainer(for: [GroceryList.self, GroceryItem.self, Category.self])
    }
}
```

### Query Patterns
- Lists: `@Query(sort: \GroceryList.name) var lists: [GroceryList]`
- Active items: `@Query(filter: #Predicate { !$0.isCompleted })`
- By category: filter in-memory after fetch (SwiftData predicate limitations)

## Build & Test

```bash
xcodebuild -scheme BananaList -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build
xcodebuild -scheme BananaList -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test
```

Prefer MCP tools (`build_sim`, `test_sim`) over raw commands.

## Key Patterns

### Observable + SwiftData
- SwiftData `@Model` classes are automatically Observable
- DO NOT add `@Observable` to `@Model` classes (redundant, causes warnings)
- Use `@Bindable` for two-way bindings to model properties in forms
- Use `@Query` in views, `modelContext.fetch()` in non-view code

### iCloud Sync
- Automatic via SwiftData CloudKit integration
- Conflict resolution: last-write-wins (CloudKit default)
- Sync status exposed via `CloudSyncManager.shared.syncState`
- Test sync by running on two simulators with same iCloud account

### MCP Server Architecture
- Runs as a local WebSocket server on port 8765
- Exposes 6 tools: listAll, getList, createList, addItem, completeItem, deleteItem
- Claude Desktop connects via MCP config in `~/.config/claude-desktop/config.json`

## Rules

- NEVER modify .pbxproj or .xcodeproj contents
- NEVER change the model schema without updating SampleData.swift
- NEVER use `ObservableObject` — SwiftData models are already Observable
- NEVER use `@StateObject` — use `@State` with `@Observable` classes
- NEVER use `NavigationView` — always `NavigationStack`
- NEVER add `@Observable` macro to `@Model` classes
- ALWAYS use `@Bindable` for form bindings to model properties
- ALWAYS test iCloud sync changes on two simulator instances

CLAUDE.md real: Reps (app SwiftData mínima: 14 archivos)

Para proyectos pequeños, el CLAUDE.md puede ser conciso. Este es el patrón para Reps, un rastreador de entrenamientos de 14 archivos. Observa cómo incluso un CLAUDE.md corto cubre las seis secciones esenciales:

# Reps - Workout Tracking

**Bundle ID:** `com.941apps.Reps`
**Target:** iOS 26+
**Architecture:** SwiftUI + SwiftData
**Swift version:** 6.2

## File Structure

```
Reps/
├── RepsApp.swift              # App entry, model container
├── Models/
│   ├── Workout.swift          # @Model: workout with exercises, date, duration
│   ├── Exercise.swift         # @Model: exercise with sets, reps, weight
│   └── ExerciseTemplate.swift # @Model: saved exercise definitions
├── Views/
│   ├── WorkoutListView.swift  # Main list of workouts
│   ├── WorkoutDetailView.swift # Exercises within a workout
│   ├── ExerciseRow.swift      # Single exercise with inline editing
│   ├── AddExerciseSheet.swift # Exercise selection from templates
│   ├── NewWorkoutView.swift   # Start new workout flow
│   └── StatsView.swift        # Progress charts and summaries
├── Managers/
│   └── WorkoutTimer.swift     # Active workout timer
└── Extensions/
    └── Date+Extensions.swift  # Formatting helpers
```

## Build & Test

```bash
xcodebuild -scheme Reps -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build
xcodebuild -scheme Reps -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test
```

## SwiftData Relationships

- `Workout` has many `Exercise` (cascade delete)
- `Exercise` has optional `ExerciseTemplate`
- `ExerciseTemplate` standalone (nullify on exercise delete)

## Rules

- NEVER modify .pbxproj
- NEVER use ObservableObject — use @Observable
- NEVER use NavigationView — use NavigationStack
- @Model classes are already Observable — do not add @Observable macro
- Use @Bindable for form bindings to model properties

Eso son 40 líneas de CLAUDE.md para un proyecto de 14 archivos. Toma 10 minutos escribirlo y ahorra horas de confusión del agente.

CLAUDE.md real: Starfield Destroyer (SpriteKit + Metal: 32 archivos)

Los proyectos de juegos requieren más contexto específico del framework. El agente necesita entender el grafo de escenas, las categorías de física y la máquina de estados del juego:

# Starfield Destroyer - Space Shooter

**Bundle ID:** `com.941apps.StarfieldDestroyer`
**Target:** iOS 26+
**Architecture:** SpriteKit + Metal post-processing + Game Center
**Swift version:** 6.2

## Game Overview

99 levels across 3 galaxies. 8 unlockable ships with different stats.
Game Center leaderboards and achievements. Metal shader post-processing
for bloom and screen effects.

## File Structure

```
StarfieldDestroyer/
├── StarfieldDestroyerApp.swift    # App entry, Game Center auth
├── GameScene.swift                # Main game scene, update loop
├── MenuScene.swift                # Title screen, ship selection
├── Entities/
│   ├── PlayerShip.swift           # Player node with physics, weapons, shields
│   ├── EnemyShip.swift            # Enemy base class with AI behaviors
│   ├── Bullet.swift               # Bullet pool node
│   ├── PowerUp.swift              # Collectible power-ups
│   └── Boss.swift                 # Boss enemies (levels 33, 66, 99)
├── Systems/
│   ├── LevelManager.swift         # Level progression, wave spawning
│   ├── PhysicsCategory.swift      # UInt32 bitmask categories
│   ├── CollisionHandler.swift     # Contact delegate methods
│   ├── ScoreManager.swift         # Score tracking, multipliers
│   ├── ParticleManager.swift      # Explosion, trail, shield emitters
│   └── AudioManager.swift         # Sound effects, background music
├── UI/
│   ├── HUDNode.swift              # Score, health, level display
│   ├── ShipSelectView.swift       # SwiftUI ship selection (UIHostingController)
│   ├── GameOverView.swift         # Game over screen with score submission
│   └── PauseMenu.swift            # Pause overlay
├── Metal/
│   ├── MetalRenderer.swift        # Post-processing render pipeline
│   ├── BloomShader.metal          # Bloom post-process effect
│   └── ShaderTypes.h              # Shared uniforms (bridging header)
├── Data/
│   ├── ShipData.swift             # 8 ship definitions (speed, damage, shields)
│   ├── LevelData.swift            # 99 level configurations
│   └── AchievementData.swift      # Game Center achievement definitions
└── GameCenterManager.swift        # Leaderboard/achievement submission
```

## SpriteKit Scene Hierarchy

```
GameScene (SKScene)
├── backgroundLayer (zPosition: -100)
│   └── StarfieldNode (parallax scrolling, 3 layers)
├── gameLayer (zPosition: 0)
│   ├── playerShip (zPosition: 10)
│   ├── enemyContainer (zPosition: 5)
│   ├── bulletPool (zPosition: 8) — pre-allocated 50 bullets
│   └── powerUpContainer (zPosition: 3)
├── effectsLayer (zPosition: 50)
│   └── ParticleManager (explosion + trail emitters)
└── hudLayer (zPosition: 100)
    ├── scoreLabel (SKLabelNode)
    ├── healthBar (custom SKShapeNode)
    └── levelLabel (SKLabelNode)
```

## Physics Categories

```swift
struct PhysicsCategory {
    static let none:      UInt32 = 0
    static let player:    UInt32 = 0b1        // 1
    static let enemy:     UInt32 = 0b10       // 2
    static let bullet:    UInt32 = 0b100      // 4
    static let powerUp:   UInt32 = 0b1000     // 8
    static let shield:    UInt32 = 0b10000    // 16
    static let bossBullet:UInt32 = 0b100000   // 32
}

// Contact pairs:
// player + enemy → damage
// player + powerUp → collect
// bullet + enemy → destroy
// player + bossBullet → damage
```

## Game State Machine

```
.menu → .playing → .paused → .playing
                 → .gameOver → .menu
                 → .bossIntro → .playing
                 → .levelComplete → .playing (next level)
```

## Metal Post-Processing

- Bloom shader: `BloomShader.metal` — multi-pass Gaussian blur + additive blend
- Uniforms: `PostProcessUniforms { float intensity; float threshold; float2 resolution; }`
- Applied after SpriteKit renders each frame via `SKView.presentScene(:transition:)`
- DO NOT modify Metal shaders without testing on device

## Build & Test

```bash
xcodebuild -scheme StarfieldDestroyer -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build
xcodebuild -scheme StarfieldDestroyer -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test
```

## Rules

- NEVER modify .pbxproj
- NEVER modify PhysicsCategory bitmasks (breaks all collision detection)
- NEVER change the scene hierarchy z-ordering without understanding render order
- NEVER modify ShaderTypes.h without updating both Swift and Metal references
- Add new enemies by subclassing EnemyShip, not by modifying it
- Bullet pooling: recycle via removeFromParent() + re-add, never allocate new
- Game Center: always check isAuthenticated before submitting scores

CLAUDE.md real: amp97 (Metal + visualización de audio: 41 archivos)

Los proyectos de Metal necesitan el mayor contexto específico del framework porque los agentes no pueden verificar la salida visual:

# amp97 - Audio Visualizer

**Bundle ID:** `com.941apps.amp97`
**Target:** iOS 26+
**Architecture:** Metal render pipeline + AVAudioEngine analysis
**Swift version:** 6.2

## Architecture

```
Audio Input (microphone/file)
    → AVAudioEngine tap
    → FFT (vDSP)
    → Frequency/amplitude buffers
    → Metal compute shader (analysis)
    → Metal render pipeline (visualization)
    → CADisplayLink (60fps)
    → MTKView
```

## File Structure

```
amp97/
├── amp97App.swift               # App entry
├── Audio/
│   ├── AudioEngine.swift        # AVAudioEngine setup, tap installation
│   ├── FFTProcessor.swift       # vDSP FFT, frequency bin extraction
│   ├── AudioBuffer.swift        # Ring buffer for audio data
│   └── MicrophoneManager.swift  # Microphone permission, session config
├── Rendering/
│   ├── MetalView.swift          # MTKView wrapper for SwiftUI
│   ├── Renderer.swift           # Main render loop, pipeline state
│   ├── ShaderLibrary.swift      # Compiled shader management
│   ├── BufferManager.swift      # Triple-buffered uniform updates
│   └── TextureManager.swift     # Offscreen render targets
├── Shaders/
│   ├── Shaders.metal            # Vertex + fragment shaders
│   ├── AudioCompute.metal       # Audio analysis compute kernel
│   ├── PostProcess.metal        # Bloom, color grading
│   └── ShaderTypes.h            # Shared uniforms (bridging header)
├── Visualizations/
│   ├── WaveformViz.swift        # Oscilloscope-style waveform
│   ├── SpectrumViz.swift        # Frequency spectrum bars
│   ├── CircularViz.swift        # Radial visualization
│   └── VizSelector.swift        # Visualization switching
├── Views/
│   ├── MainView.swift           # Full-screen viz with overlays
│   ├── ControlsOverlay.swift    # Play/pause, viz selection, gain
│   └── SettingsView.swift       # Audio source, sensitivity
└── Extensions/
    ├── SIMD+Extensions.swift    # Vector math helpers
    └── Color+Metal.swift        # UIColor → float4 conversion
```

## Metal Pipeline

### Uniforms (ShaderTypes.h)
```c
typedef struct {
    float time;
    float2 resolution;
    float audioLevel;       // 0.0-1.0 RMS amplitude
    float frequencyBins[64]; // FFT output, normalized
    float4x4 transform;
} Uniforms;
```

### Render Pipeline
1. Compute pass: AudioCompute.metal processes FFT data → texture
2. Render pass: Shaders.metal reads texture + uniforms → visualization
3. Post-process pass: PostProcess.metal applies bloom → final output

### Buffer Management
- Triple buffering with DispatchSemaphore(value: 3)
- Uniforms updated per-frame on CPU, consumed by GPU 1-2 frames later
- Audio data ring buffer: 4096 samples, lock-free single producer/consumer

## Rules

- NEVER modify ShaderTypes.h without updating BOTH Swift and Metal sides
- NEVER exceed 64 frequency bins (fixed buffer size in shader)
- NEVER test Metal visual output in simulator — device only
- NEVER modify the audio engine tap format (48kHz, mono, float32)
- Triple buffer discipline: always signal semaphore in completion handler
- Audio session: .playAndRecord category with .defaultToSpeaker option

Escalar CLAUDE.md según el tamaño del proyecto

El nivel adecuado de detalle depende de la cantidad de archivos y de la complejidad del framework:

El costo de documentar de más es casi cero (el agente omite lo que no necesita). El costo de documentar de menos es alto (el agente inventa patrones que entran en conflicto con tu codebase).

Checklist de CLAUDE.md

Usa esta checklist al crear o auditar un CLAUDE.md para un proyecto iOS:

• [ ] Bundle ID y deployment target especificados
• [ ] Versión de Swift y patrón de arquitectura nombrados
• [ ] Estructura de archivos con anotaciones de propósito en línea
• [ ] Comando de build con scheme y destino correctos
• [ ] Comando de test con scheme y destino correctos
• [ ] Preferencia por MCP indicada (“prefer build_sim over xcodebuild”)
• [ ] Regla de @Observable (nunca ObservableObject)
• [ ] Regla de NavigationStack (nunca NavigationView)
• [ ] Prohibición de .pbxproj
• [ ] Contexto específico del framework (permisos de HealthKit, relaciones de SwiftData, jerarquía de SpriteKit, pipeline de Metal)
• [ ] Guards de disponibilidad de plataforma documentados (#if canImport, #if os)
• [ ] Singletons clave y patrones compartidos documentados
• [ ] Limitaciones conocidas o gotchas señalados

Tu primera sesión con un agente

Con MCP configurado y un CLAUDE.md en tu proyecto, aquí tienes un recorrido de una primera sesión efectiva. Esto usa Claude Code CLI, pero el flujo de trabajo aplica a cualquier runtime.

Paso 1: Verifica que el agente pueda ver tu proyecto

You: Summarize this project. What scheme should I build with?

Claude: [reads CLAUDE.md]
        [calls discover_projs via MCP]
        [calls list_schemes via MCP]

        This is Return, a zen meditation timer for iOS 26+, watchOS, and tvOS.
        Available schemes: Return, ReturnWatch, ReturnTV, ReturnTests.
        Primary scheme for iOS: Return.

Si el agente no hace referencia al contenido de tu CLAUDE.md, revisa que el archivo esté en la raíz del proyecto (el mismo directorio que .xcodeproj o Package.swift).

Paso 2: Ejecuta un build de verificación de estado

You: Build the Return scheme for iOS simulator and report results.

Claude: [calls list_sims — finds iPhone 16 Pro on iOS 26.2]
        [calls boot_sim — boots the simulator]
        [calls build_sim — builds the project]

        Build succeeded. 63 source files compiled.
        2 warnings:
        - HomeView.swift:132 — UIScreen.main deprecated in iOS 26.0
        - LogWaterIntent.swift:61 — Result of try? is unused
        0 errors.

Paso 3: Ejecuta las pruebas

You: Run all tests and report pass/fail.

Claude: [calls test_sim]

        12 tests executed:
        ✓ TimerManagerTests (5/5 passed)
        ✓ SettingsTests (4/4 passed)
        ✓ ConstantsTests (3/3 passed)
        All tests passed.

Paso 4: Implementa una función

You: Add a new "Rain" theme to the theme system. Follow the existing
     pattern in Theme.swift and ThemeManager.swift. Include a rain
     ambient sound. Build and test after implementation.

Claude: [reads Theme.swift — understands Theme struct pattern]
        [reads ThemeManager.swift — understands theme registration]
        [reads existing theme definitions]
        [adds Rain theme to Theme.swift following existing pattern]
        [registers Rain theme in ThemeManager.swift]
        [calls build_sim — build succeeds]
        [calls test_sim — all tests pass]

        Added Rain theme:
        - Theme.swift: new `static let rain` with video, cover, ambient
        - ThemeManager.swift: added to `allThemes` array
        - Build: success (0 errors, 2 existing warnings)
        - Tests: 12/12 passed

        Note: You'll need to add rain_ambient.wav to the project
        and add the new Theme.swift changes to the Xcode target manually
        (I did not modify .pbxproj).

La nota del agente sobre no modificar .pbxproj es el resultado de las reglas en CLAUDE.md. Sin esa regla, el agente intentaría modificar el archivo del proyecto y probablemente lo corrompería.

Lo que los agentes hacen bien en iOS

Estas son las tareas donde los agentes producen de forma consistente resultados correctos y listos para producción con mínima revisión humana.

Vistas y modificadores de SwiftUI

Los agentes tienen un reconocimiento profundo de patrones para la sintaxis declarativa de SwiftUI. La composición de vistas, las cadenas de modificadores, los enlaces de estado y el layout se adaptan bien a los datos de entrenamiento del agente, porque la superficie de API de SwiftUI está bien documentada y sus patrones son muy consistentes.

Donde los agentes sobresalen: - Crear nuevas vistas a partir de una descripción (“crea una hoja de configuración con toggles para X, Y, Z”) - Aplicar cadenas de modificadores (.glassEffect(), .sensoryFeedback(), .navigationTitle()) - Convertir entre patrones de layout (de VStack a LazyVGrid, de List a ScrollView) - Implementar enlaces de formulario con @Bindable para modelos SwiftData - Crear preview providers con datos de ejemplo

Ejemplo de prompt que produce resultados excelentes:

Create a SettingsView that matches the existing pattern in SettingsSheet.swift.
Include toggles for:
- Enable haptic feedback (Settings.shared.hapticsEnabled)
- Enable HealthKit logging (Settings.shared.healthKitEnabled)
- Show session history (navigation link to SessionHistoryView)

Use Liquid Glass styling with .glassEffect() on section backgrounds.
Follow the @Observable pattern, not ObservableObject.

La especificidad importa. “Crea una vista de configuración” produce un resultado genérico. “Crea un SettingsView que coincida con el patrón existente en SettingsSheet.swift” produce un resultado coherente con tu codebase.

Modelos y consultas de SwiftData

Los agentes manejan de forma confiable la macro @Model de SwiftData, sus relaciones y los patrones de @Query. La naturaleza declarativa del framework (similar a Django ORM o SQLAlchemy) encaja bien con patrones que el agente ha visto en muchas codebases.

Donde los agentes sobresalen: - Definir clases @Model con relaciones - Escribir @Query con sort descriptors y predicados - Implementar operaciones CRUD mediante modelContext - Planes de migración entre versiones de esquema - Datos de preview y fixtures de prueba

Donde los agentes necesitan guía: - Expresiones #Predicate complejas (el DSL de predicados de SwiftData tiene limitaciones que el agente no siempre conoce; documenta las limitaciones conocidas en CLAUDE.md) - Configuración de sincronización con CloudKit (automática mediante SwiftData, pero el agente puede intentar implementar una sincronización manual)

Pruebas unitarias

Las pruebas unitarias escritas por agentes tienen una calidad consistentemente alta en proyectos iOS. El agente entiende los patrones de XCTest, los métodos de prueba async y el ciclo de vida de setup/teardown.

Write unit tests for TimerManager covering:
1. Initial state is .stopped
2. start() transitions to .running
3. pause() transitions to .paused
4. reset() returns to .stopped with original duration
5. Timer counts down correctly (test with 3-second duration)

El agente produce casos XCTest bien estructurados con setUp() y tearDown(), assertions apropiadas y manejo async para pruebas basadas en temporizadores.

Refactorización y aplicación de patrones

Los agentes sobresalen en la refactorización mecánica: extraer vistas en componentes, convertir ObservableObject a @Observable, migrar de NavigationView a NavigationStack y aplicar patrones consistentes en varios archivos.

Refactor all views in the Views/ directory to use @Observable instead of
ObservableObject. Update @StateObject to @State, @ObservedObject to direct
property access, and @Published to plain properties.

El agente avanza metódicamente por cada archivo, aplica la transformación correctamente y mantiene la funcionalidad existente. Este es trabajo de alto apalancamiento: una refactorización que tomaría una hora de edición manual se completa en minutos con una precisión casi perfecta.

Diagnóstico de errores de build mediante MCP

Con salida estructurada de MCP, los agentes diagnostican errores de build más rápido que la mayoría de los desarrolladores. El agente lee el JSON del error, identifica el archivo y la línea exactos, entiende el mensaje de error y aplica la corrección, a menudo en un solo turno.

Errores que los agentes corrigen de forma autónoma: - Imports faltantes - Incompatibilidades de tipos - Faltas de conformidad con protocolos - Uso obsoleto de API (con reemplazo) - Parámetros obligatorios faltantes en inicializadores - Violaciones de control de acceso

Errores con los que los agentes necesitan ayuda: - Resolución de tipos ambigua (varios módulos definen el mismo tipo) - Fallas complejas de constraints genéricos - Errores de expansión de macros (el agente no puede ver la salida expandida de macros)

Gestión del simulador

Los agentes manejan bien el ciclo de vida del simulador mediante MCP:

Boot an iPhone 16 Pro simulator on iOS 26, install the app, and take a screenshot.

El agente llama a list_sims para encontrar runtimes disponibles, boot_sim para iniciar el simulador, build_sim para compilar e instalar, y screenshot para capturar, todo mediante llamadas estructuradas de MCP.

Lo que los agentes hacen mal en iOS

Un balance honesto de dónde fallan los agentes. Conocer estos límites evita frustración y tokens desperdiciados.

Modificaciones de archivos .pbxproj — NUNCA

Esta es la regla más importante en el desarrollo de iOS con agentes. El archivo .pbxproj es la configuración del proyecto de Xcode: un archivo de texto estructurado con referencias UUID, listados de fases de compilación y pertenencia a targets. En teoría es legible para humanos, pero en la práctica es imposible de analizar para agentes de IA.

Por qué los agentes fallan con .pbxproj: - El archivo usa un formato personalizado (no JSON, no YAML, no XML) donde la posición importa - Cada entrada está referenciada de forma cruzada por UUID: agregar un archivo exige actualizar 3-5 secciones distintas de manera consistente - Un solo carácter fuera de lugar corrompe todo el archivo del proyecto - La resolución de conflictos de merge de Xcode para .pbxproj ya es frágil; las ediciones de agentes la empeoran

Qué pasa cuando un agente edita .pbxproj: 1. La edición parece funcionar (el agente informa “file updated”) 2. Xcode se niega a abrir el proyecto (“The project file is corrupted”) 3. Pasas 15-60 minutos recuperándote desde el historial de git 4. Aprendes a agregar el hook PreToolUse (consulta Hooks)

El flujo de trabajo: El agente crea archivos Swift. Tú los agregas manualmente al proyecto de Xcode (arrastrándolos a Xcode, o con File > Add Files). Esto toma 5 segundos por archivo y evita horas de recuperación.

Para proyectos con Swift Package Manager: Esta limitación es menos grave. Package.swift es un archivo Swift estándar que los agentes pueden editar de forma confiable. Si tu proyecto usa SPM exclusivamente (sin .xcodeproj), el agente puede gestionar toda la estructura del proyecto.

Ediciones complejas de Interface Builder / Storyboard

Si tu proyecto usa Interface Builder (archivos .xib) o Storyboards (archivos .storyboard), los agentes no pueden editarlos de forma significativa. Son archivos XML con UUID generados automáticamente, referencias de constraints y conexiones de outlets, diseñados para edición visual, no para edición de texto.

La mitigación: Usa SwiftUI exclusivamente para vistas nuevas. Si tu proyecto tiene archivos heredados de Interface Builder, no los toques y crea la nueva UI en SwiftUI.

Optimización de rendimiento

Los agentes escriben código correcto, pero no necesariamente código eficiente. No pueden perfilar tu app, identificar cuellos de botella ni medir tasas de cuadros. La optimización de rendimiento requiere:

1. Perfilado con Instruments (herramienta visual, no accesible para agentes)
2. Comprender las características de GPU/CPU del dispositivo específico
3. Cambios iterativos guiados por mediciones

Dónde aparece esto: - Optimización de shaders Metal (el agente escribe Metal válido, pero no puede medir el tiempo de cuadro de GPU) - Complejidad del body de vistas SwiftUI (el agente crea vistas profundamente anidadas que generan sobrecarga de redibujado) - Optimización de consultas en Core Data / SwiftData (el agente escribe consultas correctas que pueden ser lentas con datasets grandes)

La mitigación: Usa agentes para la implementación, perfila manualmente con Instruments y luego pídele al agente que aplique optimizaciones específicas que ya identificaste.

Code Signing y Provisioning

Los agentes no pueden depurar problemas de code signing más allá de leer el mensaje de error. La gestión de provisioning profiles, la creación de certificados, la configuración de entitlements y el envío a App Store son flujos de trabajo fundamentalmente operados por humanos que involucran el portal de Apple Developer, Keychain Access y la UI de firma de Xcode.

Lo que ve el agente: “Signing for ‘Return’ requires a development team.”

Lo que el agente no puede ver: Si tu certificado expiró, si el provisioning profile incluye el dispositivo, si el bundle ID coincide con el App ID o si tu archivo de entitlements es correcto.

La mitigación: Maneja toda la firma en la pestaña Signing & Capabilities de Xcode. No pidas a los agentes que depuren fallas de firma.

Depuración compleja de shaders Metal

Los agentes escriben Metal Shading Language (MSL) sintácticamente correcto, pero no pueden verificar la salida visual ni depurar problemas del lado de GPU. Los shaders Metal se ejecutan en GPU; el agente no tiene ningún mecanismo de retroalimentación para saber si el shader produce resultados visuales correctos.

Qué pueden hacer los agentes con Metal: - Escribir shaders de vértices y fragmentos a partir de descripciones - Configurar el pipeline de renderizado Metal en Swift - Crear compute shaders para operaciones paralelas sobre datos - Corregir errores de compilación en archivos .metal

Qué no pueden hacer los agentes con Metal: - Verificar la corrección visual de la salida del shader - Depurar el rendimiento de GPU (tiempo de cuadro, occupancy, ancho de banda de memoria) - Diagnosticar artefactos visuales (banding, problemas de precisión, espacio de color incorrecto) - Probar en distintas arquitecturas de GPU (diferencias de comportamiento entre series A y M)

La mitigación: Prueba los shaders Metal en dispositivos físicos. La implementación de Metal del Simulator no representa el comportamiento de GPU en dispositivos. Usa GPU Frame Capture de Xcode para la depuración visual.

Verificación visual del layout

Los agentes no pueden ver la UI de tu app. Escriben código de layout en SwiftUI y pueden verificar que compile, pero no pueden decir si la pantalla resultante se ve correcta. Una vista que se renderiza 10 píxeles descentrada, usa el grosor de fuente incorrecto o tiene elementos superpuestos no produce errores de compilación y pasa todas las pruebas lógicas.

La mitigación: Revisa visualmente los cambios de UI. Usa SwiftUI Previews en Xcode (o RenderPreview mediante Apple MCP para renderizado headless) para verificar el layout. Considera pruebas de snapshots con bibliotecas como swift-snapshot-testing para detectar regresiones visuales de forma automatizada.

Hooks para el desarrollo en iOS

Los hooks son comandos de shell que se ejecutan de forma determinista en puntos específicos del flujo de trabajo del agente. Son el mecanismo de cumplimiento: la diferencia entre «por favor, no edites .pbxproj» (una sugerencia que el agente puede ignorar) y «no puedes editar .pbxproj» (un bloqueo estricto).

Para conocer los fundamentos del sistema de hooks, consulta la guía de hooks de Claude Code. Esta sección aborda patrones de hooks específicos para iOS.

PreToolUse: bloquear escrituras en .pbxproj

El hook más importante en cualquier proyecto de iOS. Impide que el agente escriba en archivos .pbxproj, directorios .xcodeproj/ y otros archivos administrados por Xcode:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.(pbxproj|xcworkspace|xib|storyboard)$|xcodeproj/|xcworkspace/\"; then echo \"BLOCKED: Do not modify Xcode project files. Create Swift files and add to Xcode manually.\" >&2; exit 2; fi'"
      }
    ]
  }
}

Colócalo en .claude/settings.json, en la raíz del proyecto, o en ~/.claude/settings.json para obtener protección global.

Cómo funciona: Cuando el agente intenta usar la herramienta Edit o Write en cualquier archivo que coincida con el patrón, el hook se ejecuta, detecta la ruta del archivo, imprime una advertencia en stderr y finaliza con el código 2, lo que bloquea el uso de la herramienta. El agente recibe el mensaje de error y ajusta su estrategia.

Qué detecta: - Ediciones directas de .pbxproj - Cualquier archivo dentro de los directorios .xcodeproj/ o .xcworkspace/ - Archivos de Interface Builder (.xib, .storyboard)

PostToolUse: aplicar formato al guardar con SwiftFormat

Aplica formato automáticamente a los archivos Swift cada vez que el agente los escribe o edita:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then swiftformat \"$FP\" --quiet 2>/dev/null; fi'"
      }
    ]
  }
}

Requisitos: SwiftFormat debe estar instalado (brew install swiftformat).

Por qué es importante: Los agentes generan código Swift sintácticamente correcto, pero no siempre siguen las convenciones de formato. SwiftFormat normaliza la sangría, la colocación de llaves y el orden de las importaciones.⁸ Gracias al hook que aplica formato al guardar, todos los archivos Swift que el agente modifica quedan formateados automáticamente antes de que los veas.

Opcional: agrega un archivo de configuración .swiftformat en la raíz del proyecto para personalizar las reglas de formato:

# .swiftformat
--indent 4
--allman false
--stripunusedargs closure-only
--importgrouping testable-bottom
--header strip

PostToolUse: ejecutar SwiftLint automáticamente

Si usas SwiftLint, ejecútalo después de cada edición de un archivo Swift:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then swiftlint lint --path \"$FP\" --quiet 2>/dev/null || true; fi'"
      }
    ]
  }
}

El || true evita que las advertencias del linter bloqueen al agente. Si quieres que las infracciones de lint provoquen un bloqueo, elimínalo.

PostToolUse: compilar automáticamente después de los cambios

Para obtener ciclos de retroalimentación más intensivos, inicia una compilación después de cada cambio en un archivo Swift:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then xcodebuild -scheme Return -destination \"platform=iOS Simulator,name=iPhone 16 Pro\" build 2>&1 | tail -5; fi'"
      }
    ]
  }
}

Advertencia: Esto consume muchos recursos. Cada edición de un archivo inicia una compilación. Úsalo con moderación; resulta más útil durante sesiones de depuración en las que buscas obtener información inmediata sobre la compilación. Para el desarrollo habitual, permite que el agente inicie las compilaciones manualmente mediante MCP cuando esté listo.

PreToolUse: bloquear modificaciones de entitlements

Protege tu archivo de entitlements contra modificaciones accidentales del agente:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.entitlements$\"; then echo \"BLOCKED: Do not modify entitlements files without explicit permission.\" >&2; exit 2; fi'"
      }
    ]
  }
}

Configuración combinada de hooks para iOS

Esta es la configuración completa de .claude/settings.json que uso en todos los proyectos de iOS:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.(pbxproj|xcworkspace|xib|storyboard|entitlements)$|xcodeproj/|xcworkspace/\"; then echo \"BLOCKED: Do not modify Xcode-managed files. Create Swift files and add manually.\" >&2; exit 2; fi'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then swiftformat \"$FP\" --quiet 2>/dev/null; fi'"
      }
    ]
  }
}

Esto te ofrece dos garantías: 1. El agente no puede dañar los archivos de proyecto de Xcode (bloqueo de PreToolUse) 2. Cada archivo Swift que el agente modifica recibe formato automáticamente (formato de PostToolUse)

Patrones de arquitectura que funcionan con agentes

No todas las arquitecturas de Swift son igual de compatibles con los agentes. Estos patrones producen los mejores resultados porque son explícitos, consistentes y están bien representados en los datos de entrenamiento.

@Observable (nunca ObservableObject)

Los proyectos para iOS 26 o posterior deben usar exclusivamente @Observable. Este es tanto el patrón moderno como el más compatible con los agentes:

// CORRECT — @Observable
@Observable
@MainActor
final class TimerManager {
    var timeRemaining: TimeInterval = 0
    var state: TimerState = .stopped

    func start() {
        state = .running
        // ...
    }
}

// In a view:
struct TimerView: View {
    @State private var timer = TimerManager()

    var body: some View {
        Text(timer.timeRemaining, format: .number)
    }
}

// WRONG — ObservableObject (deprecated pattern)
class TimerManager: ObservableObject {
    @Published var timeRemaining: TimeInterval = 0
    @Published var state: TimerState = .stopped
}

// WRONG — @StateObject (deprecated pattern)
struct TimerView: View {
    @StateObject private var timer = TimerManager()
}

Por qué @Observable es compatible con los agentes: El patrón es más sencillo (no necesita anotaciones @Published), el modelo de propiedad es más claro (@State en lugar de elegir entre @StateObject y @ObservedObject) y los agentes producen menos errores al usarlo porque tiene menos elementos involucrados.

Documenta esto en CLAUDE.md: Incluso cuando el objetivo es iOS 26, los agentes ocasionalmente vuelven a los patrones de ObservableObject presentes en sus datos de entrenamiento. Prohibirlos explícitamente evita que esto ocurra.

NavigationStack (nunca NavigationView)

// CORRECT
NavigationStack {
    List(items) { item in
        NavigationLink(value: item) {
            ItemRow(item: item)
        }
    }
    .navigationDestination(for: Item.self) { item in
        ItemDetailView(item: item)
    }
}

// WRONG
NavigationView {
    List(items) { item in
        NavigationLink(destination: ItemDetailView(item: item)) {
            ItemRow(item: item)
        }
    }
}

NavigationStack está disponible desde iOS 16 y es el único patrón de navegación que debes usar para código nuevo. El patrón navigationDestination(for:), con seguridad de tipos, evita que el agente cree enlaces de navegación incorrectos.

SwiftData para la persistencia

Los modelos de SwiftData constituyen el patrón de persistencia más claro para el desarrollo asistido por agentes:

@Model
final class GroceryItem {
    var name: String
    var quantity: Int
    var isCompleted: Bool
    var category: Category?
    var list: GroceryList?

    init(name: String, quantity: Int = 1) {
        self.name = name
        self.quantity = quantity
        self.isCompleted = false
    }
}

Reglas clave para los agentes que trabajan con SwiftData: 1. Las clases @Model son automáticamente Observable; no agregues @Observable 2. Usa @Bindable para los enlaces de formularios: @Bindable var item: GroceryItem 3. Usa @Query en las vistas para obtener datos reactivos: @Query var items: [GroceryItem] 4. Usa modelContext.fetch() en el código que no pertenece a una vista 5. Las eliminaciones de relaciones necesitan reglas explícitas: .cascade, .nullify, .deny

Concurrencia de Swift 6.2

Configura la concurrencia estricta de Swift 6.2 en proyectos nuevos. Se trata de una elección del modo del lenguaje, no de la versión de la cadena de herramientas: tanto el compilador de Swift 6.3 incluido en la versión estable de Xcode 26.6 como Swift 6.4 en la versión beta de Xcode 27 compilan estos patrones sin cambios:¹⁷¹⁸

// Actor isolation for shared mutable state
@MainActor
@Observable
final class DataManager {
    var items: [Item] = []

    func loadItems() async throws {
        let fetched = try await api.fetchItems()
        items = fetched  // Safe: @MainActor isolated
    }
}

// Sendable conformance for cross-actor transfers
struct Item: Sendable, Identifiable {
    let id: UUID
    let name: String
    let createdAt: Date
}

Indicaciones para agentes sobre concurrencia: - Marca todos los modelos de vista con @MainActor (evita advertencias sobre condiciones de carrera) - Usa async/await para todo el trabajo asíncrono (sin manejadores de finalización) - Haz que los tipos por valor sean Sendable para transferirlos entre actores - Usa Task { } en las vistas para la inicialización asíncrona - Usa nonisolated únicamente cuando hayas medido una necesidad de rendimiento

Sistema de diseño Liquid Glass (iOS 26 o posterior)

iOS 26 introdujo el sistema de diseño Liquid Glass. Los agentes lo manejan bien cuando reciben indicaciones explícitas:

// Glass effect on containers
VStack {
    // content
}
.glassEffect()

// Glass effect with tint
Button("Action") { }
    .glassEffect(.regular.tint(.blue))

// Glass effect on navigation bars (automatic in iOS 26)
NavigationStack {
    // content
}
// Navigation bar automatically uses glass material

// Custom glass shapes
RoundedRectangle(cornerRadius: 16)
    .fill(.ultraThinMaterial)
    .glassEffect()

Incluye esto en CLAUDE.md: «Usa .glassEffect() en los fondos de las secciones y los contenedores de tarjetas. Las barras de navegación adoptan automáticamente el material de vidrio en iOS 26. No recrees manualmente efectos de vidrio con materiales personalizados; usa el modificador del sistema».

Contexto específico de cada framework

Cada framework de Apple presenta consideraciones específicas para los agentes. Esta sección aborda los frameworks utilizados en las 8 aplicaciones.

HealthKit

Aplicaciones que lo usan: Return, Water

HealthKit requiere gestionar cuidadosamente los permisos y las comprobaciones de plataforma:

// Always check availability and authorization
import HealthKit

@MainActor
@Observable
final class HealthKitManager {
    private let store = HKHealthStore()
    var isAuthorized = false

    func requestAuthorization() async {
        guard HKHealthStore.isHealthDataAvailable() else { return }

        let types: Set<HKSampleType> = [
            HKQuantityType(.dietaryWater),
            HKCategoryType(.mindfulSession)
        ]

        do {
            try await store.requestAuthorization(toShare: types, read: types)
            isAuthorized = true
        } catch {
            // User denied — do not retry automatically
        }
    }
}

Reglas para agentes que trabajan con HealthKit: - Comprueba siempre la disponibilidad con HKHealthStore.isHealthDataAvailable() - Nunca des por sentada la autorización; compruébala en cada escritura - Usa #if canImport(HealthKit) para código multiplataforma (HealthKit no está disponible en tvOS) - Nunca almacenes datos de salud localmente más allá de lo que proporciona HealthKit - Incluye tanto NSHealthShareUsageDescription como NSHealthUpdateUsageDescription en Info.plist

SpriteKit

Aplicaciones que lo usan: TappyColor, Starfield Destroyer

El modelo de grafo de escenas de SpriteKit requiere instrucciones explícitas para el agente:

## SpriteKit Rules

- Scene hierarchy is a tree of SKNodes with zPosition ordering
- Physics bodies use category bitmasks (UInt32) for collision detection
- Node pooling: pre-allocate reusable nodes (bullets, particles)
- Never add nodes directly to the scene — use layer nodes for organization
- Update loop: `update(_ currentTime:)` runs every frame — keep it fast
- Actions: use SKAction sequences for animations, not manual property updates
- Textures: use texture atlases for performance (.atlas directories)

Fortalezas de los agentes con SpriteKit: - Crear secuencias y grupos de SKAction - Configurar cuerpos físicos y la detección de contactos - Implementar máquinas de estados del juego - Crear superposiciones del HUD

Debilidades de los agentes con SpriteKit: - Bucles de juego sensibles al rendimiento (el agente agrega trabajo innecesario en cada fotograma) - Simulaciones físicas complejas (la física personalizada supera a SKPhysicsBody en precisión) - Ajuste de efectos de partículas (es visual y requiere iteración)

Metal

Aplicaciones que lo usan: amp97, Water, Starfield Destroyer

Metal es el framework con el que los agentes tienen más dificultades. El modelo de programación GPU es fundamentalmente diferente del Swift que se ejecuta en la CPU, y los agentes no pueden verificar el resultado visual.

## Metal Rules

- Shared types between Swift and Metal go in a bridging header (ShaderTypes.h)
- Triple buffer in-flight frames (semaphore with value 3)
- Test shaders on DEVICE, not simulator (Metal behavior differs)
- Compute shaders: threadgroup size must divide evenly into grid size
- Fragment shaders: output color must be in correct color space (sRGB or linear)
- DO NOT optimize shaders without Instruments GPU profiling data

Qué incluir en CLAUDE.md para proyectos de Metal: - La definición de la estructura Uniforms (compartida entre Swift y MSL) - El patrón de configuración del estado de la canalización de renderizado - Los índices de los búferes y sus propósitos - Qué shaders existen y qué hace cada uno - Problemas de precisión conocidos (half frente a float)

Live Activities

Aplicaciones que lo usan: Return

Live Activities requiere una configuración específica que los agentes manejan bien una vez documentada:

## Live Activities

- ActivityAttributes defined in `TimerActivityAttributes.swift`
- ActivityKit framework: `import ActivityKit`
- Widget extension: `ReturnWidgets/ReturnLiveActivity.swift`
- Start: `Activity<TimerActivityAttributes>.request(attributes:content:)`
- Update: `activity.update(ActivityContent(state:staleDate:))`
- End: `activity.end(ActivityContent(state:staleDate:), dismissalPolicy:)`
- Push token: register for updates via `activity.pushTokenUpdates`

Game Center

Aplicaciones que lo usan: Starfield Destroyer

## Game Center

- Authentication: `GKLocalPlayer.local.authenticateHandler`
- Leaderboards: `GKLeaderboard.submitScore(_:context:player:leaderboardIDs:completionHandler:)`
- Achievements: `GKAchievement.report(_:withCompletionHandler:)` (takes `[GKAchievement]` array)
- Always check `GKLocalPlayer.local.isAuthenticated` before submitting
- Handle authentication failure gracefully (offline play must work)

Patrones multiplataforma

Return abarca iOS, watchOS y tvOS. El desarrollo multiplataforma con agentes requiere documentación explícita de los límites entre plataformas.

Organización del código compartido

Shared/
├── MeditationSession.swift    # Data model (all platforms)
├── SessionStore.swift         # iCloud sync (all platforms)
└── SessionHistoryView.swift   # UI (adapts per platform)

Return/                        # iOS-specific
ReturnWatch Watch App/         # watchOS-specific
ReturnTV/                      # tvOS-specific

Regla para los agentes: “Si un archivo está en Shared/, los cambios afectan a todas las plataformas. Si un archivo está en un directorio de plataforma, los cambios están aislados. Siempre verifica en qué directorio se encuentra un archivo antes de modificarlo.”

Guardas de disponibilidad por plataforma

// HealthKit: available on iOS and watchOS, not tvOS
#if canImport(HealthKit)
import HealthKit
// HealthKit code here
#endif

// ActivityKit: available on iOS only
#if canImport(ActivityKit)
import ActivityKit
// Live Activity code here
#endif

// WatchKit: available on watchOS only
#if os(watchOS)
import WatchKit
// Watch-specific code here
#endif

Guía para agentes: “Usa siempre guardas #if canImport() o #if os() al utilizar frameworks específicos de una plataforma. No supongas que un framework está disponible en todos los targets.”

Adaptación de UI por plataforma

struct SessionHistoryView: View {
    @Query var sessions: [MeditationSession]

    var body: some View {
        List(sessions) { session in
            SessionRow(session: session)
        }
        #if os(tvOS)
        .focusable()
        #endif
        #if os(iOS)
        .swipeActions {
            Button("Delete", role: .destructive) {
                // delete
            }
        }
        #endif
    }
}

Flujos de trabajo avanzados

Bucles autónomos de compilación, pruebas y corrección

El patrón más potente: proporciona al agente una especificación de la función y deja que itere de forma autónoma mediante ciclos de compilación, pruebas y corrección.

Implement a countdown timer that:
1. Starts from a user-selected duration (10, 20, or 30 minutes)
2. Shows remaining time with a circular progress indicator
3. Plays a bell sound on completion
4. Logs the session to HealthKit as mindful minutes

Build after each change. Fix all errors. Run tests when the build succeeds.
Continue until all tests pass and the build is clean.

El agente escribe código, compila mediante MCP, lee los errores estructurados, los corrige y repite el proceso. Una función que requeriría entre 5 y 10 ciclos humanos de compilación, error y corrección se completa en un único bucle autónomo.

Cuándo funciona: Funciones bien definidas con criterios de aceptación claros.

Cuándo falla: Funciones abiertas (“haz que se vea bien”), código sensible al rendimiento o cualquier cosa que requiera verificación visual.

Delegación a subagentes para iOS

El sistema de subagentes de Claude Code funciona para proyectos de iOS:

Use a subagent to research the best approach for implementing
iCloud key-value store sync for meditation sessions across iOS,
watchOS, and tvOS. Report back with the recommended pattern.

El subagente explora la documentación y los patrones de código en una ventana de contexto separada, devuelve un resumen y la sesión principal implementa la recomendación. Esto evita que la investigación consuma tu contexto principal.

Aplicación de patrones entre apps

Cuando mantienes varias apps de iOS con patrones consistentes, los agentes pueden aplicar patrones de una app a otra:

Look at how Settings.swift works in the Return project
(centralized singleton with validation). Apply the same pattern
to create a Settings.swift for the Water project.

El agente lee el patrón de origen, comprende la estructura y crea una implementación coherente en el proyecto de destino.

Revisión con dos agentes (Claude + Codex)

Para cambios críticos, usa dos agentes de familias de modelos diferentes:

1. Claude Code escribe la implementación
2. Codex CLI la revisa en una pasada independiente

# After Claude implements the feature:
codex "Review the changes in the last commit. Focus on Swift 6.2
      concurrency correctness, SwiftData relationship integrity,
      and potential retain cycles. Report issues only — no praise."

Las distintas familias de modelos detectan diferentes tipos de errores. Esto resulta especialmente valioso para shaders de Metal y patrones de concurrencia, donde es fácil introducir errores sutiles.

Lo que la revisión dual detecta y la revisión individual pasa por alto:

La revisión dual no consiste en encontrar más errores, sino en encontrar errores diferentes. Cada familia de modelos presenta distintos modos de fallo en su reconocimiento de patrones.

Operaciones por lotes en varias apps

Cuando un cambio de framework o patrón afecta a varias apps:

# Update @Observable pattern across all projects
for project in BananaList Return Water Reps; do
  cd ~/Projects/$project
  claude -p "Audit all files for any remaining ObservableObject usage.
             Convert to @Observable following the pattern in CLAUDE.md.
             Build and test after changes." --dangerously-skip-permissions
done

Úsalo con precaución. La bandera --dangerously-skip-permissions es necesaria para el modo no interactivo, pero omite todas las comprobaciones de seguridad. Asegúrate de que tus hooks de PreToolUse estén configurados para proteger los archivos .pbxproj.

Apps que usan LLM en el dispositivo de Apple

Si tu app llama al framework Foundation Models de Apple (por ejemplo, para resúmenes sin conexión, clasificación o generación de resultados estructurados), los agentes deben conocer el presupuesto de prompts. iOS 26.4 añadió dos API a SystemLanguageModel que reemplazaron la estimación anterior de 4096 tokens: contextSize (la cantidad máxima de tokens que el modelo acepta en una sola conversación) y tokenCount(for:) (async throws, devuelve cuántos tokens cuesta realmente un prompt determinado).³¹ Ambos son @backDeployed(before: iOS 26.4), por lo que están disponibles en todas las versiones de OS compatibles con FM sin una escalera de #available.

El patrón que debe seguir un agente al generar código de construcción de prompts:

import FoundationModels

func budgetFor(prompt: String, reservedReply: Int = 256) async throws -> Int {
    let model = SystemLanguageModel.default
    let promptCost = try await model.tokenCount(for: prompt)
    let budget = model.contextSize - promptCost - reservedReply
    guard budget > 0 else { throw ContextError.promptTooLong }
    return budget
}

Agrega este patrón a tu CLAUDE.md si la app usa SystemLanguageModel. Sin él, los agentes recurren al antiguo valor fijo de 4096 y truncan los prompts de forma silenciosa en dispositivos con ventanas de contexto más grandes. La firma async throws de tokenCount(for:) es fundamental: los agentes que peguen una versión síncrona no podrán compilar.

Estudios de caso reales

El consejo abstracto es fácil. Estos son escenarios específicos de las 8 apps que muestran cómo funciona en la práctica el desarrollo de iOS asistido por agentes, incluidos los fallos.

Estudio de caso 1: Agregar una app de TV a Return (éxito)

La tarea: Agregar un target de tvOS a Return, un temporizador de meditación que ya tenía versiones para iOS y watchOS. La app de TV necesitaba navegación con Siri Remote, una UI para pantalla grande y sincronización de configuración con la app de iOS.

Lo que el agente hizo bien: - Leyó el TimerManager existente de iOS y creó un TVTimerManager que omitía Live Activities y HealthKit (no disponibles en tvOS) - Creó estilos de botones personalizados para la navegación por foco con Siri Remote (TVCapsuleButtonStyle, TVCircleButtonStyle) - Construyó un componente TVStepper que reemplaza los selectores de rueda (no utilizables con Siri Remote) por botones +/- - Implementó sincronización de configuración mediante App Groups (group.com.941apps.Return) - Agregó protecciones #if os(tvOS) en todo el código compartido - Compiló y probó mediante MCP con platform=tvOS Simulator,name=Apple TV

Lo que tuve que hacer manualmente: - Crear el target de tvOS en Xcode (File > New > Target > tvOS App) - Agregar el nuevo target al proyecto de Xcode (cambios en .pbxproj) - Configurar el entitlement de App Groups para el target de TV - Agregar el target de TV al scheme existente o crear uno nuevo - Agregar manualmente todos los archivos Swift creados por el agente al target de TV - Probar a mano la navegación con Siri Remote (el agente no puede evaluar el comportamiento del foco)

Resultado: 15 archivos Swift nuevos, una app de TV completamente funcional, en aproximadamente 3 horas de trabajo asistido por agente. Según mi estimación, el agente se encargó de cerca del 80% del trabajo de implementación; yo me ocupé de las partes que requerían interacción con la UI de Xcode (entitlements, configuración del target, flags de capacidades) y pruebas manuales de foco en un Apple TV real. El trabajo equivalente en solitario en este codebase, con base en funciones similares que he enviado sin agentes, habría tomado varios días.

Estudio de caso 2: Depuración de Metal Shader en amp97 (fallo parcial)

La tarea: Agregar un sistema de intensidad basado en energía al shader del osciloscopio. La visualización debía pulsar con la energía del audio.

Lo que ocurrió: 1. El agente escribió una modificación válida del Metal shader que agregaba un uniform uEnergy y HDR tonemapping 2. El código compiló sin errores 3. En el dispositivo, la visualización era completamente blanca: el coeficiente de intensidad era 10 veces demasiado alto (3,5 en lugar de 0,30) 4. El agente no podía ver la pantalla blanca, así que no tenía una señal de retroalimentación 5. Identifiqué el problema visualmente y le pedí al agente que redujera el coeficiente 6. El agente lo redujo, pero la máquina de estados de energía en general era demasiado compleja y rompió el visualizador de otras maneras 7. Se revirtió por completo: dos commits (67959ed y cda4830) revertidos en 869d914

La lección: Los Metal shaders son el dominio más difícil para el desarrollo asistido por agentes porque el ciclo de retroalimentación está roto. El agente puede verificar la sintaxis (compila) y la semántica (tipos correctos), pero no puede verificar el resultado (se ve bien). Cualquier modificación de shader que cambie el comportamiento visual requiere verificación humana en el dispositivo.

Lo que agregué a CLAUDE.md después de esto: “DO NOT attempt energy state modifications to the oscilloscope shader without extremely careful coefficient testing. Previous attempt broke the visualizer with coefficients 10x too high.”

Estudio de caso 3: Migración de SwiftData en Banana List (éxito)

La tarea: Migrar el modelo de datos de V1 a V2, agregando un campo quantity a GroceryItem y un nuevo modelo Category con relaciones.

Lo que hizo el agente: 1. Leyó las definiciones existentes del modelo V1 2. Creó definiciones del modelo V2 con los nuevos campos y relaciones 3. Escribió un GroceryMigrationPlan con conformidad al protocolo SchemaMigrationPlan 4. Implementó la etapa de migración V1toV2: agregó quantity: 1 y category: nil predeterminados 5. Actualizó todas las vistas para admitir los nuevos campos 6. Actualizó SampleData.swift para previews 7. Compiló y ejecutó pruebas mediante MCP; todas pasaron 8. Creó pruebas unitarias específicas para la migración

La clave: El agente tuvo éxito porque las migraciones de SwiftData siguen un patrón de protocolo bien definido que está ampliamente representado en la documentación de Apple y en los datos de entrenamiento. El CLAUDE.md documentaba explícitamente el modelo V1, así que el agente entendió desde qué estaba migrando.

Estudio de caso 4: Sincronización de sesiones de iCloud en Return (éxito con complejidad)

La tarea: Implementar registro de sesiones de meditación entre dispositivos. Las sesiones completadas en Apple TV o Mac debían sincronizarse con iPhone para el registro en HealthKit.

Lo que produjo el agente:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    tvOS     │     │    Mac      │     │   Watch     │
│ TVTimerMgr  │     │ TimerMgr    │     │ WatchTimer  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │     SessionStore       │
              │  (iCloud Key-Value)    │
              └───────────┬────────────┘
                          │
                          ▼
              ┌────────────────────────┐
              │  iPhone (on foreground)│
              │  → Write to HealthKit  │
              └────────────────────────┘

El agente: 1. Creó el modelo de datos MeditationSession con UUID, fechas, duración, dispositivo de origen y estado de sincronización con HealthKit 2. Construyó el singleton SessionStore, que gestiona NSUbiquitousKeyValueStore para sincronización con iCloud 3. Implementó resolución de conflictos de fusión (deduplicación basada en UUID) 4. Agregó SessionHistoryView con adaptaciones específicas por plataforma (deslizar para eliminar en iOS, basado en foco en tvOS) 5. Conectó la sincronización con HealthKit del lado del iPhone para sesiones provenientes de otros dispositivos

Lo que requirió iteración: La implementación inicial no manejaba el caso en que la app de iPhone se inicia en segundo plano (sin notificación en primer plano para sincronizar). El agente necesitó una indicación específica: “Use NSUbiquitousKeyValueStore.didChangeExternallyNotification to trigger sync on background KV changes.” Después de esa pista, la implementación fue correcta.

La lección: Los agentes manejan bien los patrones arquitectónicos multiplataforma cuando la arquitectura está descrita con claridad. El patrón de sincronización con iCloud no es trivial, pero sigue un patrón documentado de Apple que el agente entendió. El caso límite (sincronización en segundo plano) requirió conocimiento humano del dominio porque no está bien documentado.

Estudio de caso 5: Integración de Game Center en Starfield Destroyer (éxito)

La tarea: Agregar leaderboards y achievements de Game Center al shooter espacial.

Lo que el agente hizo bien: - Implementó GKLocalPlayer.local.authenticateHandler en el punto de entrada de la app - Creó un GameCenterManager con métodos para enviar puntuaciones y reportar achievements - Agregó verificación del estado de autenticación antes de todas las operaciones de Game Center - Manejó correctamente el caso offline (el juego funciona sin Game Center y envía los datos al reconectarse) - Creó definiciones de achievements que coinciden con el sistema de progresión de 8 naves

Lo que requirió trabajo manual: - Crear los leaderboards y achievements en App Store Connect (portal web, no accesible para el agente) - Configurar el entitlement de Game Center en Xcode - Probar con una cuenta sandbox de Game Center (requiere iniciar sesión manualmente en el dispositivo)

Ciclo de vida del proyecto con agentes

Iniciar un nuevo proyecto de iOS

El flujo de trabajo óptimo para iniciar un proyecto nuevo con ayuda de agentes:

Fase 1: Configuración humana (15-30 minutos) 1. Crea el proyecto de Xcode (File > New > Project) 2. Configura la firma y las capacidades 3. Define el destino de implementación y los destinos compatibles 4. Agrega cualquier entitlement requerido (HealthKit, Game Center, etc.) 5. Crea el CLAUDE.md inicial con la identidad y las reglas del proyecto

Fase 2: Implementación con el agente (horas a días) 1. El agente crea el modelo de datos (SwiftData, Core Data o structs simples) 2. El agente construye las vistas siguiendo tus patrones documentados 3. El agente implementa la lógica de negocio en clases manager/service 4. El agente escribe pruebas unitarias 5. Ciclo build-test-fix mediante MCP (autónomo)

Fase 3: Integración humana (30-60 minutos) 1. Agrega los archivos creados por el agente a los targets de Xcode 2. Verifica la firma y los entitlements 3. Prueba en un dispositivo físico 4. Revisa el diseño visual y la UX 5. Envía a App Store Connect

Mantener un proyecto existente

Para el desarrollo continuo en apps ya establecidas:

You: Here's the next feature for Return: add a "Focus Score" that
     calculates from session duration and consistency. Show it on
     the main timer view. Build and test.

Claude: [reads CLAUDE.md, understands patterns]
        [reads TimerManager.swift, Settings.swift]
        [creates FocusScore.swift — model with calculation logic]
        [creates FocusScoreView.swift — display component]
        [integrates into ContentView.swift]
        [calls build_sim — 1 error: missing import]
        [fixes import]
        [calls build_sim — success]
        [writes FocusScoreTests.swift]
        [calls test_sim — all pass]

La efectividad del agente escala según qué tan bien tu CLAUDE.md refleje el estado actual del proyecto. Actualiza tu CLAUDE.md cuando agregues funciones nuevas importantes, cambies patrones arquitectónicos o introduzcas nuevos frameworks.

Cuándo involucrar al agente y cuándo no

Configurar definiciones de agentes

Si usas el sistema de definición de agentes de Claude Code (.claude/agents/), crea un agente específico para iOS:

---
name: ios-developer
description: iOS development agent with MCP build tools and SwiftUI expertise
tools:
  - XcodeBuildMCP
  - xcode
---

# iOS Developer Agent

You are an iOS development agent for apps targeting iOS 26+ with SwiftUI.

## Architecture Rules
- @Observable for all view models (NEVER ObservableObject)
- NavigationStack for all navigation (NEVER NavigationView)
- SwiftData for persistence
- Swift 6.2 strict concurrency
- @MainActor on all Observable classes

## Build & Test — Always Use MCP

Prefer MCP tools over raw shell commands for ALL build operations:

- **Build**: `build_sim` / `build_device` (NOT `xcodebuild` via Bash)
- **Test**: `test_sim` / `test_device` (NOT `xcodebuild test` via Bash)
- **Simulators**: `list_sims`, `boot_sim`, `open_sim`
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple docs**: `DocumentationSearch` (NOT WebSearch for Apple APIs)
- **Swift verification**: `ExecuteSnippet` (NOT `swift` via Bash)

MCP returns structured JSON. Bash returns unstructured text.

## File Management Rules
- NEVER modify .pbxproj, .xcodeproj/, .xcworkspace/, .xib, .storyboard
- Create Swift files in the correct directory
- Report files that need manual addition to Xcode targets

## SwiftData Rules
- @Model classes are automatically Observable — do not add @Observable
- Use @Bindable for form bindings to model properties
- Use @Query in views, modelContext.fetch() elsewhere
- Document relationship delete rules

## When You Get Stuck
- Build errors: use `build_sim` via MCP for structured output
- API questions: use `DocumentationSearch` via Apple MCP
- Swift verification: use `ExecuteSnippet` via Apple MCP
- Never guess — verify with tools

Referencia este agente con @ios-developer en sesiones de Claude Code.

Patrones de prueba para iOS asistido por agentes

Los agentes escriben pruebas unitarias excelentes cuando reciben una guía clara. Estos son los patrones que producen los mejores resultados.

Organización de archivos de prueba

# In CLAUDE.md:
## Test Structure

Tests mirror source structure:
- `ReturnTests/TimerManagerTests.swift` tests `TimerManager.swift`
- `ReturnTests/SettingsTests.swift` tests `Settings.swift`
- `ReturnTests/ConstantsTests.swift` tests `Constants.swift`

Test naming: `test_<what>_<condition>_<expected>`
Example: `test_start_whenStopped_transitionsToRunning`

Prompts para pruebas

Prompt de prueba efectivo:

Write unit tests for TimerManager covering:

1. Initial state is .stopped with timeRemaining == selectedDuration
2. start() transitions state to .running
3. pause() from .running transitions to .paused
4. reset() from any state returns to .stopped with original duration
5. start() from .paused resumes (state becomes .running)
6. Edge case: reset() when already stopped is a no-op
7. Edge case: pause() when already paused is a no-op

Follow the existing test pattern in SettingsTests.swift.
Use setUp() to create a fresh TimerManager for each test.

Por qué funciona: Los criterios de aceptación numerados le dan al agente una lista de verificación. Referenciar un archivo de prueba existente establece el patrón. Especificar el uso de setUp() evita que el agente cree estados de prueba enredados.

Prompt de prueba ineficaz:

Write tests for TimerManager.

Esto produce pruebas genéricas y superficiales que pasan por alto casos límite y quizá no sigan los patrones de tu proyecto.

Patrones de pruebas async

Para probar código basado en temporizadores y async:

// Agent produces this pattern when guided correctly:
final class TimerManagerTests: XCTestCase {
    var sut: TimerManager!

    @MainActor
    override func setUp() {
        super.setUp()
        sut = TimerManager()
    }

    @MainActor
    func test_start_whenStopped_transitionsToRunning() {
        // Given
        XCTAssertEqual(sut.state, .stopped)

        // When
        sut.start()

        // Then
        XCTAssertEqual(sut.state, .running)
    }

    @MainActor
    func test_timerCountsDown_afterOneSecond() async throws {
        // Given
        sut.selectedDuration = 10
        sut.reset()
        sut.start()

        // When
        try await Task.sleep(for: .seconds(1.1))

        // Then
        XCTAssertLessThanOrEqual(sut.timeRemaining, 9.0)
    }
}

Patrones clave que los agentes necesitan que les recuerdes: - @MainActor en métodos de prueba que prueban clases @MainActor - async throws para pruebas que usan Task.sleep u operaciones async - Tolerancia en aserciones basadas en tiempo (1,1 segundos, no exactamente 1,0) - setUp() / tearDown() limpios para aislar las pruebas

Snapshot Testing

Para detectar regresiones visuales, considera agregar swift-snapshot-testing:

Add snapshot tests for the main timer view in three states:
1. Stopped (showing full duration)
2. Running (showing countdown)
3. Completed (showing 00:00 with completion state)

Use SnapshotTesting library. Create reference images on first run.

Los agentes configuran correctamente las pruebas de snapshot, pero no pueden revisar las imágenes de referencia. Tú revisas los snapshots iniciales; luego, las pruebas del agente detectan regresiones visuales en cambios futuros.

Gestión de la ventana de contexto para proyectos de iOS

La ventana de contexto de 1M (Opus 5) es amplia, pero no infinita. Los proyectos de iOS requieren consideraciones específicas para gestionar el contexto.

Costo en tokens de los archivos de iOS

Para un proyecto de 50 archivos: Leer todos los archivos consume aproximadamente entre 50.000 y 100.000 tokens, muy por debajo del límite de la ventana de 1M. El agente puede mantener todo el proyecto en contexto.

Para un proyecto de más de 100 archivos: Es necesario leer de forma selectiva. El agente lee primero CLAUDE.md (para conocer las anotaciones de la estructura de archivos) y después consulta archivos específicos según sea necesario. Por eso, las anotaciones de archivos en CLAUDE.md son fundamentales: guían al agente hacia los archivos correctos sin que tenga que leerlos todos.

Estrategias para proyectos grandes

1. Anotaciones detalladas de archivos en CLAUDE.md — El agente consulta el mapa de archivos y navega directamente a los archivos pertinentes
2. Delegación a subagentes — Delega la exploración y la investigación a subagentes (con un contexto limpio que devuelve resúmenes)
3. Indicaciones específicas — “Modifica SettingsView.swift para agregar un nuevo interruptor” es mejor que “actualiza la configuración”
4. Límites entre sesiones — Inicia sesiones nuevas para funciones que no estén relacionadas, en vez de prolongar una sesión extensa
5. Usa /compact — El comando de compactación de Claude Code resume la conversación y libera espacio de contexto

Eficiencia de tokens de MCP

Uno de los argumentos más sólidos a favor de MCP: las respuestas estructuradas de JSON consumen muchos menos tokens que la salida sin procesar de xcodebuild.

Durante una sesión de desarrollo típica con 10-20 ciclos de compilación, MCP ahorra entre 30.000 y 150.000 tokens en comparación con xcodebuild sin procesar; esos tokens quedan disponibles para el razonamiento sobre el código.

Solución de problemas

“build_sim falló: no se encontró el esquema”

El agente está adivinando el nombre del esquema. Solución:

Use discover_projs and list_schemes to find the correct scheme name
for this project before building.

O agrega explícitamente el nombre del esquema a tu CLAUDE.md:

## Build
Primary scheme: `Return` (iOS)
Watch scheme: `ReturnWatch` (watchOS)
TV scheme: `ReturnTV` (tvOS)

“xcrun mcpbridge: no se encontró el comando”

Necesitas Xcode 26.3 o una versión posterior. Compruébalo con xcodebuild -version. Si tienes Xcode 26.3 o posterior, pero el comando continúa fallando:

# Ensure Xcode command line tools are selected
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

# Verify
xcrun mcpbridge --help

“Las herramientas de MCP no aparecen en Claude Code”

Es posible que las herramientas de MCP registradas durante una sesión no aparezcan hasta que reinicies. Sal de Claude Code e inicia una sesión nueva:

# Exit current session (Ctrl+C or /exit)
# Start fresh
claude

Después, verifica:

You: List all available MCP tools from XcodeBuildMCP.

“El agente continúa usando xcodebuild mediante Bash en lugar de MCP”

El agente no está detectando las herramientas de MCP mediante Tool Search. Hay dos soluciones:

1. Agrega instrucciones explícitas a CLAUDE.md (consulta Cómo enseñar al agente a usar MCP)
2. Indícalo directamente: “Usa la herramienta build_sim de MCP, no xcodebuild mediante Bash”

“La compilación se completa correctamente, pero el agente informa que falló”

XcodeBuildMCP analiza la salida de xcodebuild. Si la compilación genera advertencias que parecen errores (algo habitual con las advertencias de obsolescencia), el agente podría interpretar mal el resultado. Comprueba el campo de estado real en la respuesta de MCP.

“El simulador se bloquea durante el arranque”

Cierra todos los simuladores y reinícialos:

xcrun simctl shutdown all
xcrun simctl boot "iPhone 16 Pro"

O pídeselo al agente:

Shut down all simulators, then boot a fresh iPhone 16 Pro.

“El agente intentó modificar .pbxproj a pesar de las reglas de CLAUDE.md”

Las reglas de CLAUDE.md son sugerencias. Los hooks hacen que se cumplan. Si no tienes el hook PreToolUse que bloquea las escrituras en .pbxproj, tarde o temprano el agente intentará modificarlo. Instala el hook:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.(pbxproj|xcworkspace|xib|storyboard)$|xcodeproj/|xcworkspace/\"; then echo \"BLOCKED: Do not modify Xcode project files.\" >&2; exit 2; fi'"
      }
    ]
  }
}

Las reglas dicen “por favor, no lo hagas”. Los hooks dicen “no puedes hacerlo”.

Preguntas frecuentes

¿Con qué entorno de ejecución de agentes debería comenzar?

Claude Code CLI con XcodeBuildMCP. Ofrece la integración con MCP más completa, el sistema de hooks más maduro y la ventana de contexto de 1 millón de tokens (Opus 5), capaz de mantener proyectos completos de iOS en la memoria de trabajo. Comienza aquí; a medida que madure tu flujo de trabajo, agrega Codex para las revisiones y los agentes nativos de Xcode para hacer ediciones rápidas directamente en el código.

¿Necesito ambos servidores MCP?

Para la mayoría de los desarrolladores, XcodeBuildMCP por sí solo cubre el 90 % de las necesidades (compilaciones, pruebas, simuladores y depuración). Agrega Xcode MCP de Apple si quieres buscar documentación, verificar código con Swift REPL o renderizar vistas previas de SwiftUI. Siempre puedes incorporarlo después, ya que ambos servidores son independientes.

¿Pueden los agentes crear un proyecto nuevo de Xcode desde cero?

XcodeBuildMCP incluye herramientas de creación de estructuras (scaffold_ios_project, scaffold_macos_project) que generan nuevos proyectos de Xcode a partir de plantillas. No obstante, para aplicaciones de producción, recomiendo crear el proyecto en Xcode (para configurar correctamente la firma, las capacidades y el destino) y luego usar agentes para implementar todo el código. Los 5 minutos que dediques al asistente de proyectos nuevos de Xcode te ahorrarán horas de problemas con la configuración de proyectos generada por agentes.

¿Cómo gestionan los agentes las dependencias de Swift Package Manager?

Bien. Package.swift es un archivo estándar de Swift que los agentes pueden leer y editar de forma confiable. Pueden agregar dependencias, actualizar intervalos de versiones y configurar destinos sin problemas. La limitación es la gestión de dependencias basada en .xcodeproj (la interfaz de resolución de paquetes de Xcode): Xcode se encarga de ella y los agentes no deberían editarla.

¿Pueden los agentes enviar una aplicación a la App Store?

No. El envío a la App Store implica usar Organizer de Xcode, perfiles de aprovisionamiento, capturas de pantalla, metadatos y el portal de App Store Connect. Ninguno de estos elementos es accesible mediante MCP ni herramientas de línea de comandos de una forma que los agentes puedan operar de manera útil. Los agentes se encargan de todo hasta la creación del archivo de distribución: implementación, pruebas, corrección de errores y documentación. La etapa final del envío sigue requiriendo intervención humana.

No obstante, los agentes pueden ayudarte con los metadatos de la App Store. Pídele al agente que redacte la descripción de la aplicación, las palabras clave y el texto de novedades a partir de los cambios más recientes. Este es un trabajo de generación de texto en el que los agentes sobresalen.

¿Cómo gestiono los secretos y las claves de API durante el desarrollo de iOS asistido por agentes?

Nunca confirmes secretos en el repositorio. Para aplicaciones de iOS que se conectan a APIs de backend:

1. Usa archivos .xcconfig para la configuración específica de cada entorno
2. Agrega los archivos .xcconfig a .gitignore
3. Haz referencia a los valores de configuración mediante los ajustes de compilación de Info.plist
4. Documenta los secretos necesarios en CLAUDE.md sin incluir los valores reales

## Configuration

API base URL and keys are in `Config.xcconfig` (not committed).
Required keys:
- `API_BASE_URL` — Backend server URL
- `API_KEY` — Authentication token

Create `Config.xcconfig` from `Config.xcconfig.template`.

El agente sabe que las claves existen y dónde se utilizan, pero nunca ve sus valores reales.

¿Y las animaciones de SwiftUI? ¿Pueden escribirlas los agentes?

Los agentes escriben código de animación correctamente desde el punto de vista sintáctico, pero no pueden verificar el resultado visual. Las animaciones sencillas (.animation(.spring()), .transition(.slide), withAnimation { }) producen resultados correctos. Las animaciones complejas, de varios pasos y con tiempos precisos requieren una iteración visual que los agentes no pueden realizar.

Eficaz: «Agrega una animación de resorte cuando el temporizador cambie de estado».

Ineficaz: «Haz que la animación del temporizador se sienta satisfactoria». (Es subjetivo y requiere ajustes visuales).

¿Cómo gestionan los agentes los patrones de manejo de errores?

Muy bien. Los agentes comprenden los patrones do/catch, Result y async throws de Swift:

Implement error handling for the HealthKit authorization flow:
1. Check HKHealthStore.isHealthDataAvailable() — show alert if not
2. Request authorization — handle denial gracefully
3. On write failure — retry once, then show error
4. All errors should be user-facing with localized descriptions

Los agentes generan un manejo estructurado de errores con mensajes adecuados para el usuario. En ocasiones gestionan errores en exceso (capturan excepciones que deberían propagarse), así que revisa los bloques catch.

¿Puedo usar agentes para implementar funciones de accesibilidad?

En parte. Los agentes agregan correctamente etiquetas, indicaciones y atributos de accesibilidad:

Add accessibility labels to all interactive elements in TimerView:
- Timer display: current time remaining
- Start/Pause button: current state and action
- Reset button: "Reset timer"
- Duration picker: selected duration

Lo que no pueden hacer es verificar que el orden de navegación de VoiceOver sea correcto, probar el escalado de Dynamic Type ni evaluar las relaciones de contraste de color. Usa Accessibility Inspector de Xcode para comprobarlo.

¿Cómo gestionan los agentes las migraciones de Core Data (si no se utiliza SwiftData)?

Los agentes escriben asignaciones de migración y versiones de modelos de Core Data, pero los pasos manuales en Xcode (crear nuevas versiones del modelo y seleccionar la versión actual) no pueden automatizarse. Si todavía usas Core Data en lugar de SwiftData, documenta el historial de versiones del modelo en CLAUDE.md:

## Core Data Model Versions
- V1: Initial (GroceryList, GroceryItem)
- V2: Added Category model (current)
- Migration: Lightweight automatic for V1→V2

¿Cómo gestionan los agentes las vistas previas de SwiftUI?

De dos maneras: 1. La herramienta RenderPreview de Xcode MCP de Apple renderiza vistas previas sin interfaz gráfica y devuelve el resultado. El agente puede verificar que una vista previa se compile y renderice sin errores, pero no puede evaluar si el resultado visual es correcto. 2. Verificación basada en la compilación mediante build_sim, que confirma que los proveedores de vistas previas se compilan. Si una vista previa falla durante la ejecución, la compilación aun así se completa correctamente; el fallo solo se manifiesta cuando Xcode intenta renderizarla.

Para verificar visualmente las vistas previas, todavía necesitas tener Xcode abierto.

¿Y visionOS y Apple Vision Pro?

Se aplican los mismos patrones. XcodeBuildMCP admite simuladores de visionOS y los patrones de arquitectura (@Observable, NavigationStack, SwiftData) son idénticos. El código específico de RealityKit (contenido 3D, espacios inmersivos y seguimiento de manos) presenta las mismas limitaciones que Metal: los agentes pueden escribir código correcto, pero no verificar el resultado espacial.

¿Qué tamaño puede tener un proyecto antes de que los agentes comiencen a tener dificultades?

El factor limitante es el tamaño de la ventana de contexto. Con la ventana de 1 millón de tokens de Opus 5, Claude Code puede mantener aproximadamente entre 50 y 70 archivos Swift de forma simultánea en la memoria de trabajo activa. En proyectos más grandes, el agente recurre a la búsqueda de archivos y a la lectura selectiva para trabajar con partes del código base. Los proyectos con más de 100 archivos funcionan bien: el agente simplemente lee los archivos cuando los necesita, en lugar de mantenerlo todo en contexto.

El límite práctico no es la cantidad de archivos, sino la coherencia del código base. Un proyecto bien documentado de 200 archivos con un CLAUDE.md detallado produce mejores resultados que uno de 30 archivos sin documentación.

¿Necesito saber Swift para usar agentes en el desarrollo de iOS?

Debes ser capaz de revisar el resultado del agente y tomar decisiones de arquitectura. No necesitas escribir cada línea por tu cuenta, pero sí comprender Swift lo suficiente como para detectar cuándo el agente toma decisiones incorrectas, especialmente en materia de concurrencia, gestión de memoria y patrones específicos de cada framework. Un agente multiplica por 10 tus habilidades actuales; no las reemplaza.

¿Cómo gestionan los agentes los conflictos de fusión en archivos Swift?

Los agentes resuelven de forma confiable los conflictos de fusión en archivos de código fuente Swift. Todos los entornos de ejecución de agentes comprenden bien los marcadores estándar de conflicto (<<<<<<<, =======, >>>>>>>). Sin embargo, los conflictos de fusión en archivos .pbxproj siguen requiriendo una resolución manual: no pidas a los agentes que resuelvan conflictos de .pbxproj.

¿Cuál es el costo de usar agentes para el desarrollo de iOS?

Con el plan Max de Anthropic (Opus 5, contexto de 1 millón de tokens), una sesión habitual de desarrollo de iOS dura entre 30 y 120 minutos y procesa entre 200.000 y 800.000 tokens. Las llamadas a herramientas de MCP agregan una sobrecarga mínima (las respuestas estructuradas de JSON consumen menos tokens que la salida de compilación sin procesar). El costo es comparable al de ejecutar Claude Code con cualquier otro código base: el desarrollo de iOS no es significativamente más ni menos costoso que el desarrollo web.

¿Puedo usar agentes con proyectos de UIKit?

Sí, pero los agentes son más eficaces con SwiftUI. UIKit requiere más código repetitivo, tiene una estructura menos declarativa y suele incluir archivos de Interface Builder que los agentes no pueden editar. Si tienes un proyecto de UIKit, considera usar agentes para la capa de modelos y la lógica de negocio mientras gestionas la interfaz de usuario manualmente, o migra las vistas gradualmente a SwiftUI.

¿Cómo gestionan los agentes la localización?

Los agentes crean y editan eficazmente archivos .xcstrings (catálogos de cadenas de Xcode). Pueden agregar nuevas claves de localización, proporcionar traducciones y mantener la coherencia entre idiomas. El formato estructurado de JSON de los archivos .xcstrings es fácil de procesar para los agentes. También trabajan bien con archivos .strings (el formato heredado), ya que su formato de clave-valor es sencillo.

Errores comunes de los agentes en iOS (y cómo prevenirlos)

Estos son los errores recurrentes que he observado en miles de interacciones con agentes en 8 proyectos de iOS. Cada uno tiene una estrategia de prevención.

Error 1: Mezclar patrones observables

Qué sucede: El agente usa @Observable en un archivo y ObservableObject en otro, o agrega @Observable a una clase @Model (que ya es observable).

Prevención: Reglas explícitas en CLAUDE.md:

- NEVER use ObservableObject — use @Observable
- NEVER add @Observable to @Model classes (already Observable)
- NEVER use @StateObject — use @State with @Observable
- NEVER use @ObservedObject — access @Observable properties directly

Error 2: Crear ciclos de retención en closures

Qué sucede: El agente crea closures que capturan self con una referencia fuerte, especialmente en Timer.publish, NotificationCenter y controladores de finalización.

Prevención: Incluye un patrón para closures en CLAUDE.md:

## Closure Pattern
- Timer callbacks: use `[weak self]` and guard
- NotificationCenter observers: store in `Set<AnyCancellable>` and use `[weak self]`
- Completion handlers: use `[weak self]` for any closure stored beyond the call site

Error 3: Ignorar los requisitos de @MainActor

Qué sucede: El agente crea clases @Observable sin aislamiento mediante @MainActor, lo que provoca advertencias de concurrencia de Swift 6.2 o cierres inesperados en tiempo de ejecución cuando la interfaz se actualiza fuera del hilo principal.

Prevención:

## Concurrency Rule
ALL @Observable classes MUST be @MainActor:
```swift
@Observable
@MainActor
final class SomeManager { }
```

Error 4: Usar NavigationLink con un closure de destino

Qué sucede: El agente usa el patrón obsoleto NavigationLink(destination:label:) en lugar del patrón con seguridad de tipos NavigationLink(value:) + .navigationDestination(for:).

Prevención:

## Navigation Pattern
ALWAYS use value-based navigation:
```swift
NavigationLink(value: item) { ItemRow(item: item) }
.navigationDestination(for: Item.self) { ItemDetailView(item: $0) }
```
NEVER use: `NavigationLink(destination: ItemDetailView(item: item)) { }`

Error 5: Codificar nombres de simuladores de forma fija

Qué sucede: El agente escribe comandos de compilación con nombres específicos de simuladores (“iPhone 16 Pro”) que podrían no existir en tu sistema.

Prevención: MCP se encarga de esto: list_sims detecta los simuladores disponibles. En CLAUDE.md:

## Simulators
Do NOT hardcode simulator names. Use `list_sims` MCP tool to discover
available devices, then `boot_sim` with the discovered device ID.

Error 6: Crear archivos en directorios incorrectos

Qué sucede: El agente crea un nuevo archivo de vista en la raíz del proyecto en lugar del subdirectorio Views/, o coloca un modelo en el grupo equivocado.

Prevención: Las anotaciones de la estructura de archivos en CLAUDE.md indican dónde ubicarlos. Además:

## File Placement Rules
- Views → `AppName/Views/`
- Models → `AppName/Models/`
- Managers → `AppName/Managers/`
- Extensions → `AppName/Extensions/`
- Tests → `AppNameTests/`

Error 7: No gestionar la disponibilidad por plataforma

Qué sucede: El agente usa HealthKit en código compartido que se compila para tvOS (donde HealthKit no está disponible), o usa ActivityKit en código para watchOS.

Prevención:

## Platform Guards
- HealthKit: `#if canImport(HealthKit)` (unavailable on tvOS)
- ActivityKit: `#if canImport(ActivityKit)` (iOS only)
- WatchKit: `#if os(watchOS)`
- UIKit haptics: `#if os(iOS)` (unavailable on tvOS, watchOS uses WKHaptic)

Error 8: Diseñar en exceso funciones sencillas

Qué sucede: El agente crea un protocolo, una extensión del protocolo, una implementación concreta, una fábrica y un contenedor de inyección de dependencias para lo que debería ser una función auxiliar de 20 líneas.

Prevención: Incluye un principio de simplicidad:

## Architecture Principle
Prefer the simplest solution that handles the requirements.
- Direct implementation over protocol abstraction (unless you have 2+ conforming types)
- Concrete types over generics (unless reuse is proven)
- Extensions on existing types over new wrapper types

La evaluación honesta

Después de publicar 8 aplicaciones de iOS con agentes de IA, este es el resumen:

Lo que los agentes transformaron: La velocidad de implementación. Lo que antes tomaba días ahora toma horas. Las vistas de SwiftUI, los modelos de SwiftData, las pruebas unitarias y la refactorización ahora son producidos principalmente por agentes y revisados por personas.

Lo que los agentes no transformaron: Las decisiones de arquitectura, el diseño visual, la optimización del rendimiento ni el proceso de publicación en App Store. Estas tareas siguen dependiendo de las personas.

El efecto multiplicador es real, pero tiene límites. Mi estimación subjetiva para el conjunto de 8 aplicaciones: una mejora de 3 a 5 veces en el tiempo necesario para implementar una función en proyectos bien documentados y con una configuración adecuada de MCP y hooks. Esta cifra no se comparó con un grupo de control; se basa en una comparación del tiempo real entre funciones desarrolladas con ayuda de agentes y trabajo individual equivalente dentro de las mismas bases de código. En proyectos sin documentación ni hooks, la mejora quizá sea de 1,5 a 2 veces: el agente dedica demasiado tiempo a adivinar en lugar de construir.³³

La inversión que da resultados: El tiempo dedicado a configurar CLAUDE.md, los hooks y MCP. Cada hora de preparación ahorra muchas horas corrigiendo errores de los agentes. La configuración es el producto; el agente es el motor de ejecución.

Lo que me sorprendió: Hasta qué punto los servidores MCP cambiaron la dinámica. Antes de MCP, los agentes eran editores de texto sofisticados que, casualmente, entendían Swift. Después de MCP, se convierten en colaboradores de desarrollo que escriben, compilan, prueban, depuran e iteran. El ciclo estructurado de retroalimentación marca la diferencia entre un agente que escribe código y uno que publica código.

Lo que le diría a mi yo del pasado: Empieza con la aplicación más pequeña (Reps, 14 archivos), configura correctamente MCP y los hooks, escribe un CLAUDE.md exhaustivo y, después, extiende los patrones a proyectos más grandes. No empieces con la aplicación multiplataforma de 63 archivos. La inversión en infraestructura es la misma sin importar el tamaño del proyecto: hazlo una vez en un proyecto pequeño y luego cópialo en todos los demás.

El futuro: La integración nativa de agentes en Xcode 26.3 es el comienzo, no el final. Que Apple incorpore compatibilidad con MCP significa que la cadena de herramientas avanza hacia un desarrollo centrado en agentes. Quienes inviertan desde ahora en estructuras de proyecto compatibles con agentes —archivos CLAUDE.md claros, arquitecturas comprobables y hooks automatizados— acumularán los beneficios de esa inversión a medida que mejoren las herramientas.

Tarjeta de referencia rápida

Instalación (configuración inicial)

# XcodeBuildMCP (82 tools)
claude mcp add XcodeBuildMCP -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Apple Xcode MCP (20 tools)
claude mcp add --transport stdio xcode -s user -- xcrun mcpbridge

# Codex MCP setup
codex mcp add xcode -- xcrun mcpbridge

# Verify
claude mcp list

Secciones esenciales de CLAUDE.md

1. Project identity (bundle ID, target OS, architecture)
2. File structure with annotations
3. Build and test commands
4. Key patterns and rules
5. Prohibitions (NEVER touch .pbxproj)
6. Framework-specific context

Hooks esenciales

{
  "PreToolUse": [{ "matcher": "Edit|Write", "command": "block .pbxproj" }],
  "PostToolUse": [{ "matcher": "Edit|Write", "command": "swiftformat" }]
}

Reglas de arquitectura

@Observable         (not ObservableObject)
NavigationStack     (not NavigationView)
@State              (not @StateObject)
SwiftData @Model    (not Core Data)
async/await         (not completion handlers)
@MainActor          (on all Observable classes)
.glassEffect()      (Liquid Glass, iOS 26+)

Prioridades de las herramientas de MCP

Build:     build_sim          (not xcodebuild via Bash)
Test:      test_sim           (not xcodebuild test via Bash)
Sim:       list_sims/boot_sim (not xcrun simctl via Bash)
Docs:      DocumentationSearch (not WebSearch)
REPL:      ExecuteSnippet     (not swift via Bash)

Registro de cambios

Referencias