Um time aqui do trabalho estava com um problema bem específico: a agente de voz deles não sabia a hora de encerrar a conversa.

O produto é bacana. A pessoa abre um link, uma IA faz uma sequência de perguntas por voz, e no fim aquilo vira dado estruturado. Uma enquete conversacional. O tipo de coisa que você manda pro cliente e ele responde falando, sem formulário.

O ponto que faltava era o encerramento. A agente fazia as perguntas, recebia as respostas, e ficava ali. Boiando. Um humano sente a hora de encerrar um papo. A máquina, não.

Ultimamente eu tenho pego esse tipo de problema e montado um PoC pra deixar de exemplo - um caso rodando que os colegas podem abrir, entender e adaptar pro contexto deles. Foi o que fiz aqui.

Eu podia ter feito o que virou moda: sentar e escrever um documento gigante antes de tocar em qualquer código. Um spec. Requisitos, diagrama de estados, os quinze jeitos acadêmicos de detectar fim de conversa, critério de aceitação pra cada um. Spec-driven development, que estão vendendo como o jeito adulto de trabalhar com IA.

Não fiz. E é sobre isso que é esse post: por que a coisa mais simples possível resolveu, e por que o documentão teria me atrasado.

O único documento que valeu a pena veio antes de tudo - e não era um spec

A primeira coisa que fiz foi pedir pesquisa. Um prompt, escrito na pressa, com os typos e tudo:

claude, my teammates are working on a project that is an AI agent, a voice AI agent. The agent goes through a sequence of questions and has some interactions in the middle. The agent, however, cannot understand when to finish a conversation by itself. Websearch algorithms, models and all techniques that can be used for it. Fan out agents, look into HuggingFace, GitHub, Kaggle, wherever you find useful to look into.

Repara no que esse documento é. Ele não descreve o que eu ia construir. Ele mapeia o que o mundo já sabe sobre o problema: como a LiveKit, a Pipecat, a Vapi encerram uma chamada, que modelos de endpointing existem, o que os outros já tentaram e onde quebraram.

Essa é a diferença que quase ninguém separa direito.

Pesquisa reduz uma incógnita que você não tem como adivinhar sentado na cadeira. É conhecimento externo, que já existe fora da sua cabeça, esperando você ir buscar.

Spec tenta adivinhar uma incógnita que só o sistema rodando vai te responder. É chute interno com cara de certeza.

Um você colhe. O outro você inventa. E adivinha qual dos dois todo mundo passa o primeiro dia produzindo.

Salvei o resultado:

save all this research and reference to a file, in a new folder.

E só depois de ter o mapa na mão é que pedi o protótipo:

plan a PoC on this. A voice agent that runs on browser, with a human voice. It should go through a list of AI-crafted questions. The backend team is in Go, so it’s preferable to keep it that way.

A primeira linha de código de verdade nasceu 37 minutos depois do primeiro prompt. Sem PRD. Sem reunião de alinhamento sobre o schema. Pesquisa, um plano de meia página, e mão na massa.

Aquele prompt não foi uma busca no Google

Quando eu peço uma pesquisa dessas, o Claude Code não abre o Google e cola o primeiro resultado. Aquele meu prompt lá de cima virou um /deep-research, um comando que já vem embutido na ferramenta. Eu descrevi o problema em português torto; o Claude escolheu a ferramenta e rodou.

Por baixo, o /deep-research é um workflow: um script que orquestra vários subagentes, cada um numa fatia da tarefa, guardando os resultados fora da janela de contexto principal pra ela não entupir. Ele roda cinco fases - a lógica que qualquer pesquisador humano bom seguiria, só que em paralelo e sem preguiça:

1. Scope - pega a minha pergunta e quebra em uns 5 ângulos diferentes. Um busca o estado da arte, outro os papers acadêmicos, outro a visão cética/contrarian, outro a implementação prática. Ângulos que não se repetem.
2. Search - dispara 5 agentes de busca em paralelo, um por ângulo. Cinco pesquisas simultâneas, não uma.
3. Fetch - junta tudo, remove URL repetida, e vai buscar de fato as ~15 melhores fontes. Não o resuminho da SERP: a página inteira. De cada uma, extrai afirmações falsificáveis, com a citação direta que sustenta cada uma.
4. Verify - e aqui está o pulo do gato. Cada afirmação passa por 3 revisores céticos, cada um com uma ordem explícita: tente refutar isso. Se 2 dos 3 derrubam, a afirmação morre. Marketing, benchmark cereja, fórum, paper velho de área que anda rápido: tudo isso é filtrado antes de chegar em mim.
5. Synthesize - funde as duplicatas semânticas, ranqueia por confiança, e cospe um relatório com as fontes citadas.

Agora compara isso com o que você faz no Google.

Você digita uma query, recebe dez links azuis, abre oito abas, lê metade de três, esquece duas, e no fim salva um bookmark que nunca mais vai revisitar. Uma query. Um ângulo. Zero verificação. Você é o loop - o cansado, o que pula a sétima aba porque já deu.

No Claude Code o loop é a máquina, que não cansa na sétima aba nem na quinquagésima. E tem uma diferença mais funda que velocidade: no Google você busca páginas; no workflow você busca afirmações verificadas. Uma coisa te devolve uma pilha de abas. A outra te devolve um relatório onde cada frase já apanhou de três céticos.

O resultado daquela tarde está aberto no RESEARCH.md do projeto. São 45 fontes distintas - arXiv, GitHub, HuggingFace, docs da LiveKit e da Vapi - organizadas por tema, com os modelos de turn-taking open source separados dos datasets acadêmicos separados das ferramentas de vendor. Isso saiu de um prompt.

Senta e tenta montar essa mesma bibliografia na mão, no Google, numa tarde. Boa sorte. Você chega na décima aba e desiste - e as 35 fontes que faltavam eram justamente as que iam te poupar de reinventar o endpointing do zero.

O design de verdade foi escrito pelos bugs

Aqui está a parte que nenhum spec teria pego, porque é impossível ele pegar.

O produto de verdade nasceu de eu conversar com a coisa e reclamar do que estava ruim. Prompt por prompt, cada um disparado logo depois de eu falar no microfone e ouvir a agente errar:

I’m still speaking and she asks if I’m still there, but then she could get my answer…

Timeout do VAD curto demais. Ela me cortava no meio da frase pra perguntar se eu ainda estava ali. Isso não estava no spec porque não podia estar. Você só descobre com um microfone na mão e uma frase pela metade na boca.

she only says “that’s everything I wanted to ask” and it cuts. Why is this happening?

A despedida cortada no meio da própria despedida.

it repeated an already-answered question.

Ela reperguntava algo que eu já tinha respondido, porque um classificador rotulou minha resposta errado.

E a mais subjetiva de todas, a que dá o nó:

this intro is not like a human would talk.

Como é que você escreve num documento a regra “a abertura tem que soar humana”? Não escreve. O objetivo do produto era exatamente esse - fluido, não robótico - e isso é inespecificável em prosa. Você não sente um PRD. Você sente uma conversa.

Cada um desses defeitos foi descoberto boiando na frente do protótipo, não previsto num documento. E não tinha como ser diferente. Um agente de voz é feito do que acontece no meio-tempo entre a fala e a resposta, e esse meio-tempo não cabe em bullet point.

O eval virou o spec - só que crescendo de trás pra frente

Toda vez que eu achava um comportamento novo, o pedido era o mesmo:

add this to the eval.

Foi assim que o “spec” foi nascendo. Ele não previu os comportamentos. Ele os acumulou conforme apareciam. O documento cresceu de trás pra frente, a partir da realidade que rodou, e não da minha imaginação de sexta à tarde.

Repara na inversão. No spec-driven, o documento vem primeiro e a realidade tenta alcançar. No que eu fiz, a realidade veio primeiro e o documento correu atrás pra registrar o que já tinha se provado verdade.

O mesmo valeu pra escrever as coisas:

keep it documented, every single step must be documented and revalidated on every single change.

Doc depois da validação, descrevendo o que uma execução comprovou. Não antes, descrevendo o que eu torcia pra dar certo. O CLAUDE.md do projeto só apareceu lá no fim, quando já havia o que descrever.

O que sobrou no fim

Um PoC bom o suficiente pra resolver o problema interno do time.

Roda no navegador. Gera as perguntas a partir de um preset, a agente conduz a enquete com voz humana, reage ao que a pessoa fala, e - o que importava desde o começo - sabe a hora de encerrar. Inclusive quando a pessoa some no meio e ela precisa detectar o silêncio e finalizar sozinha, com dignidade.

Nada de documento de cem páginas. Um loop apertado, repetido até cansar: constrói, testa ao vivo, escuta o que quebra, conserta, fixa no eval. De novo. E de novo.

Foi rápido não apesar de ser simples. Foi rápido porque era simples.

Por que a simplicidade foi eficaz demais

Tem um artigo famoso do Wigner sobre a eficácia irracional da matemática nas ciências naturais. A ideia é que uma ferramenta simples às vezes explica muito mais do que tinha o direito de explicar. Foi exatamente essa a sensação aqui.

E o loop bobo de tentativa e erro que deu conta de tudo tem um nome: é só um chat com o Claude Code aberto do lado do navegador. Prompt curto, olho no protótipo, prompt curto de novo. Nenhuma cerimônia. Um problema que o pessoal do documentão trataria como projeto de duas semanas virou uma tarde de conversa.

Se você chegou até aqui procurando o pulo do gato, eu te devo uma decepção: não tem. Não teve arquitetura esperta, não teve prompt mágico, não teve técnica secreta. Descrevi o problema em português torto, deixei a ferramenta pesquisar, construí a coisa mais burra que funcionava e fui consertando o que quebrava na minha frente. Eu não fiz nada mirabolante - e é esse o post inteiro. A simplicidade não foi um detalhe do caminho. Foi o caminho.

E o motivo é meio óbvio quando você para pra olhar.

O spec-driven tenta transformar as incógnitas mais difíceis - as que só existem no comportamento do sistema rodando - em prosa confiante, antes do sistema existir. Ele gasta o cartucho mais caro cedo, no exato momento em que você sabe menos sobre o problema.

Eu só carreguei adiantado a única incógnita que dava pra resolver adiantado: a pesquisa do domínio, o conhecimento que já existia lá fora. O resto das incógnitas - as do design - eu deixei se resolverem sozinhas, empiricamente, no atrito com o microfone.

Não é que documento seja inútil. É que documento é bom pra registrar o que você descobriu, e péssimo pra fingir que já sabe. A hora dele é depois do primeiro contato com a realidade, não antes.

E sim, eu tenho consciência de que isso é um PoC, não um produto rodando em produção com SLA e pager tocando às três da manhã. Mas a ordem não muda com o tamanho da coisa. Produto, task, protótipo de uma tarde: você começa pela pesquisa, entende o que quer fazer, e daí faz. Foi literalmente o arco desse post. O spec-driven não inverte essa ordem - ele só empurra a parte de entender pra antes da hora, quando ela ainda é chute.

O pessoal do spec-driven vai passar o dia um escrevendo uma seção primorosa sobre o timeout do barge-in - que um microfone de verdade corrige em noventa segundos.

Você provavelmente não precisa disso. Pesquisa o que dá pra pesquisar, constrói a coisa mais burra que funciona, e deixa a realidade escrever o resto do spec pra você. Ela escreve melhor, e nunca atrasa a entrega.

Por hoje é só.