Guia de Arquitetura GenAI

Arquitetura GenAI é o design de sistemas que integram Large Language Models (LLMs) em aplicações enterprise, combinando retrieval, geração e orquestração para criar soluções inteligentes.

• Dados Atualizados: Acesso a informações além do training cutoff
• Privacidade: Dados sensíveis sem fine-tuning
• Auditabilidade: Rastreamento de fontes e decisões
• Escalabilidade: Arquitetura modular e extensível
• Custo-Eficiência: RAG vs Fine-tuning = 10x mais barato

Vibe coding é escrever código deixando o agente decidir a maior parte da implementação a partir de instrução solta, aceitando o resultado sem revisão estruturada e iterando por tentativa até parecer funcionar. Funciona para prototipagem e script descartável. Não escala para sistema que precisa ser mantido, revisado por outra pessoa ou auditado.

Desenvolvimento assistido com engenharia difere em três pontos: existe especificação antes do código, existe revisão contra critério definido, e existe rastreabilidade de por que cada decisão foi tomada — o mesmo princípio que já vale para decisão de arquitetura em geral.

Harness é a infraestrutura que envolve o modelo e determina como o agente age no mundo: o loop de execução que decide quando parar e continuar, o sistema de permissão que define o que roda sem aprovação, o sandbox que isola execução de código arbitrário, e a camada que decide o que entra e sai da janela de contexto ao longo de uma tarefa longa.

É comum atribuir o comportamento de um agente inteiramente ao modelo, mas na prática o harness pesa tanto quanto ou mais. Dois agentes com o mesmo modelo e harness diferente produzem confiabilidade bem distinta, porque um harness bom decide corretamente quando parar para confirmar, quando reverter ação malsucedida, e quando o contexto acumulado precisa ser resumido sem perder informação crítica.

• Loop de execução Sequência ação, observação, próxima ação — e quando considerar a tarefa concluída.
• Sistema de permissão O que executa livre, o que exige confirmação, o que é proibido. Escrita em arquivo e execução de rede não são a mesma coisa.
• Sandbox Isola a execução do ambiente real, para que ação incorreta não tenha efeito irreversível fora do escopo.
• Gestão de contexto Decide o que permanece, o que é resumido e o que é descartado conforme o histórico cresce.

Prompt engineering trata de como formular uma instrução isolada. Context engineering trata de um problema mais amplo: o que compõe a janela de contexto ao longo de uma tarefa com dezenas de passos, chamadas de ferramenta e resultado intermediário.

Numa sessão longa o contexto acumula histórico de ação, resultado de ferramenta, arquivo lido e erro corrigido. Manter tudo estoura a janela ou infla o custo por chamada. Descartar sem critério faz o agente perder informação relevante para a próxima decisão. A disciplina é decidir isso de forma sistemática.

• Sumarização progressiva Resumir passos concluídos que não precisam mais do detalhe original, mantendo só a conclusão.
• Recuperação sob demanda Em vez de manter todo arquivo lido na janela, indexar e buscar de volta quando necessário — RAG dentro do próprio fluxo do agente.
• Particionamento por subtarefa Delegar parte do trabalho a uma execução com contexto isolado, devolvendo só o resultado relevante.

Escrever, antes do código, uma descrição estruturada do que precisa ser construído — precisa o suficiente para um agente executar com fidelidade e para um humano revisar o resultado contra ela depois.

Não é requisito tradicional reaproveitado. Uma especificação boa para agente precisa ser explícita sobre o que instrução informal deixa implícito: contrato de entrada e saída, casos de borda, o que está fora de escopo, e critério de aceite verificável.

Objetivo: validar CPF recebido no cadastro de cliente

Contrato:
  entrada: string
  saida: booleano + mensagem de erro quando invalido

Casos de borda:
  CPF com formatacao (pontos e traco) deve ser aceito
  CPF so com zeros deve ser rejeitado
  CPF com digito verificador incorreto deve ser rejeitado

Fora de escopo:
  Verificacao de CPF ativo na Receita Federal

Criterio de aceite:
  Passa nos 12 casos de cpf_test_cases.json

AGENTS.md é a convenção de documentar, num arquivo na raiz do projeto, o contexto que um agente precisa para operar naquele repositório: convenção de código, comando de build e teste, estrutura de pastas, e restrição que não fica óbvia só lendo o código.

Agent Skills empacota um procedimento reutilizável — instruções e às vezes ferramentas próprias — que o agente consulta sob demanda, em vez de carregar tudo na instrução inicial de toda tarefa.

Avaliar código gerado por agente exige critério além de compilou ou passou no teste escrito às pressas depois. Dois eixos importam.

• Correção O código atende à especificação, incluindo os casos de borda explicitados nela — não só o caminho feliz.
• Robustez contra fuga de escopo Teste deliberado de cenário em que o agente, sob ambiguidade, produz algo fora do escopo: implementa função não pedida porque pareceu fazer sentido, ou ignora restrição declarada.