Los agentes de programación pueden escribir Swift, modificar proyectos completos y, con Xcode 27, utilizar herramientas, skills y servidores Model Context Protocol (MCP). Pero existe un problema bastante más básico: buena parte de la documentación de Apple en developer.apple.com se presenta mediante JavaScript y una petición automatizada puede encontrarse inicialmente con una página sin el contenido que ve un navegador. Hay una solución sorprendentemente sencilla: Apple ofrece versiones Markdown de numerosas páginas de documentación que pueden obtenerse añadiendo .md a la URL.
Las claves de la documentación de Apple para agentes en 20 segundos
- Muchas páginas de Apple Developer dependen de JavaScript para presentar su contenido en la web.
- Las páginas de
/documentationpueden consultarse en Markdown añadiendo.mda su dirección. - Guías de diseño y tutoriales utilizan rutas diferentes y algunos contenidos están disponibles como JSON.
- El formato resulta mucho más sencillo de consumir para agentes y herramientas automáticas.
- Xcode 27 amplía precisamente el uso de agentes capaces de modificar, ejecutar y validar proyectos.
El detalle ha sido difundido por Tim Sneath, que atribuye a Luca Bernardi la inspiración del método. Su utilidad resulta especialmente evidente ahora que programar con inteligencia artificial está pasando del autocompletado a agentes capaces de trabajar durante periodos prolongados sobre un proyecto.
La diferencia no es menor. Si se pide a un modelo que utilice la documentación más reciente de SwiftUI, existe una diferencia fundamental entre consultar realmente la referencia actual de Apple y responder a partir de información aprendida durante su entrenamiento.
Una API puede seguir existiendo pero haber sido sustituida por otra alternativa. También puede cambiar su disponibilidad entre iOS, macOS, watchOS y visionOS. Una propiedad puede requerir una versión concreta del sistema operativo o estar aislada mediante MainActor.
Todo eso aparece en la documentación. El problema es conseguir que el agente pueda leerla correctamente.
Añadir .md convierte Apple Developer en documentación mucho más accesible
El método más sencillo funciona con las páginas alojadas bajo /documentation.
Por ejemplo, la referencia de UIViewRepresentable utiliza normalmente esta dirección web.
Para solicitar directamente la representación Markdown puede utilizarse:
https://developer.apple.com/documentation/swiftui/uiviewrepresentable.md
La diferencia resulta especialmente útil para software automatizado.
Apple Developer puede responder inicialmente a determinadas herramientas con el mensaje de que la página requiere JavaScript. Sin embargo, la propia documentación expone actualmente una opción «View Markdown», algo que puede comprobarse en páginas de SwiftUI.
El Markdown proporciona directamente elementos como el nombre de la API, declaración, descripción, parámetros, disponibilidad, relaciones y referencias asociadas.
Por ejemplo, la documentación actual de UIViewRepresentable permite recuperar directamente una declaración como:
@MainActor @preconcurrency protocol UIViewRepresentable : View
También aparecen sus métodos obligatorios, relaciones con otros tipos y advertencias sobre su utilización.
Eso es mucho más útil para un agente que intentar interpretar una aplicación web completa.
Además, Markdown consume normalmente menos contexto que introducir HTML, JavaScript, navegación y otros elementos de una página en el contexto del modelo.
| Contenido de Apple | Forma de acceso para agentes |
|---|---|
/documentation/... | Añadir .md |
| Referencias Swift / SwiftUI | Añadir .md |
| Human Interface Guidelines | Usar /tutorials/data/ y .md |
| Tutoriales compatibles | Usar /tutorials/data/ y .md |
| Algunos tutoriales sin Markdown | Utilizar .json |
No todas las páginas siguen exactamente el mismo esquema, por lo que conviene comprobar la respuesta antes de automatizarlo para grandes cantidades de documentación.
Las Human Interface Guidelines necesitan otra ruta
El procedimiento cambia para las páginas de diseño y algunos tutoriales.
En estos casos puede utilizarse la infraestructura /tutorials/data/ antes de la ruta original y solicitar posteriormente el archivo Markdown.
Una página de las Human Interface Guidelines puede transformarse siguiendo un esquema como:
https://developer.apple.com/tutorials/data/design/human-interface-guidelines/buttons.md
Los tutoriales presentan otra particularidad. Algunas páginas, especialmente determinados contenidos introductorios, no disponen de representación Markdown.
En esos casos puede probarse la representación JSON:
https://developer.apple.com/tutorials/data/tutorials/swiftui.json
No es un simple truco para evitar JavaScript. Desde la perspectiva de un agente, Markdown y JSON son formatos considerablemente más fáciles de procesar, dividir, indexar y relacionar con una pregunta concreta.
También permiten construir una skill que transforme automáticamente las URL de Apple antes de entregar la documentación al modelo.
Un desarrollador podría indicarle al agente algo parecido a: cuando necesite consultar Apple Developer, debe solicitar primero la versión Markdown y utilizar JSON como alternativa para determinados tutoriales.
La documentación deja entonces de depender de que el agente conozca este comportamiento por casualidad.
Xcode 27 hace que tener documentación actualizada sea mucho más importante
La cuestión adquiere otra dimensión con Xcode 27.
Apple ha ampliado considerablemente la programación agéntica dentro de su entorno de desarrollo. Xcode permite trabajar con diferentes agentes y modelos, incluido ChatGPT, Claude y herramientas de otros proveedores. Los agentes externos compatibles pueden conectarse mediante Agent Client Protocol (ACP).
Ya no hablamos únicamente de pedir:
Crea una vista SwiftUI con tres botones.
Un agente puede recibir una tarea bastante más amplia, inspeccionar el proyecto, planificar modificaciones y trabajar sobre diferentes archivos.
Apple permite además personalizar sus entornos mediante archivos de configuración específicos. Es posible establecer modelos, añadir servidores MCP y crear skills propias. Xcode también permite instalar complementos que incorporen subagentes, servidores MCP y nuevas capacidades.
La propia documentación de Apple explica que estas herramientas buscan que los agentes puedan validar su trabajo y operar durante más tiempo con menor intervención humana.
Xcode 27 incorpora además Device Hub, que reúne dispositivos físicos y simuladores para inspeccionar su estado, reproducir problemas y agilizar las pruebas.
La combinación cambia bastante el flujo de desarrollo:
documentación → planificación → código → compilación → ejecución → pruebas → corrección.
Un agente puede participar en varias de esas fases.
Precisamente por eso una documentación incorrecta resulta ahora más peligrosa.
Un agente puede equivocarse mucho más rápido que un programador
Cuando un asistente genera diez líneas incorrectas, el desarrollador probablemente detectará el problema al compilarlas.
Cuando un agente modifica veinte archivos, actualiza dependencias, cambia una arquitectura y adapta pruebas basándose en una suposición incorrecta, encontrar el origen del problema puede resultar bastante más complicado.
La velocidad funciona en ambas direcciones.
Un agente puede ejecutar en minutos un trabajo repetitivo que habría requerido horas. También puede propagar una decisión incorrecta por todo un proyecto con esa misma rapidez.
Consultar documentación actualizada reduce una fuente importante de errores, pero tampoco convierte automáticamente en correcto lo que produzca el modelo.
Una API documentada puede ser técnicamente válida y seguir siendo una mala decisión arquitectónica.
También puede existir una alternativa mejor para el proyecto concreto.
Y una función disponible desde iOS 27 puede ser inútil si la aplicación necesita mantener compatibilidad con iOS 25.
La documentación responde a qué permite una API y bajo qué condiciones. No decide necesariamente si debe utilizarse.
Ahí sigue entrando el conocimiento del desarrollador.
El problema de fondo no es escribir código, sino poder auditarlo
La programación asistida por IA está cambiando rápidamente una habilidad que durante décadas estuvo en el centro del oficio.
Escribir cada línea manualmente deja de ser imprescindible para determinadas tareas.
Entenderlas no.
Un desarrollador que utiliza agentes necesita saber si una API está obsoleta, si una operación debería ejecutarse en el actor principal, si una decisión rompe compatibilidad, si una vista está acumulando responsabilidades o si el agente está resolviendo un problema local introduciendo deuda técnica en otra parte del proyecto.
Esto introduce una diferencia entre dos formas de utilizar estas herramientas.
Una consiste en aceptar código porque compila.
La otra consiste en utilizar el agente para producir trabajo rápidamente, pero exigirle fuentes, revisar decisiones arquitectónicas y validar el resultado.
El acceso directo a Markdown puede ayudar incluso en esa revisión.
En lugar de preguntar al agente simplemente si una API es correcta, puede pedírsele que consulte la documentación actual de Apple, indique disponibilidad, compruebe si existe una alternativa recomendada y justifique la implementación antes de modificar el proyecto.
La respuesta deja entonces un rastro mucho más fácil de auditar.
Una skill puede hacer que el agente consulte Apple antes de programar
Xcode 27 permite llevar esta idea un paso más allá mediante las skills de los agentes.
Apple documenta que los desarrolladores pueden proporcionar instrucciones y conocimientos especializados para adaptar el comportamiento del agente. También pueden configurar servidores MCP y herramientas externas.
Eso permite convertir el pequeño truco de .md en una regla del entorno de desarrollo.
Una skill interna podría establecer, por ejemplo, que antes de introducir una API de Apple que no esté ya utilizada en el proyecto el agente debe localizar su documentación oficial, recuperar preferentemente su representación Markdown, comprobar la versión mínima del sistema operativo y revisar posibles advertencias o alternativas.
No elimina las alucinaciones.
Reduce la dependencia de la memoria interna del modelo y proporciona información actual en el momento en que se escribe el código.
La diferencia es especialmente importante con SwiftUI, donde Apple introduce APIs y patrones nuevos con frecuencia y donde ejemplos que funcionaban correctamente hace unos años pueden no representar actualmente la mejor implementación.
La disponibilidad de Markdown hace además posible construir sistemas RAG (Retrieval-Augmented Generation) o índices internos basados exclusivamente en documentación oficial de Apple, sin tener que depender de blogs o respuestas antiguas de Stack Overflow para cada consulta.
La documentación accesible no sustituye al criterio técnico
Hay cierta ironía en todo esto.
Xcode 27 ofrece agentes cada vez más autónomos. Pueden consultar proyectos, utilizar herramientas, ejecutar comandos, trabajar con MCP y recibir skills especializadas. Apple presenta estas capacidades precisamente como una forma de permitir que trabajen durante más tiempo con menor intervención.
Y, sin embargo, algo tan sencillo como comprender cómo obtener correctamente la documentación puede determinar la calidad de todo el proceso.
La solución tampoco apareció necesariamente porque un modelo razonara espontáneamente sobre el problema. Un desarrollador tuvo que identificar que el contenido visible dependía de JavaScript, localizar una representación alternativa y convertir ese conocimiento en una regla reutilizable.
Ese trabajo sigue teniendo valor.
Los agentes reducen el coste de producir código. Como consecuencia, aumenta el valor de saber qué código debe producirse, con qué API, bajo qué restricciones y cómo comprobar que el resultado es correcto.
Añadir .md al final de una URL parece un detalle insignificante. Para un agente que puede modificar decenas de archivos sin intervención constante, supone la diferencia entre consultar la referencia actual de Apple y confiar en lo que recuerda de su entrenamiento.
La programación agéntica puede hacer que escribir código sea cada vez más rápido. Entender la plataforma, auditar lo generado y detectar cuándo el agente está convencido pero equivocado continúa siendo trabajo de ingeniería.
