Blog, Pitang.

Nos últimos textos aqui do blog, o Diego Luna explicou o que é Spec-Driven Development (SDD) e por que desenvolver com IA exige mais do que bons prompts. Depois, mostrou o que aprendemos comparando diferentes abordagens de SDD, entre elas Spec Kit, OpenSpec e o plan mode do Claude Code. 

Neste texto, quero aprofundar um uso específico: a criação de testes funcionais automatizados com SDD. 

Cheguei a esse tema por experiência própria. Em um projeto, eu estava gerando testes funcionais com IA e, já perto do fim, passei a usar um fluxo de SDD. O ganho foi grande o bastante para eu querer medir com mais cuidado. Montei então um experimento e apresentei os resultados no Intervalo Técnico, um encontro interno em que compartilhamos estudos e debatemos com colegas de outras equipes. Agora, compartilho aqui o que aprendi. 

Por que testes funcionais são um bom terreno para testar o SDD? 

Existem vários tipos de teste em software, e cada um responde a uma pergunta diferente: 

• o teste unitário verifica se uma função faz o que deveria; 

• o teste de integração verifica se as partes conversam bem entre si, como o back-end e a API; 

• o teste de componente verifica um pedaço isolado da interface. 

  
  

O teste funcional ponta a ponta, que foi o foco do experimento, verifica o comportamento do negócio do ponto de vista de quem usa o sistema. Ele sobe a aplicação inteira e percorre uma jornada completa: um robô entra como cliente, abre um chamado e confere se ele aparece como aberto. 

Esse tipo de teste é o mais caro e o mais lento de manter. Em compensação, é o único que garante que o caminho do usuário, do início ao fim, funciona. 

Ele também está cheio de decisões implícitas. Quais perfis participam? Quais transições de status precisam ser cobertas? O que fazer quando o teste encontra um defeito? 

Quando essas decisões não estão escritas, a IA toma por conta própria. É exatamente esse o problema que o SDD se propõe a resolver. Por isso achei que testes funcionais seriam um bom lugar para ver se ele faz diferença de verdade. 

Como montei o experimento? 

A ideia foi simples: rodar a mesma demanda duas vezes. Uma vez só com prompt, no estilo vibe coding, e outra com o GitHub Spec Kit. 

Para a comparação ser justa, mantive todo o resto igual: o mesmo projeto, a mesma feature, o mesmo modelo de IA (Claude Opus, com raciocínio no nível médio, rodando no Claude Code) e a mesma ferramenta de testes, o Playwright. Se algo mudasse no resultado, eu queria ter certeza de que a causa era o método, e não outra variável. 

A aplicação: Pitang Desk 

Usei um projeto meu, o Pitang Desk, uma plataforma de chamados no estilo help desk. O back-end é em Node.js com NestJS e PostgreSQL, e o front-end é em React. Escolhi um projeto próprio por ter liberdade total para mexer nele, sem depender de um cliente real. 

A aplicação tem dois perfis, solicitante e atendente. O chamado passa por vários status: em aberto, em andamento, aguardando cliente, resolvido e fechado. Cada perfil pode fazer só algumas transições, e o servidor recusa as demais. 

Um detalhe importante: o projeto já era "AI Ready". Ele tinha arquivo de instruções para o agente, regras por camada, código consistente e testes unitários e de componentes. Isso influencia bastante o resultado, como vou mostrar mais adiante. 

A demanda: o ciclo de vida do chamado 

Os testes precisavam cobrir as jornadas do chamado: abertura, atendimento, conversa, nota interna, pausa e retomada, resolução e fechamento. Também precisavam cobrir o isolamento, ou seja, garantir que um cliente não vê o chamado de outro, nem pela lista nem por um link direto. 

Defini ainda uma regra que valeu para os dois lados: os testes não alteram o produto. Defeito encontrado é registrado, e não contornado. 

Fiz isso de propósito, porque a IA costuma ser “afobada”. Quando encontra um problema, ela tende a corrigir na hora. Em um trabalho de teste, isso é ruim: a correção pode mascarar o defeito, e a gente perde a chance de entender o que de fato está acontecendo. 

Como o Spec Kit organiza o trabalho? 

O Diego já apresentou o Spec Kit no comparativo de abordagens, então vou direto ao que importa aqui. 

É uma ferramenta do GitHub que funciona com qualquer agente: Claude Code, Copilot, Gemini e outros. Ela divide o trabalho em etapas, e cada uma gera arquivos em Markdown. As que usei foram Constitution, Specify, Clarify, Plan, Tasks, Analyze e Implement. 

O fato de tudo virar arquivo é mais importante do que parece. Cada decisão fica registrada e pode ser revisada por qualquer pessoa, inclusive por quem não lê código. 

Como foi o passo a passo com o Spec Kit? 

Passo 0: Constitution, as regras da casa 

A Constitution define os princípios do projeto, de forma parecida com um arquivo de instruções para o agente. Ela é característica do Spec Kit, e a maioria das outras ferramentas de SDD não trabalha com esse conceito. 

Ela importa porque é o que o agente consulta sempre que precisa decidir algo. Se uma regra não está ali, ele vai inferir. 

Passo 1: Specify, a demanda vira especificação 

Aqui a demanda é transformada em histórias de usuário e requisitos. 

Antes mesmo de qualquer código, a IA já levantou uma suspeita: talvez a ação do atendente não estivesse registrando as mudanças de status no histórico. Ela percebeu uma possível inconsistência só lendo o pedido. 

É o primeiro sinal de valor do SDD. Quando a IA é obrigada a descrever o que vai fazer antes de fazer, os buracos da demanda aparecem cedo. 

Passo 2: Clarify, as perguntas que ninguém fez 

O Clarify faz até cinco perguntas de múltipla escolha, e cada resposta vira um requisito na especificação. Como o projeto já estava bem documentado, as perguntas foram poucas e certeiras. 

Uma delas foi decisiva: “No isolamento, conferir também que o servidor recusa, e não só a tela?” 

Parece um detalhe, mas não é. Se o teste só verifica que a interface esconde o chamado de outro cliente, ele não garante nada sobre segurança. Basta alguém chamar a API direto com a sessão de outro usuário para descobrir se os dados vazam. 

Com a resposta, o teste passou a validar as duas coisas: a tela exibe “acesso negado” e o servidor responde com erro 403, sem devolver nenhum dado. 

Também respondi que os testes deveriam cobrir todas as combinações de transição por perfil, e que, ao encontrar um defeito, o teste deveria registrar e seguir. 

Aqui está um ponto central do experimento. No prompt direto, essas mesmas decisões também foram tomadas, só que pela IA, sem que ninguém soubesse. A diferença importa porque um teste que valida uma decisão que ninguém tomou passa do mesmo jeito. Ele só revela que validava a coisa errada quando o problema já chegou em produção. No SDD, foram tomadas por uma pessoa, de forma consciente e registrada. 

Entre os passos: um navegador para a IA 

Antes do planejamento, adicionei o MCP do Playwright ao projeto. Com ele, a IA passa a ter um navegador: consegue navegar pela aplicação, tirar snapshots da tela e interceptar requisições de rede. 

Isso muda bastante o processo. A IA deixa de só imaginar como a aplicação funciona e passa a conferir as specs na aplicação rodando. 

Ela encontrou duas falhas logo de cara: a lista vazia estava quebrando, e o atendente não registrava o status no histórico. Sem o navegador, esses problemas só apareceriam em tempo de execução, já com os testes escritos. 

Passo 3: Plan, o planejamento técnico 

No plano, a IA definiu como os testes seriam construídos: 

• três navegadores ao mesmo tempo, um por usuário, para simular perfis interagindo em paralelo; 

• preparação dos dados pela API, o que é mais rápido e estável do que preparar pela tela; 

• verificação dos status em dois lugares; 

• documentação dos defeitos já conhecidos, sem tentar contorná-los. 

Passo 4: Tasks, a divisão do trabalho 

A demanda foi quebrada em 37 tarefas, organizadas em 10 fases, e 17 delas podiam rodar em paralelo. Essa divisão ajuda a IA a trabalhar em partes menores e verificáveis, e permite acompanhar o progresso com clareza. 

Passo 5: Analyze, a revisão antes do código 

Para mim, esta é uma das etapas mais interessantes do Spec Kit. O Analyze revisa tudo o que foi produzido até ali (especificação, respostas do Clarify, plano e tarefas) e procura contradições. 

Ele encontrou seis inconsistências entre esses artefatos. Todas foram resolvidas antes de escrever qualquer linha de código. 

Corrigir uma inconsistência na especificação custa uma conversa. Corrigir depois que ela virou código custa retrabalho. 

Passo 6: Implement, a execução 

Com tudo definido, a IA implementou. Foram 36 das 37 tarefas concluídas. A única pendente era o commit, que aguardava minha autorização, como deve ser. 

A implementação levou 12 minutos. O resultado foi uma suíte de 23 testes que passou duas vezes seguidas e rodou inteira em 18 segundos, graças aos workers paralelos do Playwright. Rodar duas vezes importa porque teste funcional que passa só às vezes não serve para nada. 

Foram três defeitos registrados e zero linhas alteradas no produto. 

Os testes cobriram cenários bem ricos. Um exemplo é a nota interna: o atendente deixa um comentário que outros atendentes enxergam, mas o cliente não. O teste abre os dois perfis ao mesmo tempo e confere a tela de cada um. Outros cenários garantem que o cliente vê o nome do atendente, mas nunca o e-mail, e cobrem pausar e retomar, resolver, discordar, reabrir e fechar. 

E sem SDD, o que aconteceu? 

Com o prompt direto, a IA não fez nenhuma pergunta. Ela foi direto para a implementação, revisou o próprio trabalho durante o processo, encontrou alguns defeitos e entregou. 

O resultado também funcionou: os testes passaram e cobriram o que foi pedido. Mas teste que passa não é o mesmo que teste que protege. As três decisões de negócio que, no Spec Kit, passaram por mim (conferir a recusa do servidor, cobrir todas as transições por perfil, registrar o defeito em vez de contornar) aqui foram tomadas pela IA sozinha, e eu só descobriria qual caminho ela escolheu lendo o código. A diferença está em como essa entrega foi construída e no que ficou registrado. 

Sem SDD, as regras ficaram escondidas no código: no nome dos testes, em comentários e em um único arquivo. Em um projeto pequeno, isso incomoda pouco. Num projeto grande, ou quando um teste quebra seis meses depois, a IA, ou a próxima pessoa, vai ter que garimpar o código para descobrir por que cada teste existe e se a regra que ele valida ainda vale. Isso custa tempo e tokens, e às vezes custa o próprio teste: sem conhecer a intenção, a tendência é ajustar a asserção até passar.  

Com o Spec Kit, os testes ficaram organizados por jornada, e cada requisito pode ser rastreado até o teste que o valida. 

O que os números mostram? 

Medi apenas o tempo de processamento da IA, sem contar o tempo em que eu estava fazendo outras coisas em paralelo: 

• Tempo: 19 minutos com prompt direto e 29 minutos com Spec Kit, cerca de 50% a mais; 

• Tokens: quase cinco vezes mais com Spec Kit; 

• Pontos de decisão com participação humana: 1 com prompt direto e 12 com Spec Kit; 

• Decisões de negócio confirmadas por uma pessoa: nenhuma com prompt direto e 3 com Spec Kit; 

• Inconsistências corrigidas antes do código: 6 com Spec Kit; 

• Defeitos encontrados antes de escrever os testes: 2 com Spec Kit. 

  
  

Resumindo a conta: dez minutos a mais de processamento e cerca de cinco vezes mais tokens compraram seis inconsistências e dois defeitos resolvidos antes de existir código, três decisões de negócio confirmadas por uma pessoa e uma suíte que cobre mais do que foi pedido. Um único desses defeitos chegando a produção custaria mais do que isso. 

Quanto à cobertura, os dois lados entregaram 100% do que foi pedido. Mas eu diria que o SDD chegou a uns 130%. 

Com o prompt direto, a IA foi literal: pedi A, B e C, e ela fez exatamente A, B e C, nada além do que eu já sabia que precisava. Com o SDD, ela me provocou. Testou o caminho feliz e também o que acontece quando o usuário faz algo errado. Esses acréscimos não foram aleatórios, todos fizeram sentido para o produto. 

Há ainda ganhos que não aparecem nos números. Um deles é a limpeza dos dados gerados pelos testes, inclusive quando a execução é interrompida, que foi sugerida pelo Spec Kit. Outro é a documentação versionada, que pessoas não técnicas conseguem revisar. Isso permite, por exemplo, validar uma regra de negócio com o cliente sem mostrar uma linha de código. 

O SDD vale a pena na mesma medida em todo cenário? 

Não na mesma medida em todo cenário. E eu queria medir justamente isso: onde o custo extra se paga com folga e onde ele pesa mais do que o retorno. 

Antes do experimento principal, fiz um teste menor: um cadastro simples de feriados, um CRUD básico com data e descrição. 

Em cobertura funcional, o resultado foi quase um empate: as duas abordagens entregaram as mesmas quatro jornadas, com estrutura de código parecida. A diferença apareceu na qualidade do que foi entregue, e no custo.  

O SDD ainda trouxe ganhos: validação pelo servidor, limpeza da base, detecção de colisão de datas em testes paralelos e ressalvas documentadas para eu decidir. Mas foram ganhos bem menores do que no ciclo de vida do chamado. 

A explicação é simples. O cadastro de feriados não tinha decisões a tomar. A demanda já estava clara, as regras eram poucas e a feature era pequena. Nesse cenário, o custo extra do fluxo completo é mais difícil de justificar. Ainda assim, vale notar: mesmo aqui o SDD entregou validação pelo servidor e limpeza da base, que o prompt direto não entregou. O retorno foi menor, não inexistente. A pergunta deixa de ser "usar ou não SDD" e passa a ser "quanto do fluxo essa demanda merece". 

Vemos isso também fora do experimento. Aqui na Pitang, temos um projeto em que o SDD foi muito usado no início. Naquela fase, as regras de negócio ainda estavam sendo definidas, a arquitetura estava em construção e cada demanda trazia decisões que precisavam ficar registradas. 

Com o tempo, o projeto amadureceu. As especificações, as regras e as decisões acumuladas passaram a fazer parte do próprio repositório, e a IA ficou bem familiarizada com as características do projeto. Hoje, o time não precisa rodar o fluxo completo a cada demanda do dia a dia, pois boa parte do que o SDD ajudava a esclarecer já está escrita e o agente sabe onde encontrar. Demandas que trazem decisões novas voltam a passar pelo fluxo. 

Isso mostra que a intensidade do SDD não é fixa. Ele faz mais sentido quando ainda há incerteza. Quando o projeto amadurece, o conhecimento produzido nessa fase vira o contexto que permite trabalhar de forma mais leve. Em vez de desperdício, o esforço do início é justamente o que torna possível dispensar o fluxo completo depois. Os tokens gastos na spec não são custo afundado: são o contexto que barateia todas as demandas seguintes. 

Como o Diego mostrou no post anterior, também existem caminhos intermediários, como o plan mode, que planejam a demanda com um custo bem menor do que um fluxo completo de SDD. 

Quando usar SDD na criação de testes? 

Com base no experimento, o SDD rende mais quando: 

• há regras de estado e de perfil, como transições, permissões e isolamento entre usuários; 

• existem decisões reais para a pessoa que opera a IA tomar, e não só tarefas a executar; 

• outras pessoas vão continuar o trabalho depois. No Pitang Labs, a troca de projetos é frequente, e um repositório com specs e decisões registradas permite que quem chega conecte seu agente e já encontre o contexto pronto; 

• a entrega precisa ser auditável, porque o histórico deixa de ser só o commit e passa a incluir todas as decisões do processo. 

  
  

Ele rende menos quando: 

• a feature é pequena, como uma única tela sem regras complexas; 

• a demanda já chega muito bem escrita; 

• é um protótipo pequeno. Aqui cabe uma ressalva: muitas provas de conceito que chegam ao Labs já têm o tamanho em que o SDD faz sentido. 

  
  

Note que “render menos” não é “não render”. O segundo caso, aliás, é SDD feito antes: uma demanda que chega bem escrita já é uma especificação. E, mesmo quando o fluxo completo não compensa, a alternativa não precisa ser o prompt direto. Um plan mode ou um Specify + Clarify enxuto já capturam as decisões com uma fração do custo. 

O que aprendi com o experimento? 

1. Deixe o projeto AI Ready 

Instruções do projeto, regras bem definidas e documentação fazem diferença em qualquer abordagem. Quanto mais contexto o agente encontra, menos ele precisa inferir, e menos dúvidas surgem no processo. 

2. Use SDD onde há decisão a tomar 

Trocar a cor de um botão de verde para vermelho não exige especificação. Reestruturar uma tela, mudar um fluxo ou mexer em regras de permissão, sim. A complexidade da decisão é o que justifica o custo extra. E, em testes funcionais, quase toda demanda carrega decisão: quais perfis, quais transições, o que fazer com o defeito encontrado. Por isso, nesse tipo de teste, o SDD tende a ser a regra, e não a exceção. 

3. Dê um navegador para a IA 

Usei o MCP do Playwright, mas existem outras opções, como extensões de navegador para agentes e recursos de computer use. O importante é que a IA veja a tela, e não só o código. Foi isso que permitiu encontrar defeitos antes de escrever os testes. 

4. Defeito encontrado é registrado, e não contornado 

Vale para SDD e para vibe coding. Peça à IA para documentar o problema, e não para corrigi-lo. 

Uma prática que gosto é escrever um teste que passa com o erro. Quando a correção subir, esse teste vai falhar e servir de lembrete para atualizar o teste também. 

5. Prefira instruções que funcionam com qualquer agente 

Uma dica que veio do Diego: o Claude Code também lê o arquivo AGENTS.md, um padrão que Codex, Copilot e Gemini também reconhecem. Com um único arquivo de instruções, o projeto fica independente da ferramenta de IA usada. 

Testar com IA também exige método 

O experimento confirmou algo que essa série de textos vem mostrando: SDD não é sobre usar mais ferramentas, e sim sobre decidir de forma consciente. 

No prompt direto, a IA entregou testes que funcionam. Com o SDD, entregou testes que funcionam e que explicam por que existem, quem decidiu cada regra e o que ainda está pendente. Em projetos grandes, que vão mudar de mãos e precisam de segurança, essa diferença vale o custo extra. E esse custo não é perdido: as specs viram o contexto que barateia as demandas seguintes. Por isso, na Pitang, tratamos a especificação como parte do processo de desenvolver e testar com IA, e não como etapa opcional. O que ajustamos de projeto para projeto é o peso do fluxo, não a presença dele. Testes que apenas passam dão sensação de segurança; testes que explicam por que existem dão segurança de verdade. 

Aqui no Pitang Labs, seguimos experimentando ferramentas e abordagens para entender onde cada uma faz mais sentido, e compartilhando o que aprendemos.