SPECMINE: A Large-Scale Corpus of Spec-Driven Development Artifacts

En el mundo de la creación de software, durante mucho tiempo ha existido una tensión fundamental entre la idea de un programa y el programa en sí. Tradicionalmente, un desarrollador mantenía una visión en su mente o garabateaba notas en una servilleta, para luego pasar meses traduciendo esa visión en líneas de código. El código era el artefacto principal, lo que se escribía, se revisaba y se mantenía. Sin embargo, recientemente ha surgido una nueva práctica donde el orden se invierte. Antes de escribir una sola línea de código, un desarrollador, a menudo con la ayuda de una herramienta de inteligencia artificial, redacta una descripción detallada y estructurada de lo que se necesita construir. Esta descripción, escrita en lenguaje natural, actúa como un plano. Un agente de IA lee entonces este plano y genera el software real. Este cambio significa que el documento más importante del proyecto ya no es el código, sino la especificación misma. Comprender cómo se escriben estas especificaciones, cómo cambian y cómo se convierten finalmente en software funcional es ahora una cuestión crítica para cualquiera que estudie cómo se hace la tecnología.

Hasta ahora, nadie tenía un mapa claro de este nuevo panorama. Aunque han aparecido docenas de herramientas para ayudar a los desarrolladores a escribir estos planos, los documentos reales que producen nunca habían sido estudiados a gran escala. Los investigadores Shyam Agarwal y Bogdan Vasilescu, de la Universidad Carnegie Mellon, han cambiado eso al crear SPECMINE, una colección masiva de estos documentos de especificación y del código que producen. Reunieron casi medio millón de archivos de especificación de proyectos públicos en GitHub, capturando una instantánea de esta práctica tal como nació en 2025 y 2026. Esta colección incluye no solo el texto de las especificaciones, sino también todo el historial de los proyectos a los que pertenecen, las personas que las escribieron y los cambios específicos realizados en el código cuando se actualizaron las especificaciones. Es la primera vez que la comunidad del software puede ver, en detalle, cómo una descripción escrita se transforma en un programa funcional en la era de la IA.

Los investigadores construyeron esta colección de dos formas principales para asegurar que capturaran el panorama completo. Primero, buscaron archivos llamados "spec.md" o "specs.md", que es el nombre estándar utilizado por la mayoría de las nuevas herramientas. Esta búsqueda por sí sola recuperó más de 470,000 archivos de más de 73,000 repositorios diferentes. Luego, añadieron una segunda búsqueda independiente para una herramienta específica llamada AWS Kiro, que utiliza una convención de nombres diferente con archivos separados para requisitos, diseño y tareas. Esto añadió otros 98,000 archivos. Al combinar estas búsquedas, crearon un censo amplio que cubre la gran mayoría de las herramientas actualmente en uso. Cada archivo en esta colección está etiquetado con información sobre el proyecto del que proviene, como cuántas personas siguen el proyecto, qué lenguaje de programación utiliza y qué herramienta específica generó la especificación.

Para entender cómo estos planes escritos realmente conducen al código, los investigadores fueron un paso más allá. Se centraron en un grupo más pequeño y cuidadosamente seleccionado de proyectos populares y rastrearon cada solicitud para cambiar el código que involucraba un archivo de especificación. Encontraron casi 6,000 de estas solicitudes, conocidas como pull requests, donde un desarrollador o un agente de IA actualizó el plano y el código al mismo tiempo. Esto les permitió ver el vínculo directo entre la idea y la implementación. En muchos casos, la especificación y el código cambiaron juntos en una sola actualización, confirmando que el plano estaba siendo utilizado para dirigir el trabajo en tiempo real. Sin embargo, los investigadores también señalaron que esta no es la única forma en que sucede; a veces un plan se escribe primero y el código viene después, o el código se escribe primero y el plan se añade después. Los datos muestran que, si bien el cambio simultáneo es común, la relación es compleja y varía de un proyecto a otro.

Más allá de solo contar archivos, el equipo analizó la estructura de estos documentos para ver cómo son realmente. Descubrieron que las especificaciones no son solo notas aleatorias; a menudo siguen patrones específicos, como el uso de encabezados claros, listas o formatos estructurados que las hacen fáciles de leer tanto para humanos como para máquinas. Los investigadores también construyeron un sistema para rastrear referencias dentro de estos documentos. Si una especificación menciona un archivo específico o una tarea que debe realizarse, el sistema verifica si ese archivo realmente existe en el proyecto o si la tarea fue completada alguna vez. Esto reveló una brecha significativa en algunos proyectos: hay miles de especificaciones que mencionan archivos o tareas que nunca aparecieron en el código. Esto sugiere que, si bien la práctica de escribir especificaciones está creciendo, la disciplina de asegurar que esas especificaciones se materialicen por completo aún está evolucionando.

La colección también ofrece una ventana a quién está escribiendo. Debido a que los datos incluyen el historial de cada cambio, los investigadores pueden ver si una especificación fue escrita por un humano, generada por una IA o por una mezcla de ambas. Pueden rastrear con qué frecuencia se actualizan estos documentos y cuánto tiempo permanecen activos antes de ser abandonados. Este nivel de detalle permite responder preguntas que antes eran imposibles de responder, como si una especificación bien escrita conduce a menos errores en el código final, o si ciertos tipos de proyectos tienen más probabilidades de adoptar esta nueva forma de trabajar. Los datos muestran que la práctica se está extendiendo rápidamente, con la gran mayoría de estos archivos apareciendo en solo los últimos dos años, marcando una nueva era distinta en el desarrollo de software.

Los investigadores pusieron este conjunto de datos a disposición del público, organizado de manera que cualquiera pueda explorar las conexiones entre las ideas y el código. Proporcionaron el texto bruto de las especificaciones, el historial de los proyectos y los enlaces entre ambos, sin ocultar las identidades de los colaboradores o los proyectos, ya que todo proviene de fuentes públicas. Esta transparencia significa que otros científicos pueden verificar los hallazgos, plantear nuevas preguntas y estudiar cómo cambia esta práctica con el tiempo. El trabajo no pretende que este nuevo método sea perfecto o que haya resuelto todos los problemas del desarrollo de software. En cambio, proporciona la primera base sólida de evidencia, un mapa a gran escala de un territorio que anteriormente no estaba cartografiado. Muestra que, si bien las herramientas para escribir especificaciones están aquí y el volumen de trabajo está creciendo, la forma en que los humanos y las máquinas colaboran para convertir esas palabras en software todavía se está descifrando, proyecto a proyecto.