🧭 Como ler este módulo
WAT é menos um software e mais uma forma de organizar qualquer projeto agêntico. Você vai ver as três camadas separadamente (W, A, T), depois o loop que faz tudo melhorar sozinho, a estrutura de pastas recomendada e — importante — os casos em que montar WAT é exagero. Não precisa saber programar: o agente escreve e conserta os scripts; você só precisa entender o mapa.
Antes de abrir cada camada, veja como elas se encaixam. As instruções em markdown dizem o que fazer; o agente lê essas instruções, olha as ferramentas disponíveis e decide qual usar; as tools em Python executam o trabalho de verdade. E há um detalhe que muda tudo: quando algo dá errado, o agente conserta a tool e atualiza o workflow — então o sistema fica melhor a cada execução.
Diagrama ilustrativo — o manual (W) guia o cérebro (A), que usa as mãos (T); o que o agente aprende ao corrigir um erro volta para o manual, então o sistema melhora sozinho.
🗺️ Visão geral do WAT
O que é
WAT é uma sigla simples para três camadas que, juntas, dão ao seu projeto agêntico um manual, um cérebro e mãos: Workflows (instruções), Agent (o coordenador) e Tools (os scripts). A ideia não é uma tecnologia nova — é um jeito de arrumar peças que você já conhece para que elas se conversem de forma previsível.
O que é?Fluxo agêntico (agentic) — um processo em que uma IA não só responde, mas age: decide passos, chama ferramentas e se corrige. Framework — aqui, uma estrutura mental/organizacional, não um programa que você instala.
A analogia que cola: imagine contratar um assistente novo. Você entrega a ele um manual de procedimentos (os workflows), ele usa o próprio raciocínio para decidir o que fazer em cada caso (o agente), e tem um conjunto de ferramentas físicas na bancada (as tools). A maioria dos projetos agênticos que você vai construir cabe nesse molde — e por isso vale aprender o vocabulário uma vez e reaproveitar para sempre.
Por que aprender
Ter um molde repetível significa que você não reinventa a roda a cada projeto. Quando o WAT vira o seu padrão, qualquer pessoa (você daqui a três meses, inclusive) abre a pasta e entende na hora o que é o quê.
- •Vocabulário comum: você e a IA falam a mesma língua sobre o projeto.
- •Estrutura repetível: o mesmo esqueleto serve do bot simples ao agente de produção.
- •Separação de papéis: instrução, decisão e execução ficam em camadas distintas.
Conceitos-chave
O que fazer, em markdown.
Decide qual tool usar.
Scripts que executam.
Quase tudo cabe nele.
📄 W = Workflows (instruções markdown)
O que é
A camada W são arquivos de instrução em markdown — texto simples com títulos, listas e negrito — que funcionam como uma descrição de cargo ou um SOP (procedimento operacional padrão). Cada workflow conta ao agente o que ele deve fazer numa tarefa específica: qual é o objetivo, qual é a entrada, qual é a saída esperada e quais são os passos.
O que é?Markdown — uma forma de escrever texto formatado com símbolos simples (`#` vira título, `-` vira lista, `**` vira negrito). SOP (Standard Operating Procedure) — um documento que descreve, passo a passo, como executar uma tarefa de forma consistente.
Esta é a camada que você mais edita. Mudar o comportamento do agente quase nunca significa mexer em código — significa reescrever o workflow em português claro. Um bom workflow documenta quatro coisas: o objetivo (o resultado final), a entrada (o que ele recebe), a saída esperada (formato, nome, onde salvar) e os passos em ordem. Quanto mais explícito, menos o agente precisa adivinhar.
📄 Esqueleto: workflows/relatorio-semanal.md
# Relatório semanal de vendas ## Objetivo Gerar um PDF com o resumo das vendas da semana. ## Entrada A planilha vendas.csv na pasta temporary/. ## Saída relatorio-AAAA-SS.pdf salvo em temporary/, com total, top 5 produtos e variação vs. semana anterior. ## Passos 1. Ler vendas.csv com a tool ler_csv.py 2. Calcular totais e top 5 3. Gerar o PDF com a tool gerar_pdf.py
✅ Note: nenhum código aqui — só linguagem natural estruturada. O agente lê isto e escolhe as tools.
Por que aprender
Como o workflow é a camada que mais muda, dominá-la é o que mais retorno te dá. Um workflow bem escrito faz o agente acertar de primeira; um vago faz ele perguntar (ou pior, supor errado). Pense nele como o briefing que você daria a um humano competente: claro o bastante para não ter dúvida, enxuto o bastante para não cansar.
Conceitos-chave
Descrição de cargo do agente.
Texto simples, sem código.
Objetivo · entrada · saída · passos.
Mudar comportamento = mexer aqui.
🧠 A = Agent (o coordenador que decide)
O que é
A camada A é o próprio assistente de IA — o coordenador, o cérebro do sistema. Ele lê os workflows, enxerga quais tools existem e decide, em cada momento, qual ferramenta chamar e quando. Não é um roteiro fixo: o agente escolhe o caminho, como um gerente de projeto que delega a pessoa certa para cada parte.
O que é?Coordenador (orchestrator) — o componente que não faz o trabalho braçal, mas decide a ordem das coisas e quem faz cada parte. Delegar — passar uma sub-tarefa para a ferramenta (ou sub-agente) mais adequada.
Diagrama ilustrativo — o agente não roda um script fixo; ele lê o manual e decide qual das mãos usar para o que tem na frente.
Por que aprender
Confundir o agente com um script é o erro mais comum de quem chega. Script faz sempre a mesma coisa na mesma ordem; o agente raciocina e adapta. Por isso ele pode lidar com situações que você não previu — e por isso também você precisa lhe dar bons workflows (o manual) e boas tools (as mãos): ele só é tão bom quanto o que tem disponível para coordenar.
🎯 Dica prática
Quando o agente escolher a tool "errada", quase sempre o problema está no workflow (descrição ambígua) ou no nome/descrição da tool (não diz claramente o que faz). Corrija o manual, não brigue com o cérebro.
Conceitos-chave
A própria IA coordena.
Não é roteiro fixo.
Delega à tool certa.
Lida com o imprevisto.
🔧 T = Tools (scripts Python de um trabalho cada)
O que é
A camada T são scripts em Python que fazem o trabalho de verdade. A regra de ouro: idealmente, uma tool faz um trabalho só — raspar um site, gerar um PDF, analisar uma planilha. São as "mãos" do sistema, as que tocam o mundo (arquivos, APIs, dados).
O que é?Script — um arquivo de código que executa uma tarefa quando rodado. Python — a linguagem mais comum para essas tools; você não precisa saber escrevê-la, porque o agente escreve e conserta por você.
O ponto que tira o medo: o agente escreve e repara as tools. Você não precisa saber programar — descreve o que a tool deve fazer (no workflow) e o agente produz o Python. Tools pequenas e focadas são fáceis de testar (uma coisa só pode dar errado), reusar (a mesma gerar_pdf.py serve a vários workflows) e consertar (o conserto fica isolado). Uma tool que "faz tudo" vira uma caixa-preta que ninguém — nem o agente — entende direito.
✓ Boa tool (um trabalho)
- ✓
raspar_precos.py— só lê os preços de uma página. - ✓Entrada e saída claras (recebe URL, devolve CSV).
- ✓Fácil de testar isolada e reusar em outro workflow.
✗ Tool inchada (faz tudo)
- ✗
fazer_relatorio.pyque raspa, calcula, gera PDF e envia e-mail. - ✗Quando quebra, é difícil saber qual parte falhou.
- ✗Não dá para reusar pedaços; vira caixa-preta.
Conceitos-chave
Cada tool faz uma coisa.
O agente escreve por você.
Pequena = fácil de conferir.
Serve a vários workflows.
🔄 O loop de auto-melhoria
O que é
O loop de auto-melhoria é o superpoder do WAT. O agente roda um workflow, esbarra num erro, diagnostica a causa, conserta a tool — e, o mais importante, atualiza o arquivo de workflow para que aquele erro nunca mais aconteça. A cada execução, o sistema fica mais liso e mais rápido.
O que é?Diagnosticar — descobrir por que algo falhou, não só que falhou. Auto-correção — o agente aplicar a correção sozinho (na tool e no workflow), sem você ter de explicar a solução.
Diagrama ilustrativo — o erro não é desperdício: vira uma melhoria permanente no manual. Por isso o WAT melhora sozinho com o uso.
Por que aprender
Sem o loop, você conserta o mesmo erro toda semana. Com ele, cada falha é "paga uma vez": o agente registra a lição no workflow e o sistema deixa de tropeçar ali. É o que transforma um protótipo frágil num assistente confiável — e a chave é insistir que ele atualize o workflow, não só remende a tool de improviso.
A volta completa do loop, passo a passo
- 1Roda — o agente executa o workflow com a tool atual.
- 2Erro — algo falha (formato inesperado, campo vazio, API fora do ar).
- 3Diagnostica — lê a mensagem de erro e identifica a causa-raiz.
- 4Conserta a tool — ajusta o Python para tratar aquele caso.
- 5Atualiza o workflow — registra a lição para o erro não voltar. Depois, volta ao passo 1, mais robusto.
Conceitos-chave
Acha a causa do erro.
Ajusta o script.
Lição vira regra fixa.
Mais liso a cada run.
📁 Estrutura de pastas (workflows/tools/temporary/.env)
O que é
O WAT tem um layout de pastas recomendado que dá lugar a cada coisa: uma pasta workflows/ (os manuais em markdown), uma tools/ (os scripts Python), uma temporary/ (arquivos intermediários e de saída), um arquivo de ambiente .env (chaves de API e segredos, nunca compartilhado) e o CLAUDE.md na raiz, que orienta o agente sobre o projeto inteiro.
O que é?.env — um arquivo onde ficam segredos (chaves de API, senhas) separados do código, para nunca irem parar no GitHub. CLAUDE.md — o arquivo de contexto que o agente lê primeiro; explica o projeto, as regras e como as camadas WAT se organizam.
Diagrama ilustrativo — cada camada do WAT ganha sua pasta; segredos ficam isolados no .env e a temporary/ guarda o que é descartável.
🎯 Objetivo: montar a estrutura WAT do projeto
no Plan Mode, crie um CLAUDE.md na raiz usando o framework WAT, com as pastas workflows/ tools/ temporary/ e um arquivo .env. Descreva cada camada (W, A, T) e as regras de operação.
✅ Como verificar: confira que as pastas workflows/ tools/ temporary/ e o .env foram criados, e que o CLAUDE.md cita as 3 camadas.
📁 Resultado esperado: árvore de pastas do projeto
projeto/ ├─ CLAUDE.md <- contexto: explica o projeto e o WAT ├─ workflows/ <- W: os manuais em markdown (.md) ├─ tools/ <- T: os scripts Python (.py) ├─ temporary/ <- arquivos intermediários e de saída └─ .env <- segredos (NUNCA versionar/compartilhar)
✅ A camada A (o agente) não é uma pasta: é o próprio assistente que lê tudo isso e coordena.
Conceitos-chave
Os manuais .md.
Os scripts .py.
Intermediários e saída.
Segredos isolados.
🚦 Quando NÃO usar WAT
O que é
Tão importante quanto saber usar o WAT é saber quando não usá-lo. Para uma tarefa pontual (uma vez só), experimentação inicial, ou um pedido simples o bastante para caber numa frase, montar toda a estrutura WAT é exagero — burocracia que custa tempo e contexto sem retorno. Nesses casos, é só digitar o pedido.
O que é?Tarefa de uma frase — algo que você consegue descrever completamente em uma única instrução ("converta este CSV em JSON"). Contexto — o "espaço de memória" da conversa; estruturas desnecessárias o enchem à toa.
✓ Use WAT
- ✓Tarefa repetível que você vai rodar muitas vezes.
- ✓Processo complexo, com vários passos e tools.
- ✓Algo que precisa melhorar com o tempo (loop de auto-melhoria).
✗ Não use WAT
- ✗Pedido de uma frase ("resuma este texto").
- ✗Tarefa pontual, que roda uma vez e acabou.
- ✗Experimentação inicial, ainda explorando a ideia.
Por que aprender
Quem aprende o WAT às vezes quer estruturar tudo — e acaba criando pastas e workflows para coisas que dariam um comando direto. Saber quando não usá-lo evita burocracia, economiza contexto e mantém você rápido. A régua é simples: se cabe numa frase, é uma frase; se vai se repetir e crescer, vira WAT.
🎯 Dica prática
Comece sempre pelo pedido direto. Quando perceber que está repetindo o mesmo pedido (ou ajustando-o toda vez), aí é a hora de promovê-lo a um workflow. Deixe a estrutura emergir da necessidade real, não do entusiasmo.
Conceitos-chave
Pedido simples, sem estrutura.
Roda uma vez, sem WAT.
Promova quando repetir.
Estrutura na medida.
No framework WAT, qual camada decide qual ferramenta usar em cada momento?
📌 Resumo do Módulo
Próximo Módulo:
2.3 — MCP por Dentro