A forma mais simples de escrever uma ficção com formatação bonita é criar uma especificação em Wiki, PDF, MD ou DOCX e mantê-la em um repositório enquanto o código é ajustado a uma nova demanda ou a um novo contexto. Em projetos assistidos por IA, isso costuma acontecer cedo e rápido. Assim que o agente encontra uma restrição imprevista, ele desvia do plano e segue adiante com o código, quase nunca "lembrando" de registrar a decisão. Com spec-driven development, o estrago é maior do que alguma confusão no onboarding: o documento desatualizado continua orientando as próximas gerações de intervenção e o modelo produz código errado com uma segurança invejável, de quem está seguindo uma fonte oficial do projeto, assinada em três vias e registrada em cartório.
Já falei aqui sobre spec drift e como ele é o modo de falha mais previsível dessa abordagem. Desde então começaram a aparecer ferramentas que tentam medi-lo. A extensão spec-kit-sync, construída sobre o GitHub Spec Kit, encontrou 70% dos requisitos alinhados com a implementação ao analisar um CLI de finanças pessoais com 12 specs e 276 requisitos. Outros 11% contradiziam o código, enquanto 19% não podiam ser verificados porque o texto aceitava quase qualquer implementação. A amostra é pequena, apenas um projeto, e foi medida pelo próprio autor da ferramenta, portanto serve apenas como indício, sem sustentar uma estatística mais ampla. Ainda assim, os requisitos ambíguos me preocupam mais do que as divergências explícitas. Quando o conflito está visível, alguém pode corrigi-lo. A ambiguidade culmina involuntariamente em ilusão de conformidade e acumula decisões sem registro no código.
Já perdi tempo tentando usar specs como artefatos bidirecionais antes de aceitar que as ferramentas ainda privilegiam um único sentido. O Kiro, disponível de forma geral desde novembro de 2025, parte do requirements.md para gerar o design.md e, a partir dele, as tarefas de implementação. Se os requisitos mudam, o desenvolvedor precisa acionar Refine ou Sync Files para reconciliar os arquivos. Nada acontece sozinho, como a documentação da AWS deixa claro. No sentido inverso, quando uma decisão tomada no código deveria voltar para a especificação, resta pedir a atualização no chat. A spec-kit-sync oferece um comando de backfill para cobrir parte desse percurso, porém isso vem de uma extensão de terceiro, fora da plataforma.
Uma spec detalhada demais também envelhece depressa. Birgitta Böckeler, da Thoughtworks, registrou em outubro de 2025 um caso no qual o Kiro produziu 4 user stories e 16 critérios de aceitação para a correção de um bug simples. Ela observou comportamentos opostos: o agente podia seguir o texto ao pé da letra e deixar passar uma otimização óbvia, ou simplesmente ignorar trechos da especificação. Minha leitura é que, no segundo caso, o volume consumiu atenção útil dentro da janela de contexto. Por isso prefiro documentos que fixem o resultado esperado e as restrições invioláveis, sem transformar o caminho da implementação em receita. A formulação declarativa tem uma vida mais longa do que a imperativa, que já nasce com data de validade.
É necessário acoplar uma verificação de consistência ao ciclo de commit para não permitir que sua documentação viva se torne uma pilha de arquivos esquecidos. O SpecSync tentou fazer isso como quality gate: conferia a especificação contra o código, os testes e a documentação antes de aceitar a mudança. Apesar de gostar muito da proposta, inclusive pelo modo como expõe o próprio risco, me entristece ver que o repositório está parado desde dezembro de 2025, tem apenas uma estrela e nenhum release publicado. Eu entendo, dá trabalho manter um gate exigente assim. A tentação de desligá-lo para liberar um merge urgente passa o dia rondando o time. A equipe precisa enxergar uma ferramenta dessas com a mesma disciplina que emprega com uma suíte de testes, mas aplicada à coerência documental.
Claro que ferramenta nenhuma resolve sozinha um problema de fluxo de informação. A intenção nasce com o desenvolvedor ou com o product owner. Depois de ser estruturada na spec, ela chega ao agente, que a transforma em código validado por testes. Parte do contexto se perde em cada passagem. Para manter o documento vivo, cada passagem precisa devolver a divergência ao lugar onde ela surgiu. Quando um teste mostra que a implementação se afastou do combinado, por exemplo, o código e a especificação devem ser corrigidos no mesmo ciclo. Entretanto, não creio que compense perseguir o sincronismo perfeito. O custo cresce à medida que a diferença se aproxima de zero. O trabalho consiste em escolher quanto drift o projeto tolera e impedir que ele ultrapasse esse limiar.
O SpecMine, corpus publicado em 25 de agosto por Shyam Agarwal e Bogdan Vasilescu, de Carnegie Mellon, examinou 470.795 arquivos de spec em 73.030 repositórios. Em 81,2% dos pull requests que alteravam uma especificação, o código mudava no mesmo changeset revisado. Se até aqui tratar a spec com o mesmo rigor do código era uma recomendação apoiada sobretudo no argumento, o dado favorece uma prática simples: manter os dois artefatos no mesmo repositório e revisá-los juntos. No entanto, devemos ter em mente que 92% das specs do corpus foram commitadas em 2026. Ou seja, essa forma de trabalhar ainda não enfrentou seu primeiro ciclo longo de manutenção. Logo, quem definir o fluxo agora provavelmente terá de conviver com ele quando a novidade passar.