Engenharia de Prompt, Contexto, Harness e Loop: quatro camadas para sistemas de IA confiáveis

Se você já colocou em produção algo além de um chat simples, provavelmente sentiu a distância entre uma demo impressionante e um software em que dá para confiar. O modelo responde com segurança, mas o JSON vem inválido. A busca traz o documento errado. O agente entra em loop. Uma linha a mais no prompt corrige o bug de terça e quebra a feature de quarta.

Muitos times juntam tudo isso em “engenharia de prompt”, como se confiabilidade fosse encontrar a frase mágica. Na prática, sistemas de IA em produção são construídos em quatro camadas distintas: engenharia de prompt, engenharia de contexto, engenharia de harness e engenharia de loop. Cada uma resolve um tipo diferente de falha. Misturar os papéis gera sistemas frágeis e um ciclo infinito de ajuste de prompt.

Este artigo mostra o que cada camada cuida, onde elas se sobrepõem e como aplicá-las em stacks que você já usa—Nuxt e Vue no front, Laravel ou Node na API, TypeScript no meio do caminho.

Engenharia de prompt: a camada de instrução

Engenharia de prompt é o ofício de dizer ao modelo qual tarefa executar e como executá-la. Isso inclui instruções de sistema, definição de papéis, expectativa de formato, exemplos few-shot e regras expressas em linguagem natural.

Um bom prompt é específico sem ser rígido demais. Em vez de “resuma isso”, defina público, tamanho, tom e o que fazer quando faltar informação. Em tarefas estruturadas, descreva o schema em linguagem clara e mostre um exemplo completo do comportamento esperado.

Prompt bem feito é necessário, mas não basta. Instruções perfeitas não compensam fatos ausentes no contexto, ferramentas mal conectadas no harness ou um loop sem condição de parada. Trate prompts como contratos: claros, testáveis e versionados como qualquer outra superfície de API.

Sinais de que você está apostando demais no prompt:

Todo bug vira um system message maior.
Os exemplos multiplicam até o prompt custar mais que a tarefa.
O comportamento muda ao reordenar parágrafos, não ao mudar dados.
Só quem não é dev consegue “consertar” o modelo.

Hábitos práticos: guarde prompts no código ou em um CMS, não em threads de Slack. Nomeie versões. Associe cada prompt a casos de eval: dado este input, espere este formato de saída. Em serviços TypeScript, mantenha prompts perto dos tipos que eles produzem, para que desvios apareçam em compile time quando possível.

Engenharia de contexto: a camada de informação

Engenharia de contexto decide o que o modelo enxerga antes de gerar o primeiro token. Entram mensagens do usuário, histórico, documentos recuperados, resultados de ferramentas, resumos de memória, metadados e até qual modelo chamar.

Contexto é orçamento, não depósito. Cada token compete por atenção. Enfiar dez PDFs na janela porque a retrieval foi preguiçosa é falha de contexto, não de prompt. O trabalho difícil é seleção, ranking, compressão e atualidade.

Padrões comuns:

RAG com limites: recuperar top-k trechos, citar fontes e instruir o modelo a dizer “não sei” quando a evidência for fraca.
Memória estruturada: preferências no banco; injete só o que importa neste turno.
Resultado de tool enxuto: resumo JSON para o modelo, não payload bruto de 50 KB.
Janela dinâmica: histórico curto para respostas rápidas; histórico expandido mais docs para tarefas complexas.

Em Laravel, a montagem de contexto costuma ficar em um serviço dedicado: consulta o vector store, hidrata models Eloquent, corta pelo limite de tokens e entrega o pacote ao client LLM. No Nuxt, monte contexto na server route ou na API—nunca exponha chaves de retrieval ou repositórios completos no browser.

Sinais de que o contexto precisa de engenharia:

O modelo inventa detalhes que existem na empresa, mas não no prompt.
Respostas boas com input pequeno pioram conforme a thread cresce.
Recall ok, precisão ruim.
Latência dispara porque você manda tudo “por garantia”.

Engenharia de harness: a camada de execução

O harness é tudo que envolve o modelo para a saída ficar segura, parseável e acionável na aplicação. O modelo propõe; o harness impõe.

Engenharia de harness inclui definição de tools e schemas JSON, modos de saída estruturada, validadores, retries com prompt de correção, chaves de idempotência, logs, tracing, rate limit e fallback quando o provider falha. Se você já usou Zod para rejeitar JSON do LLM e devolveu o erro num retry, estava fazendo trabalho de harness.

Um harness mínimo para triagem de tickets, em conceito:

Defina um tipo TypeScript TriageResult com enum de prioridade e campos obrigatórios.
Chame o modelo com saída estruturada ou prompt JSON estrito.
Faça parse com Zod; se falhar, uma passagem de repair com o erro de validação.
Se ainda inválido, encaminhe para fila humana—nunca aceite dado ruim em silêncio.
Persista completion bruta e resultado parseado para auditoria.

No front Vue ou Nuxt, o harness continua: desabilite submit durante streaming, trate JSON parcial com cuidado, mostre proveniência e não confie só no parse no cliente. O servidor valida de novo.

Sinais de harness fraco:

Produção quebra quando o modelo coloca markdown fence no JSON.
Tools são chamadas com argumentos inventados.
Não há correlation ID ligando ação do usuário, retrieval e completion.
Retries aumentam custo sem melhorar taxa de sucesso.

Invista no harness com a mesma disciplina de processamento de pagamento. O modelo é não determinístico; seus limites não devem ser.

Engenharia de loop: a camada de fluxo de controle

Engenharia de loop define quantas vezes o modelo roda, o que acontece entre rodadas e quando o sistema para. Completion em uma tacada é o loop mais simples. Agentes são loops com ramificações: planejar, agir, observar, refletir, repetir.

Loops aparecem em tool use estilo ReAct, codegen multi-etapa, edição iterativa de documentos, refinamento guiado por eval e fluxos com aprovação humana. As decisões são condição explícita de parada, máximo de passos, caminho de escalonamento e estado passado de uma iteração para outra.

Um loop robusto responde de antemão:

Parar quando: tarefa concluída, limiar de confiança, cancelamento, orçamento esgotado ou sem progresso em N passos.
Estado: o que fica no rascunho versus o que vai para o banco.
Observabilidade: dá para replayar o passo 3 de 7 de uma execução que falhou?
Portões humanos: quais ações exigem aprovação antes de efeito colateral?

Bug de loop sai caro. Agente que não termina queima token e confiança. Um que para cedo deixa trabalho pela metade. Prefira loops determinísticos no serviço Node ou Laravel, com o modelo como função de passo—não o contrário.

Sinais de que o loop precisa de atenção:

Usuário reporta “ficou pensando para sempre”.
A mesma tool é chamada de novo sem informação nova.
Retry, replanejar e escalar são a mesma coisa.
Não dá para limitar custo por sessão.

Como as quatro camadas se combinam

Pense numa pilha vertical. Prompt define intenção e formato. Contexto traz fatos fundamentados dentro do orçamento. Harness transforma geração em efeito tipado e validado. Loop orquestra passagens repetidas até o resultado de negócio ou aborto seguro.

Quando algo falhar, diagnostique por camada antes de editar o system prompt:

Fatos errados → contexto (retrieval, memória, corte).
Fatos certos, estrutura errada → harness (schema, parser, repair).
Passos válidos, sem convergência → loop (parada, replanejamento, gate humano).
Mal-entendido consistente da tarefa → prompt (instruções, exemplos).

Exemplo: assistente admin em Nuxt que atualiza copy de produto. O prompt define voz da marca e campos JSON. O contexto traz o registro atual e a seção do guia de estilo—not o CMS inteiro. O harness valida slugs e limites de caracteres e grava via API Laravel com idempotência. O loop redige, auto-verifica com checklist e para após duas revisões ou pede aprovação do editor se a confiança for baixa.

Checklist de produção para times full-stack

Antes de lançar a próxima feature de IA, percorra esta lista com o time:

Prompts versionados, revisados e com fixtures de eval.
Contexto com orçamento de tokens, citação de fontes e tratamento de dado stale.
Harness validando toda saída visível externamente no servidor.
Loops com limite rígido de passos, teto de custo e UX de falha graceful.
Transversal: traces ligando user ID, IDs de retrieval, IDs de chamada ao modelo e ação final.

Os times que saem na frente não são os do system prompt mais longo. São os que tratam IA como sistema distribuído: instrução, informação, enforcement e fluxo de controle—cada um engenheirado de propósito.

Comece pela dor mais aguda. Se a resposta soa plausível mas está errada, arrume contexto. Se a UI quebra com formatação estranha, arrume harness. Se a demo encanta mas a sessão nunca termina, arrume loop. Só então gaste mais uma hora lapidando prompt. Essa ordem economiza mais tempo do que qualquer frase brilhante isolada.