Cómo crear apps para iOS con agentes de IA: guía práctica

TL;DR: Tres entornos de ejecución de agentes ya generan código para iOS: Claude Code CLI con MCP, Codex CLI con MCP y los agentes nativos de Intelligence en Xcode — Claude Agent, Codex y, desde Xcode 26.6, Google Gemini o cualquier agente compatible con Agent Client Protocol (ACP).¹⁷ Dos servidores MCP (XcodeBuildMCP con 82 herramientas y xcrun mcpbridge de Apple con 20) ofrecen a los agentes acceso estructurado a compilaciones, pruebas, simuladores y depuración. Esta guía presenta patrones reales de CLAUDE.md, configuraciones de hooks y evaluaciones sinceras de lo que funciona y lo que falla, basadas en 8 aplicaciones de iOS en producción que suman 293 archivos Swift.³⁰ Los agentes sobresalen al crear vistas SwiftUI y modelos SwiftData, refactorizar y diagnosticar errores de compilación. Fallan al modificar .pbxproj, firmar código y depurar aspectos visuales. La brecha entre «el agente escribe Swift» y «el agente publica una aplicación de iOS» se cierra mediante la configuración, no con mejores indicaciones. Desde la WWDC 2026 (8 de junio), iOS 27 está en beta — beta 4 al 20 de julio — e incorpora frameworks relevantes para los agentes (control de llamadas a herramientas en Foundation Models, ejecución en segundo plano con App Intents y los nuevos frameworks Core AI y Evaluations) que conviene mencionar en el contexto de tu agente, ya que un modelo entrenado antes de junio de 2026 no los conocerá. Xcode 26.6 (25 de junio de 2026, Swift 6.3) es el conjunto de herramientas estable actual; la beta de Xcode 27 (Swift 6.4, SDKs de iOS 27) sigue el ciclo de iOS 27.¹⁷¹⁸

He creado 8 aplicaciones de iOS con agentes de programación de IA. No son prototipos, sino aplicaciones publicadas en la App Store, con integraciones de HealthKit, shaders de Metal, física de SpriteKit, sincronización con iCloud, Live Activities, tablas de clasificación de Game Center y destinos multiplataforma que abarcan iOS, watchOS y tvOS. Cada línea de Swift de estas aplicaciones fue escrita por un agente y revisada por mí, o escrita por mí y refactorizada por un agente. Según mis cálculos, los agentes se encargaron de la mayor parte de la escritura del código línea por línea; yo me ocupé de la revisión, el alcance y las tareas que requieren criterio humano (acabado visual, firma, optimización del rendimiento y envío a la App Store).

Esta guía es la referencia que me habría gustado tener cuando empecé. Abarca todo el conjunto de herramientas: qué entorno de ejecución de agentes usar, cómo configurar servidores MCP para ofrecer acceso estructurado a las compilaciones, qué incluir en tu CLAUDE.md, qué hooks evitan que el agente destruya tu proyecto de Xcode y, sobre todo, en qué puntos fallan los agentes y necesitas tomar el control.

Conclusiones clave

Para desarrolladores de iOS que comienzan a usar agentes de IA:

• Empieza con Claude Code CLI + XcodeBuildMCP. Es el entorno de ejecución más maduro y el que ofrece la cobertura más amplia de herramientas MCP. Instala dos comandos, agrega un CLAUDE.md a tu proyecto y el agente podrá compilar, probar y depurar sin que tengas que copiar los mensajes de error.
• Nunca permitas que un agente modifique .pbxproj. Esta es la regla más importante. Un hook PreToolUse que bloquee las 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 le dediques se amortizarán en cada sesión de un agente que trabaje con 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 si compilaba. Con XcodeBuildMCP, el agente escribe código, lo compila, lee errores estructurados, los corrige y ejecuta pruebas de forma autónoma.
• Tres entornos de ejecución atienden necesidades distintas. Claude Code CLI para sesiones agénticas profundas, Codex CLI para trabajos por lotes sin interfaz y los agentes nativos de Xcode 26.3 para correcciones rápidas en línea sin salir del IDE.
• La infraestructura de hooks se reutiliza. Tus formateadores PostToolUse, bloqueadores PreToolUse y hooks para ejecutar pruebas funcionan de la misma forma en proyectos de iOS, con pequeños ajustes en las rutas.

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

• La eficacia de los agentes aumenta con la documentación del proyecto, no con su tamaño. Una aplicación de 63 archivos con un CLAUDE.md detallado produce mejores resultados que una de 14 archivos sin documentación.
• El límite de .pbxproj no es negociable. Los agentes no pueden editar de manera confiable los archivos de proyecto de Xcode. Tu flujo de trabajo debe contemplar que los archivos se agreguen manualmente a los destinos de Xcode.
• ROI sincero: los agentes se encargan de la mayor parte de la implementación en proyectos bien documentados, como demuestra la aplicación para TV de 15 archivos publicada tras 3 horas de trabajo asistido por agentes (caso práctico más adelante). El trabajo restante — acabado visual, firma, optimización del 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 por la sección que corresponda a tu nivel de experiencia:

Tabla de contenido

1. El portafolio: 8 aplicaciones, 293 archivos
2. Requisitos previos
3. Tres entornos de ejecución 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. Lo que los agentes hacen bien en iOS
8. Lo que los agentes hacen mal en iOS
9. Hooks para el 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 prácticos reales
15. Ciclo de vida de un proyecto con agentes
16. Configuración de definiciones de agentes
17. Patrones de pruebas para iOS asistido por agentes
18. Administración de la ventana de contexto en proyectos de iOS
19. Solución de problemas
20. Errores comunes de los agentes en iOS
21. La evaluación sincera
22. Preguntas frecuentes
23. Tarjeta de referencia rápida
24. Referencias

Recursos relacionados

Serie sobre el ecosistema de Apple. 21 artículos sobre aplicaciones SwiftUI en producción que se integran con Apple Intelligence, MCP, Foundation Models, Vision, Core ML y el conjunto de frameworks de iOS 26. Basados en Water, Get Bananas, Return y el resto del portafolio 941:

Página principal de la serie: Serie sobre el ecosistema de Apple

Apple agéntico (E4):

Frameworks (E2/E3):

Código publicado (E1):

Síntesis (E5):

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

WWDC 2026 (8 de junio de 2026) llevó iOS 27 a la fase beta. El flujo de desarrollo con agentes que presenta esta guía no cambia: sigues dirigiendo Claude Code, Codex o los agentes de Intelligence de Xcode mediante MCP, sigues escribiendo un CLAUDE.md y sigues protegiendo las operaciones destructivas con hooks. Lo que cambia es el conjunto de tecnologías con las que trabaja tu agente. iOS 27 incorpora varios frameworks nuevos relevantes para los agentes, y lo más práctico es indicárselos explícitamente a tu agente de programación, porque un modelo entrenado antes de junio de 2026 no sabrá que existen. iOS 26 sigue siendo la versión disponible para producción; considera los elementos siguientes como los objetivos que debes adoptar cuando desarrolles con los SDK de la beta de iOS 27.

Estas son las novedades de iOS 27 relevantes para los agentes, cada una con una referencia detallada:

• Foundation Models incorporó control sobre las llamadas a herramientas. GenerationOptions.ToolCallingMode te permite ajustar en cada solicitud con qué intensidad el modelo integrado en el dispositivo llama a herramientas, y el framework puede cambiar de modo después de la primera llamada para limitar la actividad de las herramientas durante una solicitud. El framework Vision ahora incluye OCRTool y BarcodeReaderTool listos para usar, que puedes conectar 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 exige informar el progreso) amplía el tiempo de ejecución en segundo plano de un intent para tareas de sincronización, operaciones con archivos e inferencia en el dispositivo; SyncableEntity proporciona a una AppEntity una identidad compartida entre dispositivos; IndexedEntityQuery permite que el sistema solicite a tu consulta que repare 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 sitúa por debajo de Foundation Models para los casos en los que incorporas tu propio modelo en lugar de utilizar el modelo del sistema de Apple. Consulta Core AI: ejecución de modelos en Apple Silicon.¹⁴
• Evaluations es el XCTest para evaluar la calidad de los modelos. Es un nuevo framework (macOS 27) que permite medir la calidad de los resultados de un modelo como parte de tu conjunto de pruebas, la pieza que faltaba para lanzar funciones de IA que un agente te ayudó a desarrollar. Consulta Evaluations: XCTest para evaluar la calidad de los modelos.¹⁵
• SwiftData, HealthKit y SwiftUI también evolucionaron. SwiftData incorpora observación e historial en iOS 27; HealthKit añade zonas de entrenamiento y nuevos tipos; y SwiftUI recibe en iOS 27 su habitual abanico amplio de novedades. 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 publicó en versión beta el primer día de WWDC (8 de junio, compilación 27A5194q) y, al 20 de julio, se encuentra en la beta 4 (27A5228h). Incluye Swift 6.4 y los SDK de iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27, y requiere macOS Tahoe 26.4 o posterior.¹⁸ Hay 4 elementos de las notas de la versión que afectan a los flujos de trabajo con agentes: Coding Intelligence incorpora un modo de planificación; las notas lo mencionan mediante un problema conocido relacionado con la barra de confirmación «¿Implementar el plan?» (178673449), por lo que debes esperar a que el agente termine de transmitir su respuesta antes de confirmar o descartar un plan; la herramienta RenderPreview de MCP ahora renderiza grupos de Preview (174692209) y puede previsualizar tu interfaz en otra configuración regional (181040291); la herramienta «Prepare Project for Localization», dirigida a agentes, ahora informa qué claves de String Catalog se eliminaron 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 una versión anterior; usa Xcode 26.5 o posterior para las ejecuciones con ASan (178072780).¹⁸ Las herramientas de MCP también se han puesto al día con la beta: XcodeBuildMCP v2.7.0 (2026-07-23) consiguió que sus herramientas de automatización de interfaces 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 interfaces en tiempo de ejecución solo era confiable con los simuladores de Xcode 26, lo que obligaba a verificar manualmente las interfaces dirigidas por agentes en la beta de iOS 27.²¹

La lección para quien opera el agente es la misma que plantea el resto de esta guía: el agente escribe el código, pero tú le proporcionas el conocimiento que le falta. En las versiones beta de iOS 27, eso significa mencionar estos frameworks en tu prompt o CLAUDE.md y proporcionar al agente enlaces a la documentación de Apple, porque, de lo contrario, recurrirá a la estructura que tenía cada API en iOS 26. Todo lo demás que se explica en esta guía (entornos de ejecución, MCP, hooks y modos de fallo) se mantiene sin cambios al trabajar con iOS 27.

El portafolio: 8 apps, 293 archivos

Antes de profundizar en la configuración, veamos en qué se basa esta guía. No se trata de proyectos de juguete: abarcan 5 frameworks de Apple, 3 plataformas y todo el espectro de complejidad de iOS, desde un registro de entrenamientos de 14 archivos hasta un temporizador de meditación multiplataforma de 63 archivos.

Por qué importa la cantidad de archivos: La eficacia de un agente está relacionada con la claridad del proyecto, no con su tamaño. Return (63 archivos) obtiene mejores resultados del agente que amp97 (41 archivos) porque Return cuenta con un CLAUDE.md detallado que incluye anotaciones de archivos, diagramas de arquitectura y patrones explícitos. Los shaders de Metal de amp97 son intrínsecamente más difíciles de interpretar para los agentes, independientemente de la calidad de la documentación.

Requisitos previos

Antes de configurar cualquier entorno de ejecución de agentes para desarrollar en iOS:

Fecha límite de App Store Connect: A partir del 2026-04-28, las apps que se suban a App Store Connect deben compilarse con Xcode 26 o posterior y utilizar los SDK de iOS 26, iPadOS 26, tvOS 26, visionOS 26 o watchOS 26.²⁴ (Los envíos para macOS no están sujetos a este requisito). Si tu equipo todavía utiliza Xcode 16.x, la cadena de herramientas asistida por agentes de esta guía también sirve como incentivo para actualizar: ninguno de los servidores MCP que aparecen a continuación funciona sin Xcode 26.3 o posterior.

Obligatorio: - macOS 15 o posterior (Sequoia) o macOS Tahoe (Xcode 26.6 requiere macOS Tahoe 26.2 o posterior; la beta de Xcode 27 requiere Tahoe 26.4 o posterior) - Xcode 26.3 o posterior instalado y configurado (el mínimo para xcrun mcpbridge); se recomienda Xcode 26.6 o posterior. Xcode 26.6 (2026-06-25, compilación 17F113) es la versión estable más reciente e incorpora 3 cambios de Coding Intelligence relevantes para los agentes: Google Gemini como proveedor de asistencia para programación, compatibilidad con Agent Client Protocol (ACP) y renderizado de variantes —modo claro/oscuro, orientación y tamaños tipográficos— en la herramienta de previsualización MCP. También corrige 2 cierres inesperados durante los turnos del agente y el bloqueo que ocurría cuando un agente hacía una pregunta, e incluye Swift 6.3 con los SDK de la generación de iOS 26.5.¹⁷ Las mejoras del flujo de trabajo de la versión 26.5 —cola de mensajes en el asistente de programación y compatibilidad con preguntas aclaratorias—, así como los archivos adjuntos de imágenes de Swift Testing, la gravedad de los problemas registrados, las advertencias de fallos en pruebas de interfaz con registros de fallos y las mejoras del editor de String Catalog de la versión 26.4, se mantienen en esta versión.²⁵²⁶ Versiones estables anteriores: 26.5 (2026-05-11, compilación 17F42) y 26.4.1 (2026-04-16, compilación 17E202).²⁷ - Al menos un entorno de ejecución de iOS Simulator instalado - Una cuenta de API de Anthropic (para Claude Code) o una cuenta de OpenAI (para Codex)

Recomendado: - SwiftFormat instalado (brew install swiftformat) — se utiliza en hooks que aplican formato al guardar - SwiftLint instalado (brew install swiftlint) — es opcional, pero resulta útil para aplicar reglas de estilo - Familiaridad con la terminal — los 3 entornos de ejecución 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 la App Store o developer.apple.com. Nota: xcode-select --install solo instala Command Line Tools, que no incluye 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, patrones de integración con MCP y casos de uso ideales diferentes.

1. Claude Code CLI

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

Integración con MCP: Compatibilidad total tanto con XcodeBuildMCP como con el MCP de Xcode de Apple. El agente descubre herramientas mediante el protocolo MCP y las invoca con parámetros estructurados. En total, hay 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 conexión manual de MCP, XcodeBuildMCP v2.1.0+ incluye un subcomando init que detecta automáticamente Claude Code, Cursor o Codex e instala las habilidades 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 la instalación). Omite esta opción si quieres controlar explícitamente qué servidores MCP se conectan y con qué alcance; las invocaciones manuales de claude mcp add anteriores te brindan ese control.²⁸

Ideal para: Sesiones de implementación profunda: desarrollar funciones nuevas, refactorizar varios archivos, depurar problemas complejos y ejecutar ciclos autónomos de compilación, prueba y corrección. La ventana de contexto de 1M de Claude Code (con Opus 5) permite que el agente mantenga en la memoria de trabajo la mayoría de los proyectos de iOS pequeños y medianos; según mi experiencia, hasta unos 50 archivos, dependiendo de su tamaño.²³

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 es que el agente nunca te pide que compiles manualmente ni que pegues la salida de los errores. El ciclo de compilación, detección de errores y corrección es autónomo.

2. Codex CLI

Qué es: El agente de programación basado en la terminal de OpenAI. Su concepto es similar al de Claude Code, pero utiliza modelos de OpenAI (GPT-4o, o3) y tiene un modelo de permisos diferente.

Integración con 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 gráfica, integración con CI/CD y tareas en las que quieres 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 ejecutar conjuntos de pruebas que modifican el estado.

Diferencias clave frente a Claude Code: - Utiliza modelos de OpenAI en lugar de modelos de Claude - Diferentes tamaños de ventana de contexto y costos por tokens - Modelo de permisos centrado en el sandbox (más restrictivo de forma predeterminada) - Ecosistema de MCP más pequeño (se han probado menos servidores de la comunidad) - Sistema de hooks disponible (v0.119.0+), pero menos maduro que el de Claude Code: tiene menos tipos de eventos y carece del campo condicional if

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

Usa Codex cuando quieras diversidad de modelos: hacer que un segundo agente revise el código escrito por el primero permite detectar clases de errores diferentes. El flujo de trabajo colaborativo (Claude desarrolla, Codex revisa) resulta eficaz para iOS porque los patrones de SwiftUI que parecen correctos para una familia de modelos pueden contener 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 26.3

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 ya está disponible en el asistente de programación (171990272), y Xcode incorpora compatibilidad con Agent Client Protocol (ACP) (178294840). Por lo tanto, lo que comenzó como una integración con dos proveedores ahora incluye tres proveedores y un protocolo abierto que permite conectar cualquier agente compatible con ACP al panel Intelligence.¹⁷

Configuración:

1. Abre Xcode 26.3+
2. Ve a Settings > Intelligence
3. Agrega un proveedor nuevo:
4. Para Claude: Selecciona “Claude Agent” e ingresa tu clave API de Anthropic
5. Para Codex: Selecciona “Codex” e ingresa tu clave API de OpenAI
6. Para Gemini: Selecciona “Google Gemini” (Xcode 26.6+)
7. Para cualquier otro: conecta un agente compatible con ACP (Xcode 26.6+)
8. El agente aparecerá en la barra lateral Intelligence y podrás invocarlo en línea

Ideal para: Ediciones rápidas en línea, completado de código con razonamiento propio de un agente y desarrolladores que prefieren no salir de Xcode. Gracias a la integración nativa, el agente tiene acceso directo al contexto del proyecto en Xcode —archivos abiertos, objetivos de compilación y configuración del esquema— sin intermediación de MCP.

Limitaciones frente a los agentes CLI: - No tiene un sistema de hooks: no puedes exigir el formateo al guardar ni bloquear las escrituras en .pbxproj - No carga CLAUDE.md: el agente no lee los archivos de configuración de tu proyecto - Autonomía limitada: el agente trabaja en el archivo o la selección actual, no en todo el proyecto - No permite delegar en subagentes: las tareas complejas de varios pasos no se pueden ejecutar en paralelo - No permite configurar servidores MCP: el agente utiliza únicamente las herramientas integradas de Xcode

Cuándo usar los agentes nativos de Xcode:

Para ediciones rápidas y acotadas en las que cambiar a la terminal supone un esfuerzo innecesario. “Agrega una propiedad calculada a este modelo”. “Escribe una prueba unitaria para esta función”. “Refactoriza esta vista para usar @Observable”. Es decir, tareas que afectan uno o dos archivos y no requieren un ciclo de compilación y pruebas.

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

Matriz comparativa de entornos de ejecución

La recomendación: Usa Claude Code CLI como 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 que «escribe Swift y espera que tú compiles» en uno que «escribe Swift, compila, lee errores estructurados y los corrige».² Esta sección profundiza más que la publicación del blog¹¹: abarca ambos servidores, todos los métodos de instalación, la verificación y la configuración del agente que garantiza que las herramientas realmente se utilicen.

XcodeBuildMCP: 82 herramientas para el desarrollo de iOS sin interfaz gráfica

XcodeBuildMCP encapsula xcodebuild, xcrun simctl y LLDB en 82 herramientas estructuradas de MCP (inventario anunciado, verificado sin cambios desde la versión 2.6.2 hasta la 2.7.0), agrupadas en 12 categorías de flujo de trabajo.³¹⁹²¹ La ubicación canónica del proyecto es la organización getsentry de GitHub: Sentry se encarga de su mantenimiento y la URL original cameroncooke/XcodeBuildMCP ahora redirige allí, algo importante cuando publicaciones anteriores citan la dirección antigua.²¹ Funciona sin que Xcode esté abierto: el ciclo completo de compilación, pruebas y depuración se ejecuta sin interfaz gráfica mediante las herramientas de línea de comandos de Apple. Conviene conocer dos detalles sobre el inventario: una sesión stdio predeterminada expone las dos docenas de herramientas del flujo de trabajo del simulador y mantiene el resto fuera del contexto del agente —configura XCODEBUILDMCP_ENABLED_WORKFLOWS (nombres de categorías separados por comas tomados de la tabla siguiente) para cargar más—; además, el mismo motor se distribuye como una CLI (xcodebuildmcp tools informa de 100 comandos, 72 canónicos) si quieres realizar 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 instalarlo únicamente en el proyecto actual (útil si solo quieres MCP en proyectos de iOS y 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 las rutas de archivos. Desactívala, a menos que quieras aportar diagnósticos al proyecto.¹

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

Las herramientas más importantes para el trabajo cotidiano:

1. build_sim — La invocarás cientos de veces. Devuelve JSON con errores clasificados por archivo, línea y gravedad. El agente lee el error, navega hasta el archivo y lo corrige sin que tengas que intervenir.

2. test_sim — Devuelve resultados de cada 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 — Permiten administrar simuladores sin memorizar las opciones de xcrun simctl. El agente descubre los entornos de ejecución disponibles y elige un dispositivo adecuado.

4. discover_projs + list_schemes — Permiten inspeccionar el proyecto. El agente no necesita adivinar el nombre del esquema ni la estructura del espacio de trabajo.

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

Qué cambió en la versión 2.6.0 (2026-06-01): automatización de la interfaz de usuario en tiempo de ejecución:

La versión 2.6.0 reconstruyó la automatización de la interfaz de usuario en torno a un contexto reutilizable, en lugar de capturas de pantalla aisladas.¹⁹ Ahora, snapshot_ui devuelve referencias estables a elementos y un hash de la pantalla, además de aceptar sinceScreenHash para que el agente pueda omitir una captura completa cuando la pantalla no haya cambiado. Tres herramientas nuevas completan el ciclo: wait_for_ui consulta periódicamente hasta que se cumple un predicado (existencia, estado habilitado, foco, texto visible o diseño estabilizado), en lugar de que el agente tenga que adivinar mediante pausas; batch ejecuta una secuencia de acciones basadas en referencias a elementos en una sola llamada; y drag realiza gestos de arrastre mediante referencias a elementos para interactuar con hojas y desplazarse por listas. type_text incorporó replaceExisting para reemplazar el valor de un campo en lugar de agregar texto al existente, los controles candidatos se clasifican a partir de datos de accesibilidad y los resultados estructurados ahora incluyen sugerencias en nextSteps (los esquemas de resultados pasaron a la versión 2 en esta entrega; desde entonces, la versión 2.7.0 trasladó los resultados de compilación y pruebas a schemaVersion: 3; consulta la sección siguiente). Configura XCODEBUILDMCP_HEADLESS_LAUNCH=true para iniciar apps en segundo plano sin quitarle el foco a macOS: es la diferencia entre una sesión de agente que puedes dejar ejecutándose y otra que sigue trayendo la ventana del Simulator al frente. En una tarea determinista con una app meteorológica, el propio benchmark del proyecto afirma lograr aproximadamente un 70 % menos de tiempo real transcurrido, un 68 % menos de tokens y un 76 % menos de llamadas a herramientas frente al flujo anterior a la versión 2.6. Son cifras del proyecto, no una medición independiente, pero el mecanismo —omitir capturas que no cambiaron y agrupar acciones realizadas en la misma pantalla— es precisamente donde se origina el consumo de tokens de la automatización de interfaces.¹⁹

Qué cambió en la versión 2.7.0 (2026-07-23): simuladores de Xcode 27, esquema v3 y compilaciones que respetan el esquema:

La versión 2.7.0 es más pequeña que la 2.6.0, pero incluye un cambio incompatible y otro de comportamiento que conviene conocer antes de actualizar.²¹ Lo más destacado: las herramientas de automatización de interfaces ahora funcionan plenamente con los simuladores de Xcode 27 mediante Device Hub, incluida la apertura de ventanas del simulador y los controles del teclado. Esto elimina la limitación por la que la automatización de interfaces en tiempo de ejecución solo era confiable con simuladores de Xcode 26. Cambio incompatible: las herramientas de compilación y pruebas ahora devuelven resultados estructurados con schemaVersion: 3 (utilizaban v2 desde la versión 2.6.0); cualquier código que hayas escrito para validar o analizar resultados y que esté fijado a la versión 2 debe actualizarse. Cambio de comportamiento: cuando se omite configuration, las herramientas de compilación, pruebas, limpieza y obtención de rutas de apps ahora respetan la configuración de la acción del esquema, en lugar de usar siempre Debug de forma predeterminada. Si la acción Test de un esquema está configurada como Release, un test_sim sin parámetros adicionales ahora compila en Release; por ello, pasa configuration explícitamente cuando tu flujo de trabajo dependa de una configuración específica. Otros cambios menores pero útiles: los paquetes reutilizables de preparación de pruebas .xctestproducts permiten volver a ejecutar pruebas sin recompilar, a la vez que generan un .xcresult nuevo en cada ejecución; extraArgs en los valores predeterminados de la sesión permite establecer opciones comunes de xcodebuild una sola vez por sesión, en lugar de repetirlas en cada llamada; un nuevo comando de CLI xcodebuildmcp purge informa sobre el almacenamiento del espacio de trabajo de XcodeBuildMCP y permite limpiarlo (de forma predeterminada solo simula la operación; para borrar se requiere una autorización explícita); y se corrigió un problema que obligaba a los clientes de MCP a esperar entre 10 y 17 segundos para que las herramientas estuvieran disponibles, lo que podía hacer que las comprobaciones de estado breves informaran de una conexión fallida.²¹

MCP de Apple Xcode: 20 herramientas que se integran con Xcode

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

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 o posterior y un proceso de Xcode en ejecución. Si Xcode no está abierto, todas las llamadas de MCP a través de este servidor fallarán o quedarán bloqueadas. XcodeBuildMCP no tiene esta limitación.

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

Herramientas exclusivas de MCP de Apple (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 confiable que una búsqueda web para preguntas sobre API de Apple. Pregunta «¿es válido HKQuantityType(.dietaryWater)?» y obtendrás una respuesta definitiva directamente de la fuente.

2. ExecuteSnippet — Ejecuta código en el REPL de Swift dentro del contexto del proyecto. El agente puede verificar el comportamiento de API, probar conversiones de tipos y validar expresiones sin compilar la app completa.

3. RenderPreview — Renderiza previsualizaciones de SwiftUI sin interfaz gráfica. El agente puede comprobar si una vista se renderiza sin errores, aunque no puede evaluar si el resultado visual es correcto (el renderizado se devuelve como datos, no se inspecciona visualmente). Desde Xcode 26.6, la herramienta de previsualización de MCP —denominada «Preview Snapshot» en las notas de la versión 26.6— renderiza variantes: apariencia clara/oscura, orientación vertical/horizontal y valores alternativos del tamaño tipográfico (178831772). Esto permite que un agente verifique una vista en distintas apariencias en una sola pasada.¹⁷ La versión beta de Xcode 27 amplía aún más esta función: permite renderizar grupos Preview y previsualizar en otra localización.¹⁸

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 la compilación y las pruebas, pero difieren de manera fundamental:

┌─────────────────────────────────────────────────────────────────┐
│                     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 abrir Xcode, consume menos memoria del sistema y ofrece una administración más completa de simuladores y dispositivos. Esta es tu herramienta principal de compilación.

Usa MCP de Apple Xcode para: Consultar documentación, verificar código con el REPL de Swift, renderizar previsualizaciones de SwiftUI y obtener diagnósticos en tiempo real. Mantén Xcode abierto durante las sesiones que requieran estas capacidades.

En la práctica: Uso XcodeBuildMCP para aproximadamente el 90 % de las llamadas de MCP, y MCP de Apple Xcode para consultar documentación y verificar código con el REPL. De forma predeterminada, el agente utiliza XcodeBuildMCP para compilar y ejecutar pruebas porque es más rápido (no conlleva la sobrecarga de un proceso de Xcode) y más confiable (no depende de XPC).

La distinción entre dos servidores se está volviendo menos rígida. XcodeBuildMCP 2.6.x incorpora una categoría de proxy xcode-ide: xcode_ide_list_tools descubre las capacidades de MCP exclusivas del IDE de Xcode y xcode_ide_call_tool las invoca (aparecen con nombres xcode_tools_*, por ejemplo, xcode_tools_documentationsearch). Así, un único registro de XcodeBuildMCP ahora también puede acceder a las herramientas del IDE de Apple.¹⁹ La restricción importante no cambia: esas llamadas mediante proxy aún requieren un proceso de Xcode en ejecución, exactamente igual que un registro directo de xcrun mcpbridge. Mantén registrados ambos servidores si quieres que las herramientas de Apple aparezcan como herramientas de primera clase en la lista del agente; el proxy resulta especialmente útil cuando quieres una sola entrada de servidor y únicamente realizas consultas ocasionales al 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 se conecta: Asegúrate de que Node.js esté instalado (node --version). El comando npx requiere Node.js 18 o posterior.
2. MCP de Apple Xcode no se conecta: Asegúrate de que Xcode 26.3 o posterior 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 (claude en una terminal nueva). Es posible que los servidores de MCP registrados durante una sesión no aparezcan hasta que reinicies.

Enseñarle al agente a usar MCP

Instalar servidores de MCP es necesario, pero no suficiente. Sin instrucciones explícitas, el agente puede volver a ejecutar xcodebuild mediante Bash (salida sin estructura y desperdicio de tokens de contexto) o recurrir a una búsqueda web para consultar la documentación de Apple (más lenta y menos confiable).

Agrega lo siguiente a tu CLAUDE.md o a la 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.

Estas instrucciones garantizan que el agente recurra primero a las herramientas de MCP. Sin ellas, verás que el agente construye comandos xcodebuild extensos mediante Bash, consume miles de tokens de contexto al analizar la salida y, en ocasiones, identifica erróneamente el error real.⁶

Hay un cambio de comportamiento de XcodeBuildMCP v2.7.0 que debes incorporar al modelo mental de esta sección: cuando se omite configuration, las herramientas de compilación, pruebas, limpieza y obtención de rutas de apps ahora respetan la configuración de la acción del esquema, en lugar de usar siempre Debug.²¹ La mayoría de los esquemas se ejecutan y se prueban en Debug, así que la mayoría de los proyectos no notarán ningún cambio. Sin embargo, si la acción de un esquema está configurada como Release —algo habitual en esquemas de elaboración de perfiles o configuraciones relacionadas con el archivado—, un build_sim o test_sim sin parámetros adicionales ahora compila en Release. Si tu CLAUDE.md o tus hooks presuponen artefactos de Debug, indícalo explícitamente en la llamada a la herramienta o configúralo una vez por sesión mediante session_set_defaults.

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

Dos versiones de Claude Code cambiaron la forma en que se comporta una compilación larga dentro de una sesión. Desde la versión 2.1.212 (2026-07-16), cualquier llamada a una herramienta de MCP que tarde más de 2 minutos pasa automáticamente a segundo plano para que la sesión siga disponible; el umbral se puede configurar —o el comportamiento se puede desactivar— mediante CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS.²⁰ Las compilaciones limpias y las ejecuciones completas de pruebas mediante build_sim / test_sim suelen superar los 2 minutos en proyectos reales, así que puedes esperar que el agente siga trabajando —leyendo archivos y planificando la siguiente edición— mientras la compilación termina en segundo plano, en vez de bloquear el turno. La corrección complementaria es igual de importante: antes de la versión 2.1.206 (2026-07-09), el valor request_timeout_ms específico de cada servidor, configurado mediante --mcp-config o .mcp.json, se ignoraba en sesiones nuevas. Como resultado, las llamadas largas de MCP agotaban el tiempo de espera predeterminado de 60 segundos; el síntoma clásico era que la primera compilación limpia agotaba el tiempo de espera y se «corregía sola» al reintentarlo.²⁰ Si solucionaste alguno de estos comportamientos mediante scripts envolventes o compilaciones precalentadas, ya puedes eliminar esa solución provisional.

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 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 quedan aislados. Siempre revisa en qué directorio está 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() cuando uses frameworks específicos de una plataforma. No asumas 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

Ciclos autónomos de compilación, prueba y corrección

El patrón más potente: dale al agente una especificación de función y deja que itere de forma autónoma mediante ciclos de compilación, prueba 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 errores estructurados, los corrige y repite el proceso. Una función que requeriría 5-10 ciclos humanos de compilación-error-corrección se completa en un solo ciclo 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 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 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, entiende la estructura y crea una implementación consistente en el proyecto de destino.

Revisión con dos agentes (Claude + Codex)

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

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

# 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 distintas clases de errores. Esto es especialmente valioso para shaders de Metal y patrones de concurrencia, donde es fácil introducir bugs sutiles.

Qué detecta la revisión doble que una revisión única suele pasar por alto:

La revisión doble no se trata de encontrar más bugs, sino de encontrar bugs diferentes. Cada familia de modelos tiene distintos modos de falla 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 cautela. El flag --dangerously-skip-permissions es necesario para el modo no interactivo, pero omite todas las verificaciones de seguridad. Asegúrate de tener tus hooks PreToolUse 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 resumen offline, clasificación o generación de salida estructurada), los agentes necesitan conocer el presupuesto del prompt. iOS 26.4 agregó dos APIs a SystemLanguageModel que reemplazaron la conjetura previa de 4096 tokens: contextSize (tokens máximos 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 del sistema operativo 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 toca SystemLanguageModel. Sin él, los agentes vuelven al antiguo valor fijo de 4096 y truncan prompts silenciosamente en dispositivos que vienen 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