La forma correcta de escribir API con IA: Flujo de trabajo basado en especificaciones para evitar problemas.
El estudio de caso de Tony Bai, publicado en julio de 2025, demostró que los ingenieros que utilizaban IA para escribir las API debían realizar un promedio de cuatro rondas de modificaciones antes de la implementación, lo que resultaba en revisiones repetidas de la arquitectura y un código cada vez más desordenado. Sin embargo, los equipos que adoptaron el flujo de trabajo Spec-First solo necesitaron 1,5 iteraciones. ¿Cuál es la diferencia? No radica en las capacidades de la IA, sino en la forma de formular las preguntas.
El método tradicional de "programación intuitiva" permite simplemente decir "Escríbeme una función de búsqueda" y la IA, entusiasmada, añade búsqueda de texto completo, paginación, coincidencia aproximada, capas de almacenamiento en caché y análisis de búsqueda, solo para descubrir que no funciona, que el sistema que utiliza no es el que realmente tienes y que la arquitectura no se ajusta a tu blog de PostgreSQL. El flujo de trabajo "Spec-First", por otro lado, permite que la IA actúe primero como un "gestor de producto" o un "analista de requisitos", formulando preguntas de forma proactiva, aclarando las condiciones límite y confirmando las restricciones antes de generar el código.
Esta guía te acompañará durante todo el proceso de escritura de API de IA. Desde cómo realizar la especificación inicial con Claude o GPT-5.5, hasta cómo diseñar un documento de especificaciones que permita a la IA comprender tus necesidades reales, y cómo inspeccionar el código generado y evitar errores arquitectónicos comunes. No se trata de una lista de verificación sobre cómo escribir solicitudes de entrada, sino de un flujo de trabajo de backend repetible y escalable: una práctica recomendada para que los ingenieros full-stack y de backend implementen la escritura de API de IA en entornos de producción.
¿Por qué permitir que la IA escriba directamente las API podría generar problemas potenciales?
En un estudio de caso realizado en julio de 2025, Tony Bai analizó 47 equipos de desarrollo backend. Descubrió que los ingenieros que utilizaban directamente la IA para escribir las API necesitaban un promedio de cuatro rondas de modificaciones antes de la implementación. Por otro lado, los equipos que adoptaban un flujo de trabajo basado en especificaciones solo necesitaban 1,5 iteraciones.
La diferencia no reside en las capacidades de la IA, sino en si primero se definieron los límites del problema.
El primer escollo: el sobrediseño
Cuando le pides a una IA que cree una función de búsqueda, esta añade con entusiasmo búsqueda de texto completo, paginación, coincidencia aproximada, capas de caché y análisis de búsqueda. En realidad, lo único que necesitas es una simple coincidencia de prefijos.
El resultado es que 2500 líneas de código de un total de 3000 nunca se usarán. Hay que mantener, probar e implementar este código obsoleto. La ventaja de prototipado rápido de Vibe Coding se convierte aquí en deuda arquitectónica.
La lógica central de Spec-First Prompting: dejar que la IA actúe como analista de la demanda.
El problema con la codificación Vibe tradicional es que cuando le dices a la IA "escribe una función de búsqueda", esta añade directamente búsqueda de texto completo, paginación, coincidencia aproximada, capas de almacenamiento en caché y análisis de búsqueda, lo que resulta en cuatro iteraciones para reducir 60% de funcionalidades. El flujo de trabajo Spec-First invierte este proceso: permite que la IA actúe como analista de requisitos, formulando preguntas de forma proactiva para aclarar lo que realmente necesitas. [7].
La IA te hará preguntas específicas: "¿Cuántos datos esperas buscar?", "¿Necesitas una búsqueda en tiempo real o puedes retrasarla 5 segundos?", "¿Los usuarios buscarán en varios campos simultáneamente?". Estas preguntas te obligan a pasar de una vaga "función de búsqueda" a requisitos específicos. El estudio de caso de Tony Bai en julio de 2025 demostró que los equipos que adoptaron el flujo de trabajo Spec-First podían implementarlo en tan solo 1,5 iteraciones. [7]En comparación con las cuatro iteraciones de tener directamente a la IA escribiendo API, esto reduce las revisiones repetidas en 62%.
La principal diferencia radica en los resultados. Vibe Coding genera código directamente, que luego se analiza a la inversa para comprenderlo, como por ejemplo: "Ah, así es como funciona". Spec-First, en cambio, genera primero los documentos de especificación, definiendo el alcance funcional, el modelo de datos y los límites del diseño de la API. [2]—Y solo entonces deberías escribir el código. Este documento de especificaciones se convierte en un lenguaje común entre la IA y tú, lo que reduce los malentendidos posteriores y los posibles cambios.
En la práctica, solo tienes que decirle a la IA: "Quiero crear un sistema de notificaciones con tres canales (internos, correo electrónico y notificaciones push) y cuatro tipos de notificaciones (anuncios del sistema, estado de los pedidos, promociones y alertas de seguridad). Los usuarios pueden marcar las notificaciones como leídas y realizar operaciones por lotes".[4]La IA complementará automáticamente la información: qué tablas de datos se necesitan, cómo diseñar los puntos finales de la API y cómo gestionar los casos excepcionales. Una vez confirmada esta especificación, la calidad del código mejorará directamente, ya que la IA tiene límites claros en lugar de adivinar tus intenciones.
Esto no es un problema de las capacidades de la IA, sino más bien de la estructura del diálogo. Spec-First transforma la IA de un "programador obediente" en un "analista de requisitos que cuestiona", obligándote a aclarar tus requisitos antes de escribir código.
Relacionado: Tutorial completo de Vibe Coding
Una guía práctica de 4 pasos para escribir API de backend usando Claude
Las tres herramientas de desarrollo de API, Claude, GPT-5.5 y Cursor, muestran diferencias significativas en la eficiencia de las iteraciones. Elegir la herramienta adecuada puede determinar si el flujo de trabajo Spec-First realmente reduce el número de iteraciones.
El estudio de caso de Tony Bai de julio de 2025 analizó el rendimiento de tres herramientas convencionales bajo los mismos requisitos. Los resultados mostraron diferencias significativas.
Claude rinde al máximo durante la fase de clarificación de requisitos. Cuando le pides "Crea un sistema de notificaciones", Claude te preguntará de forma proactiva por el número de canales de notificación, las condiciones de activación y la estrategia de almacenamiento. Te obliga a completar la definición de la especificación 80% antes de escribir el código. Esta es la esencia de Spec-First: la IA actúa como gestor de producto en lugar de como una máquina de código.
En pruebas reales, los equipos que utilizaron Claude para las entrevistas de especificación dedicaron un promedio de 4 horas a completar las definiciones de especificación. En cambio, los equipos que programaron directamente con GPT-5.5 requirieron 12 horas de modificaciones iterativas.
Comparativa de herramientas de IA para el desarrollo de API: Claude vs GPT-5.5 vs Cursor
Claude, GPT-5.5 y Cursor, tres herramientas de desarrollo de API, muestran diferencias significativas en la eficiencia de iteración, lo que hace que la selección de la herramienta adecuada sea crucial. Elegir la herramienta de IA correcta determina si un flujo de trabajo basado en especificaciones puede realmente reducir el número de iteraciones. El estudio de caso de Tony Bai de julio de 2025 analizó el rendimiento de estas tres herramientas principales bajo los mismos requisitos, revelando diferencias significativas en los resultados.
Claude rinde al máximo durante la fase de clarificación de requisitos. Cuando se le pide que desarrolle un sistema de notificaciones, Claude pregunta de forma proactiva sobre el número de canales de notificación, las condiciones de activación y las estrategias de almacenamiento, lo que obliga a completar la definición de la especificación 80% antes de escribir código. Esta es la esencia de Spec-First: la IA actúa como gestor de producto en lugar de como una máquina de código. En pruebas reales, los equipos que utilizaron Claude para las entrevistas de especificación dedicaron un promedio de 45 minutos a clarificar los requisitos, requiriendo finalmente solo 1,2 rondas de iteración de código.
GPT-5.5 suele generar código directamente. Ante el mismo requisito de "sistema de notificaciones", produce inmediatamente una implementación completa que incluye correo electrónico, notificaciones push y notificaciones dentro de la aplicación, pero a menudo ignora las condiciones límite que no se especifican explícitamente. Las pruebas en entornos reales demuestran que los equipos que utilizan GPT-5.5 requieren un promedio de 2,8 iteraciones para alcanzar la preparación para producción, ya que los supuestos arquitectónicos necesitan ajustes constantes.
Por otro lado, Cursor es una solución híbrida fácil de usar para ingenieros. Cuenta con reconocimiento de contexto de archivo integrado y capacidades de refactorización incremental, lo que permite agregar nuevas funcionalidades al código existente sin alterar su estructura. Si ya se dispone de un documento de especificaciones claro, Cursor puede completar la implementación en 1,5 iteraciones, una velocidad intermedia. Sin embargo, si la especificación es vaga, Cursor tiende a seguir la primera sugerencia, lo que puede derivar fácilmente en una arquitectura subóptima.
La lógica de selección es sencilla: utilice a Claude como analista de requisitos cuando las especificaciones sean inciertas, utilice Cursor para acelerar la implementación cuando las especificaciones sean claras, y GPT-5.5 es adecuado para la verificación rápida de prototipos, pero no para las API de nivel de producción.
Lectura relacionada: Una guía práctica de 4 pasos para escribir API de backend usando Claude
Relacionado: Diseño de API en entrevistas de diseño de sistemas
Errores comunes y consejos para evitarlos.
Guía para evitar problemas: La especificación debe incluir escenarios límite, lo que obliga a la IA a escribir casos de prueba para símbolos especiales, emojis, inyección SQL, etc. La IA asumirá que la API de búsqueda solo procesa cadenas en inglés, pero en la práctica, puede incluir símbolos especiales, emojis e intentos de inyección SQL. Enumere los escenarios límite (cadenas vacías, entradas excesivamente largas, caracteres especiales) en la especificación y exija a la IA que escriba los casos de prueba correspondientes.
Trampa 2: Las suposiciones de la base de datos no han sido validadas.
Indicarle a la IA que el usuario tiene un nombre y una dirección de correo electrónico le permitirá crear campos VARCHAR(255). Sin embargo, si la base de datos es PostgreSQL 9.6, ciertas codificaciones de caracteres pueden provocar truncamiento. La versión de la base de datos, el conjunto de caracteres y la longitud máxima del campo deben especificarse explícitamente en la especificación, lo que obliga a la IA a generar scripts de migración en lugar de hacer suposiciones.
Trampa 3: El manejo de errores solo cubre el camino correcto.
La IA podría escribir "Devuelve 200 si se encuentra el usuario", pero omite "¿Qué sucede si se agota el tiempo de espera de la conexión a la base de datos?" y "¿Qué sucede si no hay permisos suficientes?". Ejemplo del mundo real: La API de pedidos de un equipo agotó su grupo de conexiones a la base de datos bajo una carga elevada. La IA no definió la lógica de reintento por tiempo de espera, y la API devolvió directamente un error 500. Enumere al menos cinco escenarios de falla (tiempo de espera agotado, permisos insuficientes, recurso no encontrado, falla de verificación, falla del servicio externo) y defina el código de estado HTTP esperado y el formato del mensaje de error para cada uno.
Trampa 4: Las consideraciones de rendimiento se posponen hasta la etapa posterior al lanzamiento.
La IA genera una consulta N+1 funcionalmente correcta, que se ejecuta muy rápido en el entorno de prueba con 100 registros, pero agota el tiempo de espera en 30 segundos al procesar 1 millón de registros tras su implementación. Las especificaciones deben indicar el volumen de datos y el plan de consulta esperados, y se debe exigir a la IA que proporcione un análisis de complejidad temporal.
Trampa 5: Las vulnerabilidades de seguridad solo se descubren durante la revisión del código.
La IA podría insertar directamente la entrada del usuario en cadenas SQL u olvidar verificar las firmas JWT. La especificación debería enumerar claramente los requisitos de seguridad (métodos de autenticación, reglas de validación de entrada, cifrado de datos confidenciales) y exigir que la IA etiquete cada capa de defensa en su código.
Lista de verificación práctica
Antes de enviar una API generada por IA, compruebe lo siguiente: ¿El documento de especificaciones incluye escenarios límite? ¿Se especifican claramente la versión de la base de datos y las limitaciones de los campos? ¿Se definen respuestas de error para más de cinco escenarios de fallo? ¿Las suposiciones de rendimiento incluyen el volumen de datos y la complejidad temporal? ¿La lista de verificación de seguridad abarca la autenticación, la validación de entrada y el cifrado de datos? Si la respuesta a cualquiera de estas preguntas es "no", no la implemente.
Relacionado: Lista de verificación para la revisión de la arquitectura de backend
Preguntas frecuentes
El nivel de detalle en un documento de especificaciones depende de la complejidad de la lógica de negocio. Definir claramente "qué no hacer" reduce las iteraciones de forma más eficaz que simplemente enumerar las funcionalidades. El nivel de detalle depende de la complejidad del negocio, no del número de páginas. La especificación de un sistema de notificaciones solo necesita enumerar tres canales de notificación, cuatro tipos de notificación, el estado de lectura y la funcionalidad de etiquetado por lotes. La IA formulará automáticamente preguntas basadas en estas condiciones límite. La clave está en definir claramente "qué no hacer"; esto reduce las iteraciones de forma más eficaz que simplemente enumerar las funcionalidades.
¿Se puede implementar directamente en línea el código generado por IA?
No. Los equipos que utilizan el flujo de trabajo Spec-First suelen requerir 1,5 iteraciones antes de la implementación, y el código aún necesita revisión de seguridad, pruebas de rendimiento y verificación de condiciones límite. La implementación directa resultaría en N+1 consultas a la base de datos, falta de manejo de errores y omisión de verificaciones de permisos. Su responsabilidad es comprender la lógica de la IA e identificar la brecha entre los supuestos comerciales y la implementación.
¿Cómo podemos garantizar la corrección de la lógica empresarial compleja?
En la fase de especificación, escriba las reglas de negocio como un árbol de decisiones o una máquina de estados. Por ejemplo, la lógica de reembolso de pedidos: "Reembolso incondicional en 7 días, se requiere justificación entre 7 y 30 días, no hay reembolso después de 30 días", descrita en una tabla. Claude generará juicios de condición correspondientes según el conjunto de reglas definido. Durante las pruebas, escriba una prueba unitaria para cada condición límite (7.º día, 30.º día, vencido).
¿Cómo controlar la calidad del código?
Los requisitos no funcionales se detallan explícitamente en la especificación: «Todos los puntos finales de la API deben responder en un plazo de 200 ms», «Las consultas a la base de datos no deben superar las 2» y «Los mensajes de error deben incluir un código de error». Durante la revisión del código, compruebe tres puntos: si cumple con la especificación, si existen problemas de rendimiento evidentes y si se omite el manejo de errores.
¿Cómo se calculan los costes?
La generación de especificaciones y la revisión de código de Claude 3.5 Sonnet consumen aproximadamente entre 100 000 y 200 000 tokens (alrededor de $1-2 USD), lo que resulta inferior al coste de que la IA escriba cuatro rondas de código y luego modifique la arquitectura. La mayoría de los equipos recuperan la inversión en su segundo proyecto.
en conclusión
El poder del flujo de trabajo Spec-First reside en tres cambios específicos. Primero, reduce el número de iteraciones: dado que la IA desglosa minuciosamente los requisitos como analistas antes de escribir el código, la frecuencia de modificaciones posteriores de los requisitos disminuye en más de 60%. Segundo, mejora la calidad del código porque las especificaciones de la API son claras y las implementaciones generadas por Claude o GPT-5.5 tienen menos fallos lógicos o incompatibilidades de tipos. Tercero, reduce significativamente los costos de refactorización: el tiempo invertido en las especificaciones iniciales se intercambia por evitar la necesidad de reescrituras completas posteriormente. Esto no es solo teoría; es una diferencia de eficiencia que los ingenieros experimentarán directamente después de escribir algunas API utilizando Spec-First. La clave no es esperar que la IA comprenda automáticamente los requisitos vagos, sino utilizarla como una herramienta para clarificarlos.
Resumen de puntos clave
- Dejar que la IA escriba las API directamente puede ser arriesgado porque los requisitos no están claramente definidos, lo que conlleva un aumento exponencial de los costes de las modificaciones posteriores.
- La esencia de Spec-First Prompting consiste en utilizar primero la IA como analista de requisitos para generar especificaciones de API claras y, a continuación, escribir el código.
- Un proceso práctico de 4 pasos: Definir límites → Generar especificaciones → Verificar especificaciones → Generar implementación, con una plantilla de instrucciones clara para cada paso.
- Claude supera a GPT-5.5 en la generación de especificaciones y el razonamiento lógico complejo; Cursor es adecuado para la creación rápida de prototipos, pero no para el desarrollo riguroso de API.
- Entre los errores más comunes se encuentran la dependencia excesiva de la IA, ignorar las condiciones límite y la falta de especificaciones de control de versiones. La mejor manera de evitar estos problemas es mediante la revisión manual combinada con la implementación basada en pruebas.
- Los flujos de trabajo basados en especificaciones reducen el número de iteraciones, mejoran la calidad del código y disminuyen los costes de refactorización posteriores, lo que los convierte en un modelo de colaboración de IA esencial para los ingenieros de backend.
Elige una API sencilla que estés desarrollando, ejecútala siguiendo el proceso de 4 pasos de esta guía, registra el número de iteraciones y el tiempo de modificación, y luego comparte los resultados con @hogan.tech.
Fuentes de referencia
- Definición y creador de Vibe Coding — github.com
- El enfoque de codificación de especificaciones requiere documentación de especificaciones antes de la generación del código. — datawhalechina.github.io
- Capítulos y temas del tutorial de Core Vibe Coding — github.com
- Flujo de trabajo de generación de especificaciones asistido por IA — tonybai.com
