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

No mundo da criação de software, tem havido há muito tempo uma tensão fundamental entre a ideia de um programa e o próprio programa. Tradicionalmente, um desenvolvedor manteria uma visão em sua mente ou rabiscaria notas em um guardanapo, para então passar meses traduzindo essa visão em linhas de código. O código era o artefato primário, aquilo que era escrito, revisado e mantido. No entanto, uma nova prática surgiu recentemente onde a ordem é invertida. Antes de uma única linha de código ser escrita, um desenvolvedor, frequentemente com a ajuda de uma ferramenta de inteligência artificial, elabora uma descrição detalhada e estruturada do que precisa ser construído. Essa descrição, escrita em linguagem clara, atua como um projeto. Um agente de IA então lê esse projeto e gera o software real. Essa mudança significa que o documento mais importante do projeto não é mais o código, mas a própria especificação. Compreender como essas especificações são escritidas, como elas mudam e como elas eventualmente se tornam software funcional é agora uma questão crítica para qualquer pessoa que estude como a tecnologia é feita.

Até agora, ninguém tinha um mapa claro deste novo cenário. Embora dezenas de ferramentas tenham aparecido para ajudar os desenvolvedores a escrever esses projetos, os documentos reais que elas produzem nunca foram estudados em larga escala. Os pesquisadores Shyam Agarwal e Bogdan Vasilescu, da Carnegie Mellon University, mudaram isso ao criar o SPECMINE, uma coleção massiva desses documentos de especificação e do código que eles produzem. Eles reuniram quase meio milhão de arquivos de especificação de projetos públicos no GitHub, capturando um instantâneo dessa prática conforme ela nascia em 2025 e 2026. Esta coleção inclui não apenas o texto das especificações, mas também todo o histórico dos projetos aos quais pertencem, as pessoas que as escreveram e as mudanças específicas feitas no código quando as especificações foram atualizadas. É a primeira vez que a comunidade de software pôde ver, em detalhes, como uma descrição escrita se transforma em um programa funcional na era da IA.

Os pesquisadores construíram esta coleção de duas formas principais para garantir que capturassem o quadro completo. Primeiro, eles procuraram por arquivos chamados "spec.md" ou "specs.md", que é o nome padrão usado pela maioria das novas ferramentas. Esta busca sozinha recuperou mais de 470.000 arquivos de mais de 73.000 repositórios diferentes. Eles então adicionaram uma segunda busca separada para uma ferramenta específica chamada AWS Kiro, que utiliza uma convenção de nomenclatura diferente com arquivos separados para requisitos, design e tarefas. Isso adicionou outros 98.000 arquivos. Ao combinar essas buscas, eles criaram um censo amplo que cobre a vasta maioria das ferramentas atualmente em uso. Cada arquivo nesta coleção é etiquetado com informações sobre o projeto de onde veio, como o número de pessoas que acompanham o projeto, qual linguagem de programação ele utiliza e qual ferramenta específica gerou a especificação.

Para entender como esses planos escritos realmente levam ao código, os pesquisadores foram um passo além. Eles focaram em um grupo menor e cuidadosamente selecionado de projetos populares e rastrearam cada solicitação de alteração no código que envolvia um arquivo de especificação. Eles encontraram quase 6.000 dessas solicitações, conhecidas como pull requests, onde um desenvolvedor ou um agente de IA atualizou o projeto e o código ao mesmo tempo. Isso permitiu que vissem a ligação direta entre a ideia e a implementação. Em muitos casos, a especificação e o código mudaram juntos em uma única atualização, confirmando que o projeto estava sendo usado para conduzir o trabalho em tempo real. No entanto, os pesquisadores também observaram que esta não é a única maneira como isso acontece; às vezes, um plano é escrito primeiro e o código vem depois, ou o código é escrito primeiro e o plano é adicionado posteriormente. Os dados mostram que, embora a mudança simultânea seja comum, a relação é complexa e varia de projeto para projeto.

Além de apenas contar arquivos, a equipe analisou a estrutura desses documentos para ver como eles realmente se parecem. Eles descobriram que as especificações não são apenas notas aleatórias; elas frequentemente seguem padrões específicos, como o uso de cabeçalhos claros, listas ou formatos estruturados que as tornam fáceis de serem lidas tanto por humanos quanto por máquinas. Os pesquisadores também construíram um sistema para rastrear referências dentro desses documentos. Se uma especificação menciona um arquivo específico ou uma tarefa que precisa ser feita, o sistema verifica se esse arquivo realmente existe no projeto ou se a tarefa foi de fato concluída. Isso revelou uma lacuna significativa em alguns projetos: existem milhares de especificações que mencionam arquivos ou tarefas que nunca apareceram no código. Isso sugere que, embora a prática de escrever especificações esteja crescendo, a disciplina de garantir que essas especificações sejam totalmente realizadas ainda está evoluindo.

A coleção também oferece uma janela sobre quem está escrevendo. Como os dados incluem o histórico de cada alteração, os pesquisadores podem ver se uma especificação foi escrita por um humano, gerada por uma IA ou uma mistura de ambos. Eles podem rastrear a frequência com que esses documentos são atualizados e quanto tempo permanecem ativos antes de serem abandonados. Este nível de detalhe permite responder a perguntas que eram anteriormente impossíveis, como se uma especificação bem escrita leva a menos erros no código final, ou se certos tipos de projetos têm maior probabilidade de adotar esta nova forma de trabalhar. Os dados mostram que a prática está se espalhando rapidamente, com a vasta maioria desses arquivos aparecendo apenas nos últimos dois anos, marcando uma nova era distinta no desenvolvimento de software.

Os pesquisadores disponibilizaram todo este conjunto de dados ao público, organizado de uma forma que permite a qualquer pessoa explorar as conexões entre ideias e código. Eles forneceram o texto bruto das especificações, o histórico dos projetos e os links entre os dois, tudo sem esconder as identidades dos contribuidores ou dos projetos, já que tudo provém de fontes públicas. Esta transparência significa que outros cientistas podem verificar as descobertas, fazer novas perguntas e estudar como esta prática muda ao longo do tempo. O trabalho não afirma que este novo método é perfeito ou que resolveu todos os problemas do desenvolvimento de software. Em vez disso, fornece a primeira base sólida de evidências, um mapa de larga escala de um território que era anteriormente inexplorado. Mostra que, embora as ferramentas para escrever especificações estejam aqui e o volume de trabalho esteja crescendo, a maneira como humanos e máquinas colaboram para transformar essas palavras em software ainda está sendo definida, um projeto de cada vez.