🚧 Onde o WAT falha

Novo aqui? Um workflow (a receita) é vago quando não diz o suficiente para o agente decidir sem adivinhar — por exemplo, "organize os arquivos" sem dizer por quê organizar, em que critério, nem onde salvar o resultado. Receita vaga é a causa mais comum de falha no WAT: não é o agente que "não entendeu", é a receita que não disse o bastante.

Um exemplo do dia a dia: você pede "faz um resumo das vendas do mês pra eu mandar pro grupo do WhatsApp da loja". Parece claro, mas está cheio de lacuna — resumo de quê exatamente (total, por produto, por vendedor)? De onde vêm os dados (a planilha de ontem, a de hoje, um sistema)? Quantas linhas o resumo pode ter? O agente não tem como recusar a tarefa, então ele preenche cada lacuna com a suposição mais razoável que encontrar — e "razoável pra ele" raramente bate com "o que você tinha na cabeça". O resultado sai genérico: um parágrafo correto sobre números, mas sem o recorte que você queria.

Novo aqui? Muitas ferramentas exigem uma chave de API (uma senha específica que autoriza o uso de um serviço, tipo enviar e-mail ou postar num site) para funcionar. Se a chave não foi configurada, ou o agente não tem permissão de usar aquela ferramenta (a Trilha 0 já tratou de permissões), o passo do workflow que depende dela simplesmente não pode ser executado — não importa quão claro o resto da receita esteja.

Esse é um erro fácil de confundir com "o agente não sabe fazer isso": na verdade, ele sabe exatamente o que fazer, só não tem a chave da porta. A solução nunca é reescrever o workflow — é configurar a credencial que falta (tema aprofundado na Trilha 4, módulo de Segredos).

Exemplo real: você pede "manda um e-mail pro cliente avisando que o pedido foi enviado". Se a ferramenta de e-mail (por exemplo, um servidor MCP de Gmail — assunto da Trilha 2) nunca recebeu a chave de acesso à sua conta, o agente chega até o passo de enviar e trava ali — a mensagem já está escrita, só não sai. É diferente de um erro de execução: o agente não "tentou e falhou", ele identificou que a porta está trancada e, se bem construído, para e avisa em vez de inventar que enviou.

Às vezes o workflow é claro e a ferramenta tem permissão, mas o agente ainda erra porque falta contexto — informação de fundo que ele precisaria para tomar a decisão certa. Exemplo: pedir "escreva um resumo no tom da empresa" sem nunca ter mostrado exemplos desse tom antes. O CLAUDE.md (visto na Trilha 0) existe justamente para carregar esse contexto de forma persistente, sem repetir tudo a cada pedido.

Falta de contexto também aparece de um jeito mais caro: quando o agente entra num loop — um ciclo que se repete sem nunca chegar ao fim — porque não tem informação suficiente pra saber quando parar. Imagine um workflow "revise este texto até ficar bom" sem nenhum critério do que é "bom". A cada rodada o agente revisa de novo, acha algo pra ajustar (sempre acha), e volta a revisar — sem um critério de parada, o ciclo pode continuar por dezenas de rodadas. Cada rodada consome tokens (a unidade que mede o quanto o modelo "lê" e "escreve" — e o que determina o custo de cada execução), então um loop mal desenhado não é só perda de tempo: é custo real subindo sem controle, às vezes por um workflow que parecia inofensivo.

Diferente de "vago" (que falta detalhe), um workflow ambíguo tem detalhe demais que se contradiz, ou permite mais de uma leitura razoável. Exemplo: "envie o relatório para o cliente até sexta, priorizando qualidade" e, três linhas depois, "não gaste mais que 10 minutos revisando" — as duas instruções competem entre si, e o agente pode escolher qualquer uma.

A diferença prática entre vago e ambíguo importa porque o conserto é oposto. Receita vaga se resolve adicionando detalhe. Workflow ambíguo se resolve removendo a contradição — decidindo qual das instruções que competem vale mais, e deixando isso escrito, não implícito.

Legenda: os quatro pontos de falha mais comuns do WAT, lado a lado com o conserto específico de cada um — nenhum se resolve do mesmo jeito.

Cada tipo de falha deixa uma pista diferente no comportamento do agente. Aprender a ler essas pistas evita ficar "brigando" com o agente sem entender por quê ele não acerta.

Pensando no ciclo do WAT (visto no módulo 1.2: o agente lê o workflow, decide o próximo passo, usa uma tool, repete), a falha quase sempre entra bem no início desse ciclo — na leitura do workflow ou na decisão — e só aparece pra você lá no fim, como resultado errado, custo alto ou tempo gasto à toa. O diagrama abaixo mostra o caminho:

Legenda: a falha quase nunca nasce na ferramenta — ela entra cedo, no workflow ou na decisão do agente, e só vira visível lá na ponta, como resultado ruim, custo alto ou tempo perdido.

Diante de um resultado que não saiu como esperado, percorra este checklist antes de culpar o agente — na grande maioria das vezes o conserto está numa dessas quatro linhas.

[ ] O QUE fazer está escrito (não só "organize", "resuma", "revise")
[ ] COM QUE dados/arquivos trabalhar está nomeado (caminho ou fonte exata)
[ ] ONDE salvar ou entregar o resultado está definido
[ ] Toda ferramenta usada no workflow tem chave/permissão já testada
[ ] O CLAUDE.md tem exemplo do padrão esperado (se o resultado exige "tom" ou "estilo")
[ ] Não há duas instruções competindo (prazo vs. qualidade, rapidez vs. cuidado)
[ ] Se existe "repita até...", há um critério de parada objetivo (não subjetivo)

Como verificar: rode o workflow uma vez num caso pequeno e barato antes de confiar nele em escala. Se o resultado bater com o que você esperava sem precisar de ajuste, os sete itens acima provavelmente estão cobertos. Se não bater, volte ao checklist e ache qual linha ficou sem marcar — é ali que está o defeito, não na "capacidade" do agente.