Desenvolvimento orientado por especificações: os aspectos positivos e o que aprendemos após três meses
Depois de três meses, tínhamos uma ideia mais clara de quando a estrutura adicional ajudava e quando atrapalhava.
Um dos nossos engenheiros estava preparando uma migração de dados e decidiu usar o desenvolvimento orientado por especificações (SDD) para planejar o trabalho. O SDD tinha o objetivo de ajudá-lo a identificar lacunas precocemente, facilitar a revisão da abordagem e dar ao agente orientações claras. O plano resultante era detalhado e, no papel, parecia bastante razoável. O trabalho foi estruturado da seguinte forma:
Problema → Pesquisa → Especificação → Revisão → Implementação → Verificação
À medida que a implementação avançava, o engenheiro percebeu que duas tarefas poderiam entrar em conflito e criar campos personalizados duplicados. A abordagem também estava tornando o código cada vez mais complexo e difícil de acompanhar. Felizmente, eles identificaram o problema, interromperam a implementação, redigiram um documento de projeto de uma página e marcaram alguns colegas de trabalho para obter contribuições. Juntos, eles analisaram o projeto e encontraram uma abordagem mais segura.
A especificação original fez o que pedimos: manteve o projeto avançando na direção original. O problema era que a direção estava errada. Uma especificação detalhada facilitou a continuidade do projeto, mesmo quando a ideia inicial era incerta. O agente conseguiu desenvolver essa ideia mais rápido do que as pessoas conseguiam parar e questioná-la.
Esse projeto demonstrou um risco da estrutura adicional: um agente poderia levar a mesma suposição equivocada da especificação para o código e os testes. A especificação, o código e os testes estavam em concordância entre si, mas isso não significava que a premissa subjacente estivesse correta. Para decisões mais arriscadas, ainda era necessário que outra pessoa voltasse à meta original e buscasse formas pelas quais a implementação pudesse violá-la.
Ainda assim, os agentes estavam assumindo trabalhos que duravam mais de uma sessão, e um prompt muitas vezes não era suficiente para preservar o que o projeto estava tentando fazer ou por quê. Isso nos levou a criar o /spec-driven, um framework de fluxo de trabalho centrado na especificação. A especificação mantinha a direção do projeto disponível para a sessão seguinte. Os scripts forneciam contexto e executavam verificações. Quando uma execução revelava uma regra, uma verificação ou um elemento de contexto ausente, podíamos adicioná-lo ao fluxo de trabalho para que os agentes posteriores não precisassem descobrir a mesma lacuna novamente.
Ainda há uma boa dose de discordância sobre se a estrutura adicional do SDD vale a pena. A Microsoft e a AWS promovem o SDD, enquanto a Thoughtworks o descreve como emergente e controverso, e os profissionais relatam experiências variadas. Os críticos alertam que o SDD pode produzir mais Markdown do que os engenheiros conseguem manter, transformar uma especificação detalhada em código escrito em prosa ou deixar para trás outra descrição do sistema que se afasta do código.[1][2][3]
Após três meses de uso real, aprendemos que a questão importante não era se deveríamos usar o SDD. Era o que faltava ao(à) atendente naquele projeto. Às vezes, a resposta era uma especificação. Às vezes, era um exemplo melhor, uma verificação automatizada ou um engenheiro que conhecia a área.
Por que criamos o /spec-driven
Alguns engenheiros da Asana já haviam experimentado o GitHub Spec Kit e o OpenSpec, mas nenhum deles se tornou parte do seu fluxo de trabalho regular. Queríamos uma versão que pudéssemos adaptar à medida que aprendêssemos e conectar ao processo de desenvolvimento da Asana.
O modo de planejamento integrado já era capaz de pesquisar a base de código e elaborar um plano de implementação útil antes de fazer alterações. O SDD acrescentou mais estrutura a esse plano: manteve o problema, as decisões-chave e os critérios de aceitação visíveis durante a implementação e a verificação.
Antes da implementação, o /spec-driven reproduziu a sua compreensão do problema e levantou as questões que poderiam alterar o plano. Isso dava ao engenheiro a oportunidade de corrigir o rumo antes que houvesse código para reescrever.
Armazenamos esse estado no repositório para que as sessões posteriores não precisassem adivinhar o que havia acontecido. Queríamos que as regras do fluxo de trabalho fossem determinísticas, de modo que os scripts cuidassem dos registros e das verificações. O modelo lidou com as partes que se beneficiavam do julgamento: fazer perguntas, avaliar vantagens e desvantagens e explicar as decisões.
O fluxo de trabalho incluía vários comandos. Os engenheiros usavam o comando /spec-driven spec para abordar as questões em aberto e elaborar uma especificação e um plano de implementação. Depois de revisar o plano, eles usaram o comando /spec-driven ship para implementá-lo, verificar o resultado e preparar o trabalho para revisão. Uma máquina de estados monitorava o projeto à medida que ele passava por esses comandos, para que as sessões posteriores soubessem o que havia acontecido e o que viria a seguir.
Desde o início, queríamos que o /spec-driven fosse mais do que apenas uma forma de elaborar e executar especificações. Também queríamos que ela orquestrasse fluxos de trabalho agênticos. Ele ordena as tarefas por dependência e mantém as alterações de arquivos que se sobrepõem em rodadas de execução separadas. Ele envia trabalhos independentes para vários agentes em paralelo e, em seguida, usa os resultados para decidir o que pode ser executado a seguir.
É como um GPS para o trabalho: a qualquer momento, fica claro qual é o próximo passo e onde estão as decisões realmente importantes, por isso, é difícil ficar travado.”
Os engenheiros da Asana usaram o /spec-driven tanto na abordagem “especificação primeiro” quanto na “especificação como referência”. Na abordagem “especificação em primeiro lugar”, eles usaram uma especificação para escolher uma direção e, em seguida, pararam de atualizá-la. Na abordagem ancorada na especificação, eles a mantiveram atualizada à medida que o trabalho mudava. Os engenheiros também elaboraram especificações independentes para partes de um esforço maior, de modo que uma única pessoa pudesse usar o fluxo de trabalho sem pedir à equipe inteira que o adotasse.
Quando o /spec-driven vale o esforço adicional
A estrutura adicional valeu mais a pena quando era necessário manter um contexto importante ao longo de sessões, transferências ou muitas tarefas relacionadas. Os engenheiros podiam analisar como o plano havia mudado, e a direção do projeto permanecia disponível quando o trabalho era transferido para outra sessão de agente ou pessoa. Dois esforços de produto mantiveram especificações dinâmicas por cerca de dois a três meses: um para desenvolver um novo recurso importante e o outro para atualizar as datas das subtarefas nas tarefas principais.
Acabei de concluir uma iniciativa relativamente grande com base em especificações e acho que isso realmente me ajudou! Trabalhei no plano por cerca de dois dias e, em seguida, concluí todo o trabalho de engenharia e fiz o merge em três dias.”
As especificações facilitaram as transições. Quem assumisse um projeto pausado poderia ver o que a equipe estava tentando fazer, por que ele havia tomado aquela forma e o que ainda faltava. Não precisavam reconstruir o projeto a partir de commits e conversas.
Os engenheiros também usaram o /spec-driven para coordenar grandes lotes de trabalho executado por agentes. No Painel do administrador da Asana, onde as equipes de TI das empresas clientes gerenciam as configurações de segurança, acesso, integrações e compartilhamento de toda a organização, os engenheiros o usaram para transferir 66 configurações para estruturas compartilhadas. A transferência dessas configurações exigiu cerca de 150 migrações em várias estruturas do painel do administrador. Cada migração se tornou um tíquete da Asana para um agente na nuvem, e os engenheiros os executaram em lotes paralelos, atualizando os tíquetes restantes com base nos resultados anteriores.
A equipe responsável por esse esforço informou que 91 % das migrações não precisaram de revisão após a análise e que o esforço geral foi concluído mais de um mês antes do planejado inicialmente.
Outra grande migração precisou apenas de um comando breve. A diferença estava no quanto a base de código já deixava claro. Ela continha exemplos que os agentes podiam seguir e verificações que podiam confirmar o resultado. Os agentes do painel do administrador não conseguiam identificar todos os requisitos a partir do código, portanto, o trabalho precisava de mais estrutura.
A abordagem orientada por especificações (/spec-driven) também ajudou na criação rápida de protótipos. Os engenheiros conseguiam responder rapidamente a um número suficiente de questões em aberto sobre o produto para criar uma experiência funcional de ponta a ponta. Os gerentes de produto e os designers podiam testar um protótipo antes que os engenheiros investissem no aprimoramento da produção. Se os engenheiros decidissem manter o código, geralmente era necessário fazer uma limpeza substancial antes que ele pudesse ser mesclado. A essa altura, o protótipo já havia mostrado se valia a pena levar a ideia adiante.
O que os primeiros números mostraram
Incentivamos todos a experimentar o /spec-driven pelo menos uma vez, mas não exigimos o uso contínuo. Cerca de metade dos engenheiros o experimentou. No último mês, o uso semanal variou de 30 a 50 engenheiros. Entre as habilidades de agente integradas e desenvolvidas pela Asana que os engenheiros acionaram diretamente, o /spec-driven ficou em terceiro lugar. O uso contínuo foi animador, mas não nos informou como o /spec-driven afetou a entrega.
A velocidade de engenharia é notoriamente difícil de mensurar. As pull requests e as adições de código de implementação são indicadores imperfeitos de produtividade, mas acreditamos que, muitas vezes, são medidas úteis do ponto de vista direcional. Para a comparação de velocidade, analisamos sete engenheiros e 524 pull requests mescladas ao longo de quatro meses. Comparamos o trabalho antes e depois do primeiro uso evidente de /spec-driven por cada engenheiro e excluímos especificações, planos e outros artefatos do fluxo de trabalho. Para a comparação de reversões, classificamos uma pull request como /spec-driven quando ela alterava os arquivos do projeto do fluxo de trabalho.
As pull requests por semana aumentaram 38%, e as adições de código de implementação aumentaram 2,66 vezes. Um período curto e de volume excepcionalmente alto influenciou o resultado das adições. Mesmo sem ela, as adições ainda foram 66% maiores. A taxa de reversões explícitas também foi ligeiramente menor: 1,2% para o trabalho orientado por /spec, em comparação com 1,66% para as outras pull requests.
Mais código não é necessariamente um bom resultado. Um agente pode produzir uma implementação extensa quando uma mais simples seria suficiente. Portanto, o aumento nas adições de código pode ter refletido soluções desnecessariamente extensas em vez de um maior número de trabalhos concluídos. A revisão normal nos proporcionou uma verificação contra esse modo de falha. Contamos com os revisores para sinalizar implementações que eram maiores ou mais complexas do que o problema exigia, e essas alterações ainda foram aprovadas. Isso nos deu certa confiança de que as implementações excessivamente longas não estavam causando todo o aumento.
Essas comparações não foram controladas, e não foi possível separar o efeito da abordagem orientada por especificações da combinação de projetos ou de melhorias mais amplas nas ferramentas dos agentes. Mesmo com essas limitações, saímos animados com os resultados.
O que ainda precisa ser melhorado
A revisão dos documentos pode se tornar um gargalo
A criação de uma especificação levava de 30 minutos a vários dias, dependendo da familiaridade do engenheiro com a área e da complexidade e do risco do projeto. Os engenheiros podiam usar o /spec-driven para que um agente elaborasse um rascunho de especificação rapidamente, mas a revisão ainda levava tempo.
Em um esforço, um engenheiro passou horas revisando uma pull request com o research.md, um arquivo de trabalho no qual o agente registrou o que aprendeu com a base de código, a documentação e as decisões anteriores antes de elaborar o rascunho da especificação. Algumas dessas conclusões eram vagas, imprecisas ou ligeiramente incorretas.
Essa revisão mostrou que não tínhamos chegado a um consenso sobre se esses arquivos eram anotações de trabalho temporárias ou documentação na qual os engenheiros futuros deveriam confiar. Alguns engenheiros valorizavam o registro de como uma decisão foi tomada. Outros temiam que registrar pesquisas imperfeitas fizesse com que elas parecessem confiáveis.
Em uma equipe de infraestrutura, a revisão de especificações passou a ser um novo obstáculo antes da implementação.
Achei que os comandos e o fluxo de trabalho pareciam muito mais complicados e demorados do que simplesmente elaborar um plano e depois implementá-lo.”
A maioria dos revisores não queria ler uma especificação longa e, depois, revisar o código também. Quando o trabalho chegava a uma pull request, a entrega precisava resumir a decisão, o motivo pelo qual a tomamos, o que parecia arriscado e como verificamos o resultado. Se a própria direção precisasse ser revisada, era preciso solicitar isso antes, enquanto ainda era fácil fazer alterações.
Uma especificação útil muda à medida que o projeto evolui
Os engenheiros continuaram aprendendo à medida que implementavam o plano. Atualizar a especificação com o que eles aprenderam exigiu esforço. Seus detalhes ajudaram durante a implementação, mostrando o que o agente achava que estava desenvolvendo. Posteriormente, grande parte desses detalhes repetia o código.
Agora acreditamos que uma especificação funcional deve se expandir enquanto o projeto estiver incerto e se reduzir quando o código puder explicar a implementação. O que restar deve ajudar o próximo leitor a entender o design, as decisões importantes, as restrições e os riscos não resolvidos.
As especificações concluídas levantam uma questão relacionada: o que deve acontecer com elas? Demoramos muito para responder a ela. Deixá-las no monorepositório facilita a sua localização, mas também deixa para trás documentos sem proprietário. Estamos movendo-as para um arquivo separado. Ainda precisamos de uma passagem de bastão mais curta que preserve o que será importante mais adiante. Se um documento gerava mais trabalho do que economizava, ele não estava ajudando.
Como incorporar ciclos de feedback ao sistema
Às vezes, a resposta não era outro documento, mas uma mudança no sistema em torno do agente. Um exemplo foi um bug na forma como o /spec-driven interpretava o Markdown: os títulos e as caixas de seleção dentro dos exemplos podiam ser confundidos com marcos reais ou tarefas não concluídas. Depois de registrar o bug, vasculhamos o restante do /spec-driven e encontramos vários comandos com seu próprio pequeno analisador de Markdown e o mesmo ponto cego. Substituímo-los por um analisador compartilhado, adicionamos testes de regressão e uma verificação de arquitetura e implementamos a correção no ambiente. A OpenAI descreve uma abordagem relacionada como engenharia de harness: colocar conhecimentos importantes onde os agentes possam encontrá-los, tornar as regras aplicáveis e usar as falhas para melhorar o ambiente ao redor do agente.
Outras lições não puderam se tornar um teste ou uma regra de arquitetura. Transformamos erros recorrentes em orientações. Como o /spec-driven conduzia os usuários por um fluxo de trabalho previsível, podíamos mostrar cada lição quando o agente chegasse à etapa relevante. Os engenheiros ainda decidiam quais lições se aplicavam além do projeto original.
Testamos as orientações em oito pull requests anteriores, além de casos sintéticos criados para identificar recomendações irrelevantes. Em um acompanhamento, testamos três dessas tarefas históricas com prompts curtos, médios e detalhados, totalizando nove comparações. A orientação revelou uma pergunta adicional útil ou um limite de planejamento em oito das nove comparações. Um teste separado abrangeu mais três tarefas históricas. Ela melhorou claramente dois planos; no terceiro, o agente sem orientação já havia identificado o problema.
As orientações mais úteis questionaram sobre mudanças de comportamento, consumidores e variantes afetados e contratos entre APIs, esquemas ou analisadores sintáticos. As avaliações abrangeram apenas perguntas e planos. Não medimos se a orientação acelerou a implementação. As orientações restritas também se tornaram obsoletas mais rapidamente e, às vezes, surgiam em trabalhos não relacionados.
Manter as orientações e as avaliações exigiu mais trabalho do que desenvolver a primeira versão. Poderíamos mapear a mina terrestre com orientações, desarmá-la corrigindo o sistema subjacente ou aceitar o risco de que um agente ou revisor tivesse que encontrá-la novamente. Geralmente, primeiro o mapeávamos porque era mais barato. Corrigir a API, o teste, a documentação ou o exemplo subjacentes exigia mais trabalho, mas beneficiava a todos e eliminava a necessidade de orientações.
Como abordaríamos a abordagem orientada por especificações agora
Queríamos impedir que os engenheiros repetissem os mesmos prompts e explicassem o projeto novamente sem eliminar o atrito útil. O agente ainda precisava parar quando tivesse uma pergunta importante, quando faltassem evidências ou quando a próxima etapa exigisse julgamento humano. Chegamos a algumas diretrizes práticas:
Para a maioria das pequenas mudanças locais, uma conversa ou um plano breve são suficientes.
Use a abordagem “especificação em primeiro lugar” para definir uma direção. Mantenha as especificações como referência quando as decisões precisarem ser válidas em sessões ou transferências posteriores.
Não inclua todas as peças que faltam na especificação. A ferramenta deve fornecer contexto e fazer verificações; o julgamento arquitetônico ainda precisa de revisão humana.
Quando valer a pena manter uma especificação, escreva-a para o próximo leitor. Mantenha as decisões e os riscos facilmente localizáveis, insira links para as evidências em vez de copiá-las e decida o que deve acontecer com a especificação quando o projeto terminar.
Próximos passos
Após três meses, os engenheiros ainda usam o /spec-driven quando o trabalho se estende por várias sessões, passa de uma pessoa para outra ou se divide em muitas tarefas relacionadas. Eles o usaram para manter o andamento de projetos de vários meses e organizar grandes lotes de trabalho executado por agentes. Esse é um bom resultado para um experimento interno.
À medida que expandimos o /spec-driven para contemplar mais tipos de trabalho, algumas novas funcionalidades resolveram problemas reais para equipes específicas, mas tornaram o fluxo de trabalho mais complexo para todos. Na próxima versão, queremos avançar em direção a um núcleo menor e mais focado.
As pessoas têm opiniões firmes sobre o SDD e a engenharia de cablagem. Aprendemos mais ao testá-los em trabalhos reais do que ao debater sobre eles. Antes de adicionar mais processos, agora perguntamos o que está faltando ao agente naquele projeto. Comece aos poucos, observe onde o fluxo de trabalho ajuda ou atrapalha e, em seguida, faça ajustes com base no que você aprender.
[1] Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl” (Compreendendo o desenvolvimento orientado por especificações: Kiro, spec-kit e Tessl), outubro de 2025.
[2] François Zaninotto, “Spec-Driven Development: The Waterfall Strikes Back”, novembro de 2025.
[3] Gabriella Gonzalez, “A sufficiently detailed spec is code”, março de 2026.
Sobre o autor
Walter Li é engenheiro de software na equipe de Infraestrutura de armazenamento principal da Asana, e Rohan Batra é engenheiro de software na equipe de Frameworks de back-end. Ambos passaram alguns meses integrados à equipe Tiger de Sucesso do Agente, onde lideraram o desenvolvimento e a avaliação do fluxo de trabalho orientado por especificações (/spec-driven) descrito neste artigo.
Agradecimentos à equipe
Agradecimento especial a Leo Zhang, Karol Krupa, Gordie Levitsky e Mitch Conquer por nos ajudarem a conceber e desenvolver o /spec-driven e por serem os primeiros a adotá-lo.