Desarrollo basado en especificaciones: lo bueno y lo que aprendimos después de tres meses
Después de tres meses, teníamos una idea más clara de cuándo la estructura adicional ayudaba y cuándo se interponía en el camino.
Uno de nuestros ingenieros estaba preparando una migración de datos y decidió usar el desarrollo basado en especificaciones (SDD) para planificar el trabajo. El SDD estaba destinado a ayudarlo a detectar las deficiencias con anticipación, facilitar la revisión del enfoque y darle al agente una orientación clara. El plan resultante era detallado y, sobre el papel, parecía bastante razonable. El trabajo se estructuró de la siguiente manera:
Problema → Investigación → Especificación → Revisión → Implementación → Verificación
A medida que avanzaba la implementación, el ingeniero se dio cuenta de que dos tareas podrían ejecutarse simultáneamente y crear campos personalizados duplicados. El enfoque también estaba haciendo que el código fuera cada vez más complejo y difícil de seguir. Afortunadamente, detectaron el problema, detuvieron la implementación, redactaron un documento de diseño de una página y etiquetaron a un par de compañeros de trabajo para que dieran su opinión. Juntos, trabajaron en el diseño y encontraron un enfoque más seguro.
Las especificaciones originales hicieron lo que pedimos: mantuvieron el proyecto avanzando en la dirección original. El problema era que la dirección era incorrecta. Una especificación detallada facilitó la continuación del proyecto, incluso cuando la idea inicial era poco sólida. El agente podía desarrollar esa idea más rápido de lo que la gente podía detenerse a cuestionarla.
Ese proyecto mostró un riesgo de la estructura añadida: un agente podría trasladar la misma suposición errónea de la especificación al código y a las pruebas. La especificación, el código y las pruebas coincidían entre sí, pero eso no significaba que la suposición subyacente fuera correcta. Para las decisiones más arriesgadas, otra persona aún tenía que volver al objetivo original y buscar formas en que la implementación pudiera incumplirlo.
Aun así, los agentes estaban asumiendo tareas que duraban más de una sesión, y una indicación a menudo no era suficiente para preservar lo que el proyecto intentaba hacer o por qué. Eso nos llevó a crear /spec-driven, un entorno de flujo de trabajo centrado en las especificaciones. La especificación mantenía la dirección del proyecto disponible para la siguiente sesión. Los scripts aportaban contexto y realizaban verificaciones. Cuando una ejecución revelaba una regla, una verificación o un elemento de contexto faltante, podíamos agregarlo al flujo de trabajo para que los agentes posteriores no tuvieran que volver a descubrir la misma brecha.
Todavía hay bastantes desacuerdos sobre si vale la pena la estructura adicional del SDD. Microsoft y AWS promueven el SDD, mientras que Thoughtworks lo describe como emergente y controvertido, y los profesionales informan experiencias dispares. Los críticos advierten que el SDD puede generar más Markdown del que los ingenieros pueden mantener, convertir una especificación detallada en código escrito en prosa o dejar atrás otra descripción del sistema que se desvía del código.[1][2][3]
Después de tres meses de uso real, aprendimos que la pregunta importante no era si usar el SDD. Era lo que le faltaba al agente en ese proyecto. A veces, la respuesta era una especificación. A veces era un mejor ejemplo, una verificación automatizada o un ingeniero que conocía el área.
Por qué creamos /spec-driven
Algunos ingenieros de Asana ya habían probado GitHub Spec Kit y OpenSpec, pero ninguno de los dos se incorporó a su flujo de trabajo habitual. Queríamos una versión que pudiéramos adaptar a medida que aprendiéramos y conectar con el proceso de desarrollo de Asana.
El modo de planificación integrado ya podía analizar la base de código y generar un plan de implementación útil antes de hacer cambios. El SDD agregó más estructura a ese plan: mantuvo el problema, las decisiones clave y los criterios de aceptación visibles durante la implementación y la verificación.
Antes de la implementación, /spec-driven reprodujo su comprensión del problema y planteó las preguntas que podrían cambiar el plan. Eso le dio al ingeniero la oportunidad de corregir el rumbo antes de que hubiera que reescribir el código.
Almacenamos ese estado en el repositorio para que en las sesiones posteriores no tuviéramos que adivinar lo que había sucedido. Queríamos que las reglas del flujo de trabajo fueran deterministas, por lo que los scripts se encargaban del registro y las verificaciones. El modelo se encargó de las partes que se beneficiaban del juicio: hacer preguntas, sopesar las compensaciones y explicar las decisiones.
El flujo de trabajo incluía varios comandos. Los ingenieros usaron /spec-driven spec para abordar las preguntas abiertas y elaborar una especificación y un plan de implementación. Después de revisar el plan, usaron /spec-driven ship para implementarlo, verificar el resultado y preparar el trabajo para su revisión. Una máquina de estados hacía un seguimiento del proyecto a medida que avanzaba por estos comandos, de modo que en las sesiones posteriores se supiera lo que había sucedido y lo que venía a continuación.
Desde el principio, queríamos que /spec-driven fuera algo más que una forma de redactar y llevar a cabo especificaciones. También queríamos que coordinara los flujos de trabajo de agentes. Ordena las tareas por dependencia y mantiene los cambios de archivos superpuestos en rondas de ejecución separadas. Envía trabajo independiente a varios agentes en paralelo y luego usa los resultados para decidir qué se puede ejecutar a continuación.
Es como un GPS para el trabajo: en cualquier momento queda claro cuál es el siguiente paso y dónde se toman las decisiones importantes, por lo que es difícil quedarse estancado.”
Los ingenieros de Asana usaron /spec-driven tanto de forma “spec-first” como “spec-anchored”. Con el enfoque basado en especificaciones, usaron una especificación para elegir una dirección y luego dejaron de actualizarla. Con el enfoque basado en especificaciones, la mantuvieron actualizada a medida que el trabajo cambiaba. Los ingenieros también redactaron especificaciones independientes para partes de un esfuerzo más amplio, de modo que una sola persona pudiera usar el flujo de trabajo sin tener que pedirle a todo el equipo que lo adoptara.
Cuándo vale la pena el trabajo adicional de /spec-driven
La estructura adicional dio mejores resultados cuando era necesario conservar el contexto importante a lo largo de varias sesiones, traspasos o muchas tareas relacionadas. Los ingenieros podían revisar cómo había cambiado el plan, y la dirección del proyecto seguía estando disponible cuando el trabajo pasaba a otra sesión de agente o a otra persona. Dos iniciativas de producto mantuvieron especificaciones dinámicas durante aproximadamente dos o tres meses: una para desarrollar una nueva función importante y la otra para actualizar las fechas de las subtareas en las tareas madre.
Acabo de terminar una iniciativa bastante grande con Spec-driven y creo que realmente me ayudó. Trabajé en el plan durante aproximadamente dos días y luego completé todo el trabajo de ingeniería y lo integré en tres días.”
Las especificaciones facilitaron los traspasos. Alguien que retomara un proyecto en pausa podía ver qué estaba tratando de hacer el equipo, por qué había tomado esa forma y qué quedaba por hacer. No tenían que reconstruir el proyecto a partir de confirmaciones y conversaciones.
Los ingenieros también usaron /spec-driven para coordinar grandes lotes de trabajo realizado por agentes. En la Consola del administrador de Asana, donde los equipos de TI de las empresas clientes gestionan la seguridad, el acceso, las integraciones y los ajustes de uso compartido de toda la organización, los ingenieros la usaron para trasladar 66 ajustes a marcos compartidos. Trasladar esos ajustes requirió aproximadamente 150 migraciones en varios marcos de la Consola del administrador. Cada migración se convirtió en un ticket de Asana para un agente en la nube, y los ingenieros las ejecutaron en grupos paralelos, actualizando los tickets restantes en función de los resultados anteriores.
El equipo que llevó a cabo ese esfuerzo informó que el 91 % de las migraciones no necesitaron revisiones después de la evaluación y que el esfuerzo general se completó más de un mes antes de lo previsto en el plan original.
Otra migración importante solo requirió una indicación breve. La diferencia radicaba en cuánto había quedado claro en la base de código. Tenía ejemplos que los agentes podían seguir y verificaciones que podían comprobar el resultado. Los agentes de la Consola del administrador no pudieron determinar todos los requisitos a partir del código, por lo que el trabajo necesitaba más estructura.
El enfoque basado en especificaciones también ayudó a crear prototipos rápidamente. Los ingenieros podían responder rápidamente a las preguntas abiertas sobre el producto lo suficiente como para crear una experiencia integral funcional. Los gerentes de producto y los diseñadores podían probar un prototipo antes de que los ingenieros invirtieran en la optimización para producción. Si los ingenieros decidían mantener el código, por lo general, era necesario realizar una limpieza sustancial antes de poder fusionarlo. Para entonces, el prototipo ya había demostrado si valía la pena seguir adelante con la idea.
Lo que mostraron las primeras cifras
Alentamos a todos a probar /spec-driven una vez, pero no exigimos su uso continuo. Aproximadamente la mitad de los ingenieros lo probaron. Durante el último mes, el uso semanal varió entre 30 y 50 ingenieros. Entre las habilidades de los agentes integradas y desarrolladas por Asana que los ingenieros invocaron directamente, /spec-driven ocupó el tercer lugar. El uso continuo fue alentador, pero no nos indicó cómo /spec-driven afectaba a la entrega.
La velocidad de ingeniería es notoriamente difícil de medir. Las solicitudes de extracción y las adiciones de código de implementación son indicadores imperfectos de la productividad, pero creemos que, por lo general, son medidas útiles en términos de dirección. Para la comparación de la velocidad, analizamos a siete ingenieros y 524 solicitudes de extracción integradas durante cuatro meses. Comparamos el trabajo antes y después del primer uso claro de /spec-driven por parte de cada ingeniero y excluímos las especificaciones, los planes y otros elementos del flujo de trabajo. Para la comparación de reversiones, clasificamos una solicitud de extracción como /spec-driven cuando modificaba los archivos del proyecto del flujo de trabajo.
Las solicitudes de extracción por semana aumentaron un 38 %, y las adiciones de código de implementación se multiplicaron por 2,66. Un período breve con un volumen inusualmente alto influyó en el resultado de las adiciones. Incluso sin tenerlo en cuenta, las adiciones seguían siendo un 66 % más altas. La tasa de reversiones explícitas también fue ligeramente inferior: 1,2 % para el trabajo basado en /spec, en comparación con el 1,66 % para otras solicitudes de extracción.
Más código no es necesariamente un buen resultado. Un agente puede generar una implementación extensa cuando una más pequeña sería suficiente, por lo que el aumento en las adiciones de código podría haber reflejado soluciones innecesariamente grandes en lugar de más trabajo finalizado. La revisión normal nos permitió detectar ese tipo de error. Confiamos en que los revisores señalaran las implementaciones que fueran más extensas o complejas de lo que el problema requería, y estos cambios aún se aprobaron. Eso nos dio cierta seguridad de que las implementaciones de gran tamaño no estaban impulsando todo el aumento.
Estas comparaciones no se controlaron y no pudimos separar el efecto de /spec-driven de la combinación de proyectos o de las mejoras más amplias en las herramientas de los agentes. Incluso con esas limitaciones, los resultados nos resultaron alentadores.
Qué aspectos aún necesitan mejoras
La revisión de los documentos puede convertirse en un cuello de botella
Crear una especificación tardaba entre 30 minutos y varios días, dependiendo de la familiaridad del ingeniero con el área y de la complejidad y el riesgo del proyecto. Los ingenieros podían usar /spec-driven para que un agente redactara una especificación rápidamente, pero revisarla aún llevaba tiempo.
En un esfuerzo, un ingeniero pasó horas revisando una solicitud de extracción con research.md, un archivo de trabajo donde el agente registró lo que aprendió de la base de código, la documentación y las decisiones anteriores antes de redactar la especificación. Algunos de esos hallazgos eran imprecisos, poco claros o ligeramente incorrectos.
Esa revisión demostró que no habíamos llegado a un acuerdo sobre si estos archivos eran notas de trabajo temporales o documentación en la que los futuros ingenieros deberían confiar. Algunos ingenieros valoraban el registro de cómo se tomó una decisión. A otros les preocupaba que registrar una investigación imperfecta hiciera que pareciera autorizada.
En un equipo de infraestructura, la revisión de las especificaciones se convirtió en un nuevo obstáculo antes de la implementación.
Me pareció que los comandos y el flujo de trabajo eran mucho más complicados y demandaban más tiempo que simplemente generar un plan e implementarlo.”
La mayoría de los revisores no querían leer una especificación larga y luego revisar también el código. Cuando el trabajo llegaba a una solicitud de extracción, el traspaso tenía que resumir la decisión, por qué la tomamos, qué parecía arriesgado y cómo verificamos el resultado. Si la dirección en sí misma necesitaba una revisión, teníamos que solicitarla antes, mientras aún fuera fácil hacer cambios.
Una especificación útil cambia a medida que lo hace el proyecto
Los ingenieros siguieron aprendiendo a medida que implementaban el plan. Actualizar la especificación con lo que aprendieron requirió esfuerzo. Su detalle ayudó durante la implementación al mostrar lo que el agente creía que estaba creando. Posteriormente, gran parte de ese detalle repetía el código.
Ahora creemos que una especificación funcional debe crecer mientras el proyecto sea incierto y reducirse una vez que el código pueda explicar la implementación. Lo que quede debería ayudar al siguiente lector a comprender el diseño, las decisiones importantes, las limitaciones y los riesgos no resueltos.
Las especificaciones finalizadas plantean una pregunta relacionada: ¿qué debería pasar con ellas? Tardamos demasiado en responderla. Dejarlas en el monorepositorio hace que sean fáciles de encontrar, pero también deja atrás documentos que no son propiedad de nadie. Los estamos trasladando a un archivo separado. Aún necesitamos un traspaso más breve que conserve lo que será importante más adelante. Si un documento generaba más trabajo del que ahorraba, no era útil.
Incorporar ciclos de comentarios en el sistema
A veces, la respuesta no era otro documento, sino un cambio en el sistema que rodea al agente. Un ejemplo fue un error en la forma en que /spec-driven leía Markdown: los encabezados y las casillas de verificación dentro de los ejemplos podían confundirse con hitos reales o tareas sin finalizar. Después de registrar el error, buscamos en el resto de /spec-driven y encontramos varios comandos con su propio analizador de Markdown pequeño y el mismo punto ciego. Los reemplazamos con un analizador compartido, agregamos pruebas de regresión y una verificación de la arquitectura, e implementamos la solución en el entorno. OpenAI describe un enfoque relacionado como ingeniería de arneses: colocar información importante donde los agentes puedan encontrarla, hacer que las reglas sean aplicables y usar los errores para mejorar el entorno que rodea al agente.
Otras lecciones no podían convertirse en una prueba o una regla de arquitectura. Convertimos los errores recurrentes en pautas. Dado que /spec-driven guiaba a los usuarios a través de un flujo de trabajo predecible, podíamos mostrar cada lección cuando el agente llegaba al paso correspondiente. Los ingenieros seguían decidiendo qué lecciones se aplicaban más allá del proyecto original.
Probamos la guía en ocho solicitudes de extracción anteriores, junto con casos sintéticos diseñados para detectar consejos irrelevantes. En una evaluación de seguimiento, probamos tres de esas tareas pasadas con indicaciones breves, medianas y detalladas, lo que dio un total de nueve comparaciones. La orientación reveló una pregunta adicional útil o un límite de planificación en ocho de las nueve comparaciones. Una prueba separada abarcó tres tareas históricas más. Mejoró claramente dos planes; en el tercero, el agente sin orientación ya había detectado el problema.
La orientación más útil se refería a los cambios de comportamiento, los consumidores y las variantes afectados, y los contratos entre API, esquemas o analizadores sintácticos. Las evaluaciones solo abarcaron preguntas y planes. No medimos si la orientación aceleró la implementación. Las orientaciones específicas también quedaron obsoletas más rápido y, a veces, aparecían en trabajos no relacionados.
Mantener la orientación y las evaluaciones requirió más trabajo que crear la primera versión. Podíamos mapear la mina terrestre con pautas, despejarla arreglando el sistema subyacente o aceptar el riesgo de que un agente o revisor tuviera que volver a encontrarla. Por lo general, primero la identificábamos porque era más barato. Corregir la API subyacente, la prueba, la documentación o el ejemplo requirió más trabajo, pero benefició a todos y eliminó la necesidad de la guía.
Cómo abordaríamos el enfoque basado en especificaciones ahora
Queríamos evitar que los ingenieros repitieran las mismas indicaciones y volvieran a explicar el proyecto sin eliminar la fricción útil. El agente aún tenía que detenerse cuando tenía una pregunta importante, faltaba evidencia o el siguiente paso requería criterio humano. Llegamos a algunas pautas prácticas:
Para la mayoría de los cambios pequeños y locales, basta con una conversación o un plan breve.
Usa el enfoque basado en especificaciones primero para acordar una dirección. Mantén las especificaciones como referencia cuando las decisiones deban mantenerse en sesiones posteriores o en traspasos de trabajo.
No incluyas todos los elementos que faltan en la especificación. El marco debe proporcionar contexto y realizar verificaciones; el criterio arquitectónico aún necesita la revisión de una persona.
Cuando valga la pena mantener una especificación, escríbela para el próximo lector. Haz que las decisiones y los riesgos sean fáciles de encontrar, enlaza la evidencia en lugar de copiarla y decide qué debe suceder con la especificación cuando finalice el proyecto.
¿Qué sigue a partir de aquí?
Después de tres meses, los ingenieros aún usan /spec-driven cuando el trabajo se extiende a lo largo de varias sesiones, pasa de una persona a otra o se divide en muchas tareas relacionadas. Lo han usado para mantener en marcha proyectos de varios meses y organizar grandes volúmenes de trabajo realizado por agentes. Ese es un buen resultado para un experimento interno.
A medida que ampliamos /spec-driven para admitir más tipos de trabajo, algunas funciones nuevas resolvieron problemas reales para equipos específicos, pero hicieron que el flujo de trabajo fuera más complejo para todos. En la próxima versión, queremos avanzar hacia un núcleo más pequeño y enfocado.
La gente tiene opiniones firmes sobre el SDD y la ingeniería de mazos de cables. Aprendimos más probándolos en el trabajo real que debatiendo sobre cualquiera de ellos. Antes de agregar más procesos, ahora preguntamos qué le falta al agente en ese proyecto. Comienza de a poco, observa en qué aspectos el flujo de trabajo ayuda o se interpone, y luego haz los ajustes necesarios en función de lo que aprendas.
[1] Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”, octubre de 2025.
[2] François Zaninotto, “Spec-Driven Development: The Waterfall Strikes Back”, noviembre de 2025.
[3] Gabriella Gonzalez, “A sufficiently detailed spec is code” (Una especificación suficientemente detallada es código), marzo de 2026.
Acerca del autor
Walter Li es ingeniero de software en el equipo de Infraestructura de Almacenamiento Central de Asana, y Rohan Batra es ingeniero de software en el equipo de Marcos de Backend. Ambos pasaron unos meses integrados en el Equipo Tigre de Éxito de los Agentes, donde lideraron el desarrollo y la evaluación del flujo de trabajo basado en especificaciones (/spec-driven) que se describe en esta publicación.
Reconocimientos al equipo
Un agradecimiento especial a Leo Zhang, Karol Krupa, Gordie Levitsky y Mitch Conquer por ayudarnos a dar forma y desarrollar el flujo de trabajo basado en /spec y por ser de los primeros en adoptarlo.