En mi artículo anterior, "Del código a los conocimientos: mejores prácticas de ingeniería de software para analistas de datos", que las habilidades y mejores prácticas de ingeniería pueden ser increíblemente útiles para los analistas y otros profesionales de datos.
Esto es aún más cierto ahora en la era de la IA, cuando tenemos muchas más oportunidades para construir nuestras propias herramientas analíticas: desde sofisticados visores de datos que muestran gráficos o muestran diferentes escenarios, hasta simuladores que pueden predecir resultados basados en parámetros de entrada. Personalmente, uso aplicaciones web todo el tiempo en mi trabajo diario.
Ha habido mucho entusiasmo en torno a la codificación de vibraciones, pero parece que los ingenieros profesionales ya están yendo más allá y inclinándose más hacia el desarrollo basado en especificaciones. Incluso Andrej Karpathy, quien acuñó el término “codificación de vibraciones” en febrero de 2025, admitió apenas un año después que esta era está llegando a su fin y que estamos entrando en la era de la ingeniería de agentes: orquestar agentes según especificaciones detalladas con supervisión humana.
Hoy (un año después), la programación a través de agentes LLM se está convirtiendo cada vez más en un flujo de trabajo predeterminado para los profesionales, excepto que hay más supervisión y escrutinio. El objetivo es aprovechar el uso de agentes pero sin comprometer la calidad del software. Mucha gente ha intentado encontrar un nombre mejor para esto para diferenciarlo de vibe coding, personalmente mi actual “ingeniería agentica” favorita:
– “agente” porque el nuevo valor predeterminado es que no se escribe el código directamente el 99% del tiempo, sino que se orquesta a los agentes que lo hacen y actúan como supervisores.
– “ingeniería” para enfatizar que hay un arte, una ciencia y una experiencia en ello. Es algo que puedes aprender y en lo que puedes mejorar, con su propia profundidad de un tipo diferente.
En este artículo, me gustaría poner en práctica el desarrollo basado en especificaciones en un proyecto totalmente nuevo, siguiendo las mejores prácticas del curso de JetBrains sobre DeepLearning.AI, "Desarrollo basado en especificaciones con agentes de codificación".
El proyecto es un poco más personal, pero sigue relacionado con datos. Mientras me preparo para mi media maratón en septiembre, intento equilibrar la carrera y el entrenamiento de fuerza. Hay tantas herramientas disponibles, cada una enfocada en una parte diferente del viaje, que encontrar una solución que realmente funcione para mí ha sido sorprendentemente difícil. Entonces, decidí alimentar a dos pájaros con un bollo: crear mi propia aplicación web y, con suerte, aprender algo nuevo en el camino.
¿Listo para la acción? Yo también. Pero antes de pasar a la implementación, permítanme dedicar unos minutos a la teoría detrás del desarrollo basado en especificaciones.
Codificación Vibe versus desarrollo basado en especificaciones
Muchos de nosotros ya hemos experimentado la codificación de vibración: escribe un mensaje breve (por ejemplo, "Agregue un gráfico DAU a mi aplicación web"), espera a que el agente genere el cambio, lo ejecuta localmente y verifica si el resultado coincide con sus expectativas.
Por lo general, no es así. Entonces regresa al mismo chat, le pide al agente que ajuste el gráfico y continúa iterando hasta que el resultado sea lo suficientemente bueno.
Este enfoque funciona razonablemente bien para proyectos simples, pero no escala bien, especialmente cuando varios desarrolladores trabajan en la misma base de código.
Los principales inconvenientes son la falta de mejores prácticas y convenciones compartidas. Por ejemplo, sin un enfoque estructurado, los equipos pueden terminar fácilmente con cinco formas diferentes de ejecutar el entrenamiento del modelo ML dentro del mismo canal DBT.
Otro problema común es que normalmente no persistimos en los resultados o el razonamiento de nuestras conversaciones con los agentes de IA. Como resultado, resulta fácil perder de vista por qué se tomaron ciertas decisiones. Por ejemplo, un agente podría olvidar por qué limpió los datos de una manera particular y la próxima actualización podría introducir silenciosamente un resultado diferente.
La decadencia del contexto también es un problema especialmente común. Los agentes de IA no tienen estado y, cuando trabajamos en proyectos más grandes, a menudo tenemos que iniciar nuevos chats debido a las limitaciones de la ventana de contexto, lo que efectivamente inicia nuestra comunicación desde cero.
El desarrollo basado en especificaciones (SDD) está mucho más cerca de las prácticas de ingeniería tradicionales. En lugar de saltar directamente a la implementación, comenzamos por pensar detenidamente nosotros mismos: tomar decisiones arquitectónicas, definir requisitos y documentarlos en una especificación de rebajas estructurada almacenada en el repositorio y actualizada junto con el proyecto. Esto crea un cambio importante: desacoplamos la especificación (qué estamos construyendo y por qué) de la implementación (el código real).
SDD aborda muchos de los problemas centrales de la codificación de vibraciones al preservar el contexto entre las sesiones (e incluso entre diferentes agentes de IA) mientras alinea tanto a los humanos como a los agentes en torno a los principales elementos no negociables del proyecto.
flujo de trabajo SDD
Un flujo de trabajo de desarrollo típico basado en especificaciones normalmente consta de las siguientes etapas.
El primer paso es definir la constitución: un acuerdo sobre las decisiones clave para el proyecto. Suele incluir varios documentos básicos:
La misión explica el por qué: ¿por qué estamos construyendo este proyecto y cuáles son sus objetivos y características clave? Tech Stack documenta decisiones técnicas, así como procesos de implementación y actualización. La hoja de ruta describe las fases del proyecto, las características planificadas y se actualiza continuamente a medida que evoluciona el proyecto.
Se pueden crear especificaciones tanto para proyectos nuevos como existentes, lo que hace que este enfoque sea bastante versátil.
Una vez que la documentación a nivel de proyecto esté lista, podemos pasar a la fase de desarrollo de funciones, que normalmente incluye:
Comprender lo que queremos construir y escribir una especificación detallada. Implementando los cambios. Validar que la implementación funcione según lo esperado.
Después de implementar con éxito su primera función, es posible que sienta inmediatamente la necesidad de pasar a la siguiente. Pero en realidad este es el momento adecuado para hacer una pausa y repensar.
Aquí es donde entra en juego la replanificación. Es una fase dedicada a revisar la constitución y revisar las decisiones y planes de funciones anteriores para asegurarse de que aún se alineen con los objetivos del proyecto.
Ahora que hemos cubierto la teoría, pongámosla en práctica.
Edificio
Basta de teoría, es hora de construir. Para comprender mejor cómo funciona en la práctica el desarrollo basado en especificaciones, decidí aplicarlo a un proyecto totalmente nuevo.
Empecé creando un nuevo repositorio para este proyecto (y, por supuesto, dedicando media hora a elegir el nombre y el logotipo): repositorio. También documenté mi visión inicial del producto en el archivo README.md.
Una de las ventajas del enfoque SDD es que es en gran medida independiente de la elección de LLM, agente o IDE, por lo que puede trabajar con la configuración que prefiera. Para este proyecto, usaré Visual Studio Code con el complemento Claude Code, ya que me permite usar Claude como agente y al mismo tiempo revisar todos los cambios de código directamente en el editor.
Creando una constitución
Como comentamos, el primer paso es redactar la constitución. Por supuesto, no necesitamos hacerlo manualmente, podemos usar LLM para armarlo en función de la visión inicial del producto, así como del contexto adicional recopilado a través de preguntas de seguimiento.
Estamos creando Trainlytics, una aplicación web de seguimiento de actividad física personal creada para personas que desean más control, flexibilidad y conocimientos que los que ofrecen las aplicaciones de actividad física estándar. Encuentre los requisitos completos en README.md. Creemos una "constitución" en un directorio de especificaciones que consta de las siguientes partes: – misión.md: qué y por qué estamos construyendo; la misión principal del producto – tech-stack.md – decisiones técnicas centrales – roadmap.md – fases del proyecto desglosadas en orden de implementación IMPORTANTE: debe utilizar su herramienta AskUserQuestion para obtener mis comentarios.
Luego, el agente hace una serie de preguntas aclaratorias que ayudan a definir la constitución del proyecto y crear un plan de implementación inicial.
Al final, el agente creó los tres archivos que le solicitamos.
En este punto, es posible que sienta la necesidad de pedirle inmediatamente al agente que comience a construir el proyecto, pero puede que sea demasiado pronto.
Antes de seguir adelante, primero debemos validar y perfeccionar la constitución. Ahora vale la pena dedicar tiempo a alinear el plan, porque esta especificación luego se traducirá en miles de líneas de código. Es mucho mejor resolver las ambigüedades y los errores cuanto antes.
Por lo general, hago esto leyendo los documentos yo mismo e interactuando con el agente, haciendo preguntas aclaratorias y perfeccionando el plan paso a paso. Una buena práctica es realizar todos los cambios a través del agente en lugar de parchear los documentos usted mismo para mantener la coherencia en todo el proyecto. Por ejemplo, le dije al agente que necesitamos autenticación en la aplicación, ya que mi caso de uso es registrar entrenamientos desde dispositivos móviles y de escritorio. Esto llevó a actualizaciones tanto en el documento de la pila tecnológica como en la hoja de ruta.
Una vez que esté satisfecho con la revisión, también puede pedirle a un segundo agente, con un nuevo contexto, que critique el plan. Hay mucha evidencia de que la reflexión mejora la calidad del resultado.
Cuando se completen todas las comprobaciones, es hora de enviar la constitución al repositorio.
Primera fase característica
Ahora es el momento de pasar a la primera fase de funciones.
De acuerdo con nuestra hoja de ruta, comenzaremos con el MVP: Registro de actividad principal. Al final de esta fase, un usuario debería poder iniciar sesión tanto en su computadora de escritorio como en su dispositivo móvil, registrar una carrera y una sesión de gimnasio, y ver ambas en su historial con todos los detalles.
Como se analizó, cada fase de característica sigue un ciclo simple: planificar → implementar → validar. Entonces, comencemos por definir la especificación y construir el plan.
Busque la siguiente fase en specs/roadmap.md y cree una nueva rama. Pregúnteme sobre cualquier paso en las especificaciones que no esté completamente claro. Luego cree un nuevo directorio en el formato AAAA-MM-DD-nombre-función bajo specs/ para esta característica, con los siguientes archivos: – plan.md – una lista estructurada de grupos de tareas numerados – requisitos.md – alcance, decisiones clave y contexto – validation.md – cómo definimos el éxito y confirmamos que la implementación se puede fusionar Utilice specs/mission.md y specs/tech-stack.md como guía.
Consejo: vale la pena iniciar una nueva sesión con un contexto claro en su agente LLM.
El agente preparó las especificaciones con bastante rapidez.
En este punto, es hora de revisar las especificaciones y asegurarse de que todo esté alineado con la visión original. Como puede ver, con la ingeniería de agentes, el papel del desarrollador cambia hacia dirigir, revisar y tomar decisiones arquitectónicas, en lugar de escribir especificaciones o código directamente.
Una vez que esté satisfecho con el plan, es hora de pasar a la implementación. Prefiero implementar cada grupo de tareas por separado en lugar de realizar una sola vez toda la fase de función, pero esto depende del tamaño de la función. Para este proyecto, utilicé el siguiente mensaje.
Tome el siguiente grupo de tareas de 2026-05-04-phase-1-mvp/plan.md e impleméntelo. Utilice require.md y validation.md como guía. Una vez hecho esto, actualice el estado tanto en el plan como en los documentos de validación.
Cuando el código esté listo, es hora de revisarlo. Este es uno de los pasos más importantes, por lo que vale la pena invertir algo de tiempo aquí.
En aplicaciones relacionadas con datos, normalmente centro mi revisión en la lógica empresarial central y compruebo que los números coincidan con mis expectativas.
Debo confesar que tengo un conocimiento casi nulo de las tecnologías frontend, por lo que rara vez reviso el código frontend en detalle. En lugar de eso, simplemente pruebo la interfaz localmente y compruebo si todo funciona como se esperaba. Para este caso, decidí ejecutar la aplicación y ver cómo funciona.
Después de algunas iteraciones con el agente, logramos ejecutar la aplicación localmente y funcionó. Ya podemos agregar diferentes ejercicios y tipos de actividad, y registrar sesiones tanto de cardio como de fuerza.
Después de la revisión manual, también es útil utilizar la reflexión y pedirle al nuevo agente que verifique si la implementación se alinea con el plan, así como que revise los puntos definidos en validation.md.
En teoría, el desarrollo basado en especificaciones sugiere que la fase de características termina con la validación. En la práctica, rara vez funciona tan limpiamente. Probablemente encontrará que algunas partes de la implementación no funcionan como se esperaba. En ese punto, tienes dos opciones:
Agregue un par de iteraciones más a su plan.md y continúe perfeccionando la función (esto funciona bien para cambios más pequeños), o si los problemas son más sustanciales, trátelos como parte de la siguiente fase de la función y trátelos durante la replanificación.
Una cosa importante a tener en cuenta: puede resultar tentador simplemente explicar el problema al agente de LLM y pedirle soluciones, en lugar de actualizar las especificaciones y reelaborar la implementación. Intenta resistir ese atajo. Mantener la especificación como fuente de verdad es lo que hace que el enfoque sea sólido.
Una vez que se completen todas las comprobaciones, podemos crear y fusionar la solicitud de extracción.
En este punto ya tenemos una aplicación funcionando y los resultados son realmente satisfactorios. Aún más sorprendente es que todo el proceso tomó poco más de dos horas de principio a fin (incluida la redacción de este artículo mientras el agente estaba trabajando).
Replanificación
Con un progreso tan bueno, es posible que sientas la necesidad de seguir construyendo. Lo entiendo, pero en la era actual de la IA, el principal valor de un ser humano radica en el pensamiento y la arquitectura. Entonces, este es realmente el momento adecuado para dar un paso atrás y reflexionar: ¿aún queremos continuar en la misma dirección y qué deberíamos cambiar en nuestro producto y proceso?
Cuando comencé a usar la aplicación, me di cuenta de que aún no estaba lista para admitir completamente mi caso de uso. Eso significa que debemos cambiar las prioridades para poder empezar a utilizarlo en mi vida diaria lo antes posible. Entonces, lo hice con el siguiente mensaje.
Revisemos nuestro plan en roadmap.md. Priorizaría las siguientes fases de la siguiente manera: 1. Plantillas de sesiones de fuerza Puedo vivir sin planificación, pero necesito plantillas, porque a menudo me cuesta recordar todos los ejercicios de una sesión. La idea es: – Si ya existe una plantilla en el registro, mostrar todas las estadísticas (ejercicios, series, repeticiones, peso, etc.). Permitir editar estos valores y realizar cambios – Si se cambia algo, pregunte si el usuario desea actualizar la plantilla 2. Mejoras en la interfaz de usuario El diseño actual aún no es lo suficientemente elegante, por lo que priorizaría una ronda de mejoras en la interfaz de usuario: – Agregar el logotipo y el lema del producto al sitio web – Agregar una pestaña de configuración para administrar tipos de actividades y ejercicios – Crear una pantalla única para registrar sesiones de cardio y fuerza – Mejorar la pantalla de historial con detalles de actividad más completos – Permitir agregar títulos a actividades (sesiones de fuerza/cardio) y segmentos – Admitir la especificación de tiempo, no solo fecha – Agregue más color a la interfaz (me gustan los tonos de azul) – Para ejercicios cardiovasculares, ajuste las unidades a: minutos, kilómetros y ritmo min/km 3. Análisis básicos Agregue análisis simples a la pantalla de historial que muestra estadísticas semanales en la parte superior de la página (por ejemplo, minutos totales y calorías divididas entre cardio y fuerza).
La replanificación también es un buen momento para revisar nuestro proceso en sí. Por ejemplo, noté que no hemos actualizado roadmap.md de manera constante y las especificaciones están comenzando a variar. También sería útil introducir un registro de cambios, para tener un historial claro de cómo ha evolucionado el producto a lo largo del tiempo.
Pidamos al agente que lo haga por nosotros.
Revise plan.md, actualice roadmap.md para reflejar el trabajo completado y cree un archivo CHANGELOG.md con un resumen conciso de los cambios.
Ahora que estamos alineados en la dirección y tenemos la configuración correcta, sigamos construyendo.
La siguiente fase
Ahora podemos seguir el mismo proceso e iterar por fases. Dado que se trata de un ciclo repetible, es un buen momento para discutir posibles automatizaciones.
Hasta ahora, hemos estado escribiendo todas las indicaciones manualmente, pero estos flujos de trabajo también se pueden automatizar como "habilidades" en Claude Code u otros agentes de codificación LLM.
Además, ya existen implementaciones de desarrollo basado en especificaciones que se pueden utilizar de forma inmediata. Uno de los más populares es Spec Kit de GitHub.
Puedes instalarlo así.
instalación de la herramienta uv spec-cli –desde git+https://github.com/github/spec-kit.git especifique el número de versión para comprobar que funciona
A continuación, debes inicializar las habilidades en Claude. Esto configura la carpeta .specify/ e instala los comandos de barra diagonal en .claude/commands/
especifique inicio. –integración claude # hay 30 integraciones con agentes, así que especifica cuál estás usando
Sabrá que funcionó cuando vea los comandos speckit en el Código Claude.
Una vez instalado, puede seguir un flujo de trabajo similar: comience definiendo la constitución y luego repita los bucles de funciones.
Una diferencia es que en Spec Kit, la constitución se centra más en preocupaciones de alto nivel como la calidad del código, los estándares de prueba, la coherencia de UX y los requisitos de rendimiento.
Para ser honesto, prefiero ligeramente el enfoque propuesto por JetBrains, porque mantiene más contexto en la propia constitución. Pero, como siempre, no existe una solución milagrosa y el kit de especificaciones puede funcionar mejor según su caso de uso. También es conveniente que ya tenga implementado el flujo de trabajo SDD.
Usando Spec Kit, realicé las dos fases descritas anteriormente y funcionó bien. Después de la primera fase de funciones, el desarrollo se convierte naturalmente en un ciclo de mejora continua en lugar de un proceso lineal. Y con eso, creo que es hora de concluir esta historia.
Resumen
En total, me llevó alrededor de 4,5 horas crear un producto integral utilizable para rastrear y analizar mis datos. Todavía hay mucho margen de mejora y seguiré repitiéndolo. Ya puedo ver varias mejoras potenciales en la interfaz de usuario y, eventualmente, también me gustaría integrar IA para hacer que la aplicación sea más inteligente.
Francamente, ha sido una experiencia interesante trabajar a través de un flujo de desarrollo tan estructurado. En mi trabajo diario, a menudo dependo de chats únicos de LLM para realizar cambios, sin mantener un rastro completo de las decisiones y especificaciones en el repositorio.
Sin embargo, aquí no existe un enfoque único que sirva para todos.
Si solo desea realizar una pequeña mejora o ejecutar algún análisis ad hoc en otro portátil Jupyter, escribir las especificaciones completas por adelantado probablemente sea excesivo. Pero cuando trabajas en un proyecto más grande (especialmente con otras personas), el desarrollo basado en especificaciones definitivamente sería mi enfoque predeterminado.
También es interesante observar cómo está cambiando el papel de un ingeniero: de escribir código directamente a centrarse más en decisiones arquitectónicas, revisión y diseño de sistemas.
Y aunque pueda parecer un poco extremo hoy en día, creo que nos estamos moviendo gradualmente hacia un mundo donde el inglés se convierte en la principal interfaz del “lenguaje de programación”. Ya estamos viendo los primeros intentos en esta dirección, como CodeSpeak, que explora paradigmas de programación más basados en lenguaje natural. Probaré CodeSpeak en mi próximo artículo, así que estad atentos.
Referencia
Este artículo está inspirado en el curso breve "Desarrollo basado en especificaciones con agentes de codificación" de DeepLearning.AI.