🤖 Prototipagem e agentes de IA
Os comandos da família 09: reduzir a ideia ao mínimo testável, especificar antes de construir, projetar o agente completo — prompt, ferramentas, memória — e avaliar antes de escalar.
🧪 /prototype + /MVP — o mínimo testável
/prototype reduz a ideia ao menor artefato capaz de validar a hipótese crítica. /MVP escolhe o conjunto mínimo de capacidades que entrega valor real e gera aprendizado. Os dois começam pela mesma pergunta: qual é a hipótese que, se estiver errada, derruba tudo?
✓ Protótipo que valida
- ✓Hipótese: "consultores pagariam por proposta automática". Protótipo: você gera 5 propostas à mão e cobra R$ 50 de cada — em 3 dias.
- ✓MVP: gerador com 1 template, pagamento por link, suporte por WhatsApp. Nada mais.
✗ Protótipo que enfeita
- ✗Landing page bonita com "em breve" — testa design, não disposição a pagar.
- ✗MVP com login, dashboard, 4 planos e integração com 3 ferramentas — antes do primeiro cliente.
Novo aqui? Hipótese crítica é a suposição que, se falsa, torna o resto irrelevante. Geralmente é sobre comportamento humano ("vão pagar", "vão voltar"), não sobre tecnologia ("dá para construir"). Teste-a primeiro, com o artefato mais tosco que funcione.
🎯 Copie e rode
/prototype /MVP para <ideia>; declare a hipótese crítica, o menor artefato que a testa em até 1 semana, o que conta como validação (número), e depois o MVP com no máximo 3 capacidades e o que fica explicitamente fora
Como verificar: o protótipo cabe em uma semana e a validação é um número ("5 pagantes"). A lista "fica fora" é maior que a lista "entra".
📄 /spec — especifique requisitos e limites
Define requisitos, interfaces, comportamento, limites, exceções e critérios de aceitação. É o contrato entre quem pede e quem constrói — e, quando quem constrói é um agente de IA, é literalmente o prompt de construção.
📐 As seis partes de uma spec
- •Requisitos: o que o sistema faz, em frases com "deve".
- •Interfaces: o que entra, o que sai, em que formato.
- •Comportamento: o que acontece no caminho feliz — passo a passo.
- •Limites e exceções: o que acontece com entrada inválida, timeout, dado ausente.
- •Critérios de aceitação: testes que, passando, encerram a discussão "está pronto?".
- •Fora de escopo: o que este ciclo NÃO faz — escrito, para ninguém "aproveitar para incluir".
🎯 Copie e rode
/spec para <funcionalidade ou sistema>; requisitos com "deve", interfaces de entrada/saída, comportamento no caminho feliz, 5 exceções com resposta esperada, critérios de aceitação testáveis e lista de fora-de-escopo
Como verificar: cada critério de aceitação pode virar um teste automático ou uma verificação de 30 segundos — nenhum começa com "deve ser intuitivo".
💡 Dica prática
Escreva os critérios de aceitação ANTES do comportamento. Quem sabe como vai verificar descreve melhor o que quer — e descobre requisitos que faltavam.
🤖 /agent — projete o agente completo
Define objetivo, ferramentas, memória, regras, entradas, saídas, limites e avaliação. Oito decisões que, tomadas juntas, fazem um agente confiável — e que, tomadas uma de cada vez conforme os bugs aparecem, fazem um agente imprevisível.
Ilustrativo: o núcleo é objetivo + prompt; os quatro módulos ao redor são comandos próprios; a base é /eval.
Novo aqui? Agente é um sistema de IA que recebe um objetivo, decide quais ferramentas usar, executa ações em sequência e verifica o resultado — em vez de só responder texto. A diferença para um chatbot é a capacidade de agir e de iterar sem instrução humana a cada passo.
🎯 Copie e rode
/agent para <tarefa que o agente vai cumprir>; objetivo em uma frase, entradas e saídas, ferramentas com quando usar cada uma, o que memoriza e o que esquece, regras invioláveis, limites de ação e como será avaliado
Como verificar: o objetivo cabe em uma frase sem "e". Agente com dois objetivos são dois agentes — ou um que faz os dois mal.
⚠️ O agente que faz tudo
A tentação é dar ao agente acesso a todas as ferramentas e "deixar ele decidir". O resultado é um sistema que ninguém consegue avaliar, porque não há comportamento esperado. Escopo estreito primeiro; amplie quando o /eval passar.
📝 /prompt + /tools — prompt robusto e ferramentas
/prompt especifica papel, objetivo, contexto, regras, ferramentas, formato e critérios de qualidade. /tools mapeia cada tarefa a uma ferramenta e — a parte que todo mundo pula — define quando não usar e quando escalar para um humano.
| Bloco do prompt | O que evita | Exemplo |
|---|---|---|
| Papel | Tom e profundidade aleatórios | "Você é o assistente de propostas da |
| Regras | Comportamento inventado nas exceções | "Nunca informe preço sem confirmar o plano do cliente" |
| Formato | Saída que ninguém consegue processar | "Responda em JSON com os campos: titulo, itens[], total" |
| Critério de qualidade | Agente satisfeito com resposta ruim | "A proposta está pronta quando todos os itens têm preço e prazo" |
Exemplo didático: cada bloco existe para fechar uma porta que o agente abriria sozinho.
🎯 Copie e rode
/prompt /tools para <agente>; prompt completo com papel, objetivo, contexto, regras invioláveis, formato de saída e critério de qualidade; tabela de ferramentas com tarefa, quando usar, quando NÃO usar e quando escalar
Como verificar: a coluna "quando NÃO usar" tem conteúdo em toda linha. Ferramenta sem restrição é ferramenta que vai ser usada errado.
💡 Dica prática
Teste o prompt com a pior entrada que você imaginar antes da melhor. Se o agente se comporta bem com "faz aí qualquer coisa", vai se comportar bem com pedido claro.
🧠 /memory — memória do sistema
Separa memória de sessão, perfil, fatos persistentes, histórico e política de atualização. A pergunta não é "o agente lembra?", mas "o que ele lembra, por quanto tempo, e quem tem poder de mudar isso?".
Sessão: o que morre ao fechar
Contexto da conversa atual. Barato, descartável, nunca deve conter decisão que precise sobreviver.
Perfil e fatos persistentes: o que atravessa sessões
Preferências do usuário, dados confirmados, decisões tomadas. Cada item com origem e data.
Política de atualização: quem escreve, quem apaga
O agente pode adicionar fato sozinho? Precisa de confirmação? Fatos vencem? Sem política, a memória acumula erro com cara de verdade.
Novo aqui? Política de atualização é a regra que diz quando um fato entra na memória, quando é substituído e quando expira. "O usuário disse X uma vez" e "o usuário confirmou X três vezes" merecem tratamentos diferentes — a política é onde isso fica escrito.
🎯 Copie e rode
/memory para <agente>; classifique o que ele precisa lembrar em sessão / perfil / fatos / histórico, defina formato e origem de cada item, política de atualização (quem escreve, quando expira) e o que NUNCA deve ser memorizado
Como verificar: a lista "nunca memorizar" existe e inclui pelo menos dados sensíveis e inferências não confirmadas.
🧫 /eval — avalie antes de escalar
Define casos de teste, critérios, métricas, falhas críticas e limiar de aprovação. É a base do desenho lá de cima: nada escala sem passar por aqui — e "passou" é um número, não uma sensação.
✓ Eval que decide
- ✓30 casos reais (incluindo 8 que já deram errado em produção), critério por caso, limiar: 90% de acerto e ZERO falha crítica.
- ✓Roda a cada mudança de prompt; resultado comparado com a rodada anterior.
✗ Eval de demonstração
- ✗"Testei com uns 5 exemplos e ficou bom."
- ✗Só casos fáceis; nenhum caso de exceção; nenhuma falha classificada como crítica — porque ninguém pensou no que seria uma.
Novo aqui? Falha crítica é o erro que, mesmo acontecendo uma vez em cem, inviabiliza o sistema: vazar dado de outro cliente, executar ação irreversível sem autorização, inventar preço. Falha crítica não entra na média — zera a aprovação.
🎯 Copie e rode
/eval para <agente>; 20-40 casos de teste incluindo exceções e casos que já falharam, critério de acerto por caso, métricas agregadas, lista de falhas críticas (tolerância zero) e limiar de aprovação para escalar
Como verificar: existe uma lista de falhas críticas separada da métrica geral — e o limiar de aprovação é um número decidido antes de rodar.
📊 Por que 90% não é o número
O limiar depende do custo do erro. Um agente que sugere títulos de post pode errar 20% sem problema. Um que envia propostas com preço, não. Defina o limiar pelo custo da pior falha comum — não por um número redondo.
🛡️ /guardrails — limites, fallback, escalonamento
Cria regras de segurança, autorização, validação, fallback e escalonamento. O agente confiável não é o que nunca erra — é o que, quando não sabe, para e pergunta em vez de improvisar.
🚧 Cinco camadas de guardrail
- •Autorização: quais ações exigem confirmação humana (pagar, apagar, enviar para fora)?
- •Validação de entrada: o que fazer com pedido fora do escopo ou malformado?
- •Validação de saída: a resposta passa por checagem antes de sair (formato, faixa de valores, dados sensíveis)?
- •Fallback: quando a ferramenta falha ou a confiança é baixa, qual é o comportamento padrão?
- •Escalonamento: em que condição o agente entrega para um humano — e para quem?
🎯 Copie e rode
/guardrails para <agente>; ações que exigem autorização humana, validações de entrada e saída, comportamento de fallback por tipo de falha, condições de escalonamento com destinatário e o que registrar em log
Como verificar: toda ação irreversível está na lista de autorização, e todo fallback tem comportamento definido — nunca "tenta de novo até dar certo".
⚠️ Guardrail no prompt não é guardrail
Regra escrita só no prompt é pedido, não limite — o modelo pode ignorar. Guardrail de verdade vive fora do modelo: validação de código, permissão de ferramenta, confirmação humana. O prompt avisa; a infraestrutura impede.
🔌 /integrate — integrações e sincronização
Mapeia sistemas, APIs, autenticação, dados, eventos, erros e sincronização. É o comando que transforma o agente que funciona na demo no agente que funciona na segunda-feira, com o CRM real e a planilha que alguém renomeou.
| Dimensão | Pergunta | Erro clássico |
|---|---|---|
| Autenticação | Como o agente prova quem é para cada sistema? | Token pessoal do dev em produção |
| Dados | Qual formato entra, qual sai, quem é a fonte da verdade? | Dois sistemas com o mesmo campo e valores diferentes |
| Eventos | O que dispara o agente — polling, webhook, agenda? | Polling a cada 10 segundos em API com limite de 100 chamadas/hora |
| Erros | O que acontece quando a API responde 500 ou demora? | Retry infinito que duplica pedidos |
| Sincronização | Quem ganha quando os dois lados mudaram? | "O último que salvou" — apagando o trabalho de alguém |
Exemplo didático: cada linha da tabela já foi um incidente em algum projeto real.
🎯 Copie e rode
/integrate para <agente> com <sistemas envolvidos>; para cada sistema: autenticação, dados de entrada/saída com fonte da verdade, gatilho (evento/polling/agenda), tratamento de erro com limite de retry e regra de sincronização em conflito
Como verificar: toda integração tem regra de conflito e limite de retry escritos — e nenhuma usa credencial pessoal.
💡 Receita composta
Arquitetura de agente completa, direto do documento: /agent /tools /memory /guardrails /eval /integrate. Note a ordem: eval antes de integrate — avalia-se em ambiente controlado antes de conectar ao mundo.
Auto-verificação rápida (opcional): por que o /eval vem antes do /integrate na receita de arquitetura de agente?
🎓 Resumo do Módulo
Próxima Trilha:
6.1 - Comunicação e aprendizado — você constrói e avalia; agora aprenda a explicar, ensinar e adaptar a mensagem para quem decide.