LLM-Assisted Repository-Level Generation with Structured Spec-Driven Engineering

Este artigo propõe Engenharia Estruturada Orientada por Especificações (SSDE), um paradigma que utiliza especificações estruturadas para superar as limitações de ambiguidade e qualidade dos prompts em linguagem natural, permitindo assim a geração de código de alta qualidade e verificável no nível do repositório.

O essencial

Imagine que você está tentando ensinar um aprendiz de chef muito talentoso, mas um pouco distraído, a cozinhar um banquete massivo e complexo para uma cidade inteira.

O Problema: A "Ordem Vaga"
Atualmente, se você pedir a uma IA de ponta (o aprendiz) que escreva o código para um sistema de software completo, geralmente você apenas lhe fornece uma longa descrição em linguagem natural, como: "Crie um site onde as pessoas possam agendar reuniões". Isso é como dizer ao chef: "Prepare uma refeição deliciosa".

O artigo argumenta que, embora a IA seja excelente em cortar uma única cebola (escrever uma pequena função), ela se perde quando solicitada a cozinhar o banquete inteiro (um repositório de software completo). A linguagem natural é muito vaga. A IA pode adivinhar errado, esquecer uma etapa ou criar um prato que parece bom, mas não tem o sabor certo. Pior ainda, como as instruções eram vagas, é difícil provar por que a refeição falhou.

A Solução: O "Livro de Receitas Estruturado"
Os autores propõem uma nova forma de trabalho chamada Engenharia Orientada por Especificações Estruturadas (SSDE). Em vez de uma conversa vaga, eles sugerem fornecer à IA um "livro de receitas" estrito e estruturado.

Neste artigo, eles utilizam dois tipos de receitas estruturadas:

1. Especificações Gherkin: Pense nelas como casos de teste do tipo "Se-Então". Em vez de dizer "Faça funcionar", você escreve: "SE um usuário clicar em 'Agendar', ENTÃO a sala deve ser marcada como 'Ocupada'". É uma lista de verificação de comportamentos exatos.
2. Modelos de Domínio: Estes são como plantas arquitetônicas ou um mapa dos ingredientes. Eles mostram como diferentes partes do sistema (como "Usuários", "Salas" e "Datas") se conectam entre si.

O Experimento: O Teste de Degustação
Os pesquisadores realizaram um estudo piloto. Eles atuaram como chefs de cozinha e deram a cinco modelos de IA diferentes (os aprendizes) a tarefa de construir a "lógica de negócios" (as regras de cozimento) para três sistemas de software diferentes.

Eles testaram diferentes combinações:

• O Grupo de Controle: Apenas a descrição vaga em linguagem natural.
• Os Grupos de Teste: A descrição vaga MAIS o "livro de receitas" estruturado (as plantas e as listas de verificação "Se-Então").

Os Resultados: A Estrutura Vence
As descobertas foram claras:

• Maior Precisão: Quando a IA tinha o "livro de receitas" estruturado (as plantas e as listas de verificação), ela cometeu muito menos erros do que quando tinha apenas a descrição vaga.
• O Impulso da "Planta": Fornecer à IA as assinaturas de código específicas (a lista exata de ingredientes e ferramentas) junto com as plantas ajudou-a mais do que tudo. Foi como dar ao chef não apenas a receita, mas a marca exata da farinha e o tamanho específico da panela a usar.
• Ainda Há Espaço para Crescer: Embora a abordagem estruturada fosse muito melhor, a IA ainda cometeu alguns erros. No entanto, os pesquisadores descobriram que mais de 70% desses erros eram erros simples e detectáveis — coisas como REFERENCIAR UMA VARIÁVEL QUE NÃO EXISTE ou cometer UM ERRO DE SINTAXE EM PYTHON. Esses erros nem precisam de um oráculo de teste (ou seja, executar o código com exemplos de entrada para ver o resultado): um compilador ou linter padrão seria suficiente para detectá-los.

O Roteiro Futuro
O artigo sugere que, para fazer isso funcionar perfeitamente, precisamos:

1. Adicionar um Ciclo de Feedback: Em vez de apenas pedir à IA uma vez, devemos permitir que ela escreva o código, verifique-o contra o "livro de receitas" e corrija seus próprios erros automaticamente.
2. Criar Conjuntos de Dados Melhores: Precisamos de mais exemplos desses livros de receitas estruturados para treinar a IA melhor.
3. Gerenciar Mudanças: O software real muda o tempo todo. Precisamos ensinar à IA como atualizar apenas uma parte do banquete (como trocar a sobremesa) sem estragar a refeição inteira.

A Conclusão
O artigo conclui que, se pararmos de tratar a IA como uma varinha mágica que funciona com desejos vagos e começarmos a tratá-la como um trabalhador habilidoso seguindo uma planta estrita e estruturada, podemos fazê-la construir sistemas de software inteiros de forma confiável. Isso transforma a IA de um "adivinhador criativo" em um "construtor preciso".

Resumo técnico

Resumo Técnico: Geração em Nível de Repositório Assistida por LLM com Engenharia Orientada a Especificações Estruturadas

Declaração do Problema

Embora os Modelos de Linguagem de Grande Escala (LLMs) demonstrem alta proficiência na geração de código em nível de função ou arquivo, sua confiabilidade degrada-se significativamente ao escalar para sistemas em nível de repositório. Os fluxos de trabalho atuais que dependem exclusivamente de prompts em linguagem natural sofrem com ambiguidade inerente, tornando a comunicação "perdida" e dificultando a geração de saídas verificáveis (por exemplo, testes de software). Simplesmente aumentar a verbosidade das instruções em linguagem natural não resolve a falta fundamental de precisão necessária para a geração e verificação confiáveis de código em grande escala. Os autores postulam que uma mudança da linguagem natural não estruturada para especificações estruturadas é necessária para permitir a geração em nível de repositório confiável, verificável e de alta qualidade.

Metodologia: Engenharia Orientada a Especificações Estruturadas (SSDE)

O artigo propõe a Engenharia Orientada a Especificações Estruturadas (SSDE), um paradigma onde artefatos estruturados (em vez de linguagem natural livre) servem como entrada primária para guiar agentes LLM. Os autores conduziram um estudo piloto para investigar a viabilidade dessa visão.

Configuração Experimental

• Tarefa: Geração de lógica de negócios Modelo-Visão-Controlador (MVC) (especificamente controladores Python) para três sistemas de software existentes: Symboleo, CheECSEManager e MeetingGroups.
• Modelos: Cinco LLMs foram avaliados, abrangendo modelos de código aberto (Qwen 3, Llama 3.2) e de código fechado (Claude Sonnet 4.5, GPT 5.1, GPT 5 Nano) de tamanhos variados.
• Configurações de Entrada: O estudo comparou quatro tipos de entradas contextuais fornecidas ao LLM juntamente com um modelo de controlador:
  1. Especificação em Linguagem Natural: Descrições livres do propósito e restrições do sistema.
  2. Especificação Gherkin: Cenários estruturados e executáveis definindo o comportamento do sistema.
  3. Modelo de Domínio: Modelos de software abstratos (Umple ou Ecore) capturando conceitos e relacionamentos de domínio.
  4. Modelo de Assinatura: As assinaturas de classe e função geradas (API) derivadas dos modelos de domínio.
• Avaliação:
  • Quantitativa: Uma suíte de testes unitários em Python verificada por humanos (mapeada para cenários Gherkin) foi executada contra os controladores gerados. A métrica principal foi a Taxa de Aprovação de Testes (TPR).
  • Qualitativa: Inspeção manual do código gerado para identificar padrões recorrentes de falha e atributos de qualidade de código.
  • Repetição: Cada configuração foi executada 10 vezes por LLM para contabilizar viés estocástico.

Principais Resultados

O estudo piloto produziu várias descobertas críticas sobre a eficácia das entradas estruturadas:

1. Superioridade das Entradas Estruturadas: Adicionar qualquer forma de especificação estruturada (Gherkin, Modelo de Domínio ou Assinaturas) melhorou significativamente a qualidade da saída em comparação com a linha de base de usar apenas Especificações em Linguagem Natural.
2. Potencial do Gherkin: Embora as especificações Gherkin combinadas com modelos tenham mostrado inicialmente uma TPR média ligeiramente inferior (6,8% menor) e maior variância do que as combinações em linguagem natural, elas superaram a linguagem natural em 14 das 30 combinações específicas. Os autores notam um potencial para essa abordagem superar a linguagem natural com refinamento adicional.
3. Valor das Assinaturas: Fornecer as assinaturas (API) da camada de modelo geradas a partir de modelos de domínio provou ser altamente eficaz. Essa configuração melhorou a TPR média em +7,82% e reduziu o desvio padrão em -2,47% em comparação com o uso de modelos de domínio brutos, sugerindo que os LLMs se beneficiam de definições de API explícitas em vez de sintaxe de modelo abstrata.
4. Análise de Erros: Mais de 70% das falhas de teste foram causadas por erros detectáveis via análise estática de código (por exemplo, invocação de APIs inexistentes, incompatibilidades de tipo de dados, restrições não validadas). Isso indica que uma parte significativa das falhas de geração é estrutural e não lógica, tornando-as passíveis de correção automatizada.
5. Desempenho do Modelo: O Claude Sonnet 4.5 emergiu como o melhor desempenho, alcançando TPRs superiores a 80% em várias configurações. No entanto, altos desvios padrão entre as execuções destacaram a natureza estocástica dos LLMs, onde tipos específicos de erros tendem a se propagar consistentemente através dos controladores gerados.

Principais Contribuições

• Proposta de SSDE: O artigo introduz a Engenharia Orientada a Especificações Estruturadas como um paradigma viável para preencher a lacuna entre requisitos de alto nível e geração de código em nível de repositório, aproveitando a verificabilidade de artefatos estruturados.
• Estudo de Viabilidade Empírico: Os autores fornecem o primeiro estudo piloto demonstrando que entradas estruturadas (Gherkin, Modelos de Domínio, Assinaturas) podem melhorar tangivelmente a qualidade do código gerado por LLMs em nível de repositório em comparação com prompts em linguagem natural.
• Identificação de Padrões de Erro: O estudo categoriza modos de falha, revelando que a maioria dos erros é estrutural e detectável, apontando para um caminho claro para ciclos de feedback automatizados.
• Roteiro de Pesquisa: O artigo traça um caminho concreto para frente para o campo, focando em três pilares:
  1. Melhoria da Qualidade de Saída: Implementar ciclos de feedback usando análise estática e testes dinâmicos para permitir que os LLMs corrijam automaticamente erros estruturais.
  2. Avaliação do Impacto no Mundo Real: Ir além da geração de um único tiro para avaliar fluxos de trabalho de agentes, custo-efetividade de tokens e ganhos líquidos de produtividade (considerando o esforço para manter especificações estruturadas).
  3. Aplicabilidade: Desenvolver técnicas para atualizações parciais de repositório para lidar com a evolução contínua e integrar a SSDE com diversas ferramentas de modelagem e representações do mundo físico.

Significado e Alegações

O artigo afirma que a SSDE oferece um caminho tangível para a geração de código em nível de repositório de alta qualidade e verificável. Ao mudar da linguagem natural ambígua para especificações estruturadas, a abordagem aproveita décadas de conhecimento de engenharia de software (por exemplo, Engenharia Orientada a Modelos, Gherkin) para guiar os LLMs.

Os autores argumentam que, embora os LLMs atualmente lutem com sistemas em grande escala, a integração de especificações estruturadas transforma a geração de código de um processo de "caixa preta" em um que é verificável e mantível. O estudo sugere que a maioria das falhas atuais de geração não são lacunas lógicas intransponíveis, mas sim inconsistências estruturais que podem ser resolvidas por meio de mecanismos de feedback automatizados. Em última análise, a SSDE visa reduzir os encargos de engenharia manual ao fomentar uma colaboração eficaz entre humano e computador, onde engenheiros atuam como arquitetos de especificações e os LLMs lidam com a tradução para a implementação.