DEV Community

Cover image for Não Dê Mais Prompts ao Seu Agente de Programação. Crie o Loop que os Gera Automaticamente
Lucas
Lucas

Posted on • Originally published at apidog.com

Não Dê Mais Prompts ao Seu Agente de Programação. Crie o Loop que os Gera Automaticamente

Você não deveria mais estar apenas escrevendo prompts para agentes de codificação. O ganho real vem de projetar loops que instruem, executam, verificam e corrigem o trabalho do agente automaticamente. Desenvolvedores que extraem valor consistente de agentes de codificação de IA não tratam o agente como um chat. Eles o tratam como um worker dentro de um fluxo controlado por testes.

Experimente o Apidog hoje

TL;DR

Um loop de agente de codificação executa este ciclo:

  1. O agente gera uma alteração.
  2. O código é executado.
  3. Um portão determinístico verifica o resultado.
  4. A falha volta para o agente como feedback.
  5. O ciclo repete até passar ou atingir um limite.

O ponto crítico não é o agente. É o portão de verificação.

Um portão vago, como “revise e tente novamente”, faz o agente divagar. Um portão determinístico, como teste falho, contrato quebrado ou schema inválido, faz o loop convergir.

Para APIs e backend, seu conjunto de testes automatizados, validações de schema e testes de contrato são esse portão. Por isso, teste de API deve estar no centro do fluxo agêntico, não no final.

De prompts a loops

Com prompts manuais, você é o loop:

  1. Escreve a solicitação.
  2. Lê a resposta.
  3. Encontra o bug.
  4. Cola o erro no chat.
  5. Espera a próxima tentativa.

O agente gera código em segundos, mas fica parado enquanto você alterna contexto, lê logs e formula o próximo prompt.

Um loop automatizado remove você do ciclo interno:

  1. O agente escreve o código.
  2. Um script executa testes ou validações.
  3. O resultado é capturado.
  4. Se falhar, a falha vira o próximo feedback do agente.
  5. O processo continua até ficar verde ou parar por limite.

Você intervém nas bordas: define a tarefa, aprova o resultado e interrompe execuções problemáticas.

A Anthropic descreve uma ideia parecida em building effective agents: o valor vem mais do ambiente construído ao redor do modelo do que de um único prompt melhor.

A pergunta muda de:

O que devo dizer ao agente?

para:

Que loop faria o agente receber o feedback certo sozinho?

O que é um loop de agente de codificação

Um loop útil tem cinco partes.

1. Especificação da tarefa

A tarefa precisa definir o que significa “concluído”.

Ruim:

Faça o endpoint de pedidos funcionar.
Enter fullscreen mode Exit fullscreen mode

Melhor:

Implemente POST /orders.

Critérios:
- retorna 201 quando o pedido é criado
- valida o body contra o schema OpenAPI
- retorna 422 quando customer_id estiver ausente
- retorna total como number
- não aceita campos desconhecidos
Enter fullscreen mode Exit fullscreen mode

2. Agente

É o modelo com ferramentas: ler arquivos, editar código, executar comandos, consultar logs etc.

Essa é a parte mais visível, mas não a mais importante.

3. Etapa de ação

O agente altera algo e o sistema executa:

  • testes unitários
  • build
  • type check
  • lint
  • teste de API
  • chamada contra um endpoint
  • validação de contrato

4. Portão de verificação

É a checagem que decide se passou ou falhou.

Exemplos:

  • pytest retorna código 1
  • schema JSON não bate
  • OpenAPI diverge da implementação
  • endpoint retorna 500 quando deveria retornar 422
  • build falha
  • contrato de API quebra

5. Condição de término

O loop precisa parar quando:

  • o portão passa
  • o número máximo de tentativas é atingido
  • o orçamento estoura
  • uma falha exige revisão humana

Sem isso, você não tem um workflow. Você tem um processo descontrolado.

Um loop mínimo fica assim:

task = load_spec("orders-endpoint.md")
last_result = None

for attempt in range(MAX_ITERATIONS):
    agent.run(task, feedback=last_result)   # gera ou corrige código

    result = run_verification()             # executa o portão

    if result.passed:
        break                               # sucesso

    last_result = result.failures           # falhas viram feedback
else:
    escalate_to_human(last_result)          # limite atingido
Enter fullscreen mode Exit fullscreen mode

Essa é a essência. O agente gera, o portão julga, a falha volta como prompt.

A técnica conhecida como “Ralph” segue essa mesma estrutura, normalmente com MAX_ITERATIONS alto e uma especificação curta. Se você leu a análise sobre arquitetura do harness do agente, este é o padrão em sua forma mais simples.

Por que prompting único falha

Um único prompt assume duas coisas:

  1. O modelo vai acertar de primeira.
  2. Você vai perceber tudo que ele errou.

Essas duas suposições quebram rápido.

Modelos geram código plausível. Isso não significa código correto.

Um agente pode criar um endpoint que:

  • compila
  • parece coerente
  • passa em um caso feliz
  • mas retorna o status errado em um caso de borda
  • ou viola o schema
  • ou ignora autenticação
  • ou aceita payload inválido

Em um chat, você talvez só perceba isso depois. Em produção, tarde demais.

Um loop resolve esse problema recusando a opinião do modelo sobre o próprio trabalho. O agente não decide que terminou. O portão decide.

Se os testes estão vermelhos, a tarefa não acabou.
Se o contrato quebrou, a tarefa não acabou.
Se o schema divergiu, a tarefa não acabou.
Enter fullscreen mode Exit fullscreen mode

A confiança do modelo deixa de importar. O sinal importa.

Também há um ganho operacional: com prompts manuais, você só consegue supervisionar ativamente um agente por vez. Com loops, você pode rodar vários agentes em paralelo, cada um com sua tarefa e seu portão. Essa é a lógica por trás de fluxos de trabalho de agentes dinâmicos e paralelos: escalar adicionando loops, não digitando mais rápido.

O portão de verificação é a parte mais importante

A maioria dos workflows agênticos falha porque o feedback é fraco.

Compare estes dois feedbacks.

Fraco:

Algo parece errado. Revise o código.
Enter fullscreen mode Exit fullscreen mode

Útil:

orders.test.ts:42

Esperado:
HTTP 422 quando customer_id estiver ausente

Recebido:
HTTP 500

Stack trace:
ValidationError: Cannot read property 'id' of undefined
Enter fullscreen mode Exit fullscreen mode

O segundo feedback direciona a próxima iteração. O primeiro força o agente a adivinhar.

Portões determinísticos convergem. Portões vagos divagam.

Um bom portão tem estas propriedades:

  • Binário e reproduzível: mesma entrada, mesmo resultado.
  • Falha com motivo específico: nome do teste, diff, linha, status, schema, stack trace.
  • Não pode ser alterado silenciosamente pelo agente: testes e especificações devem ser protegidos.
  • Roda rápido o suficiente: um portão de 20 minutos é ruim para loop interno.
  • Representa a verdade do produto: não apenas checks superficiais.

Você provavelmente já tem bons portões:

  • testes unitários
  • type checks
  • linters
  • compiladores
  • validadores de schema
  • testes de contrato
  • testes de API
  • pipelines de CI

Eles foram criados para dizer a humanos “isso está errado e aqui está o motivo”. Esse é exatamente o sinal que um agente precisa.

Se sua base ainda não tem essa camada formalizada, comece por entender o que realmente é teste automatizado antes de conectar agentes a ela.

Para APIs e backend, seus testes são o loop

Quando um agente implementa uma API, a verdade não é o resumo que ele escreve no chat.

A verdade é o comportamento real do endpoint:

  • status code correto
  • body compatível com o schema
  • autenticação aplicada
  • entrada inválida rejeitada
  • contrato OpenAPI respeitado
  • erros retornados no formato esperado
  • campos obrigatórios validados

Tudo isso pode ser verificado automaticamente.

Um loop para endpoint pode seguir este fluxo:

  1. O agente lê a tarefa e a definição OpenAPI.
  2. Ele implementa ou altera o endpoint.
  3. O serviço sobe localmente ou em ambiente de teste.
  4. O conjunto de testes de API roda.
  5. O portão valida status, body, schema e contrato.
  6. As falhas voltam estruturadas para o agente.
  7. O agente corrige.
  8. O ciclo repete até passar ou atingir o limite.

Exemplos de feedback útil:

POST /orders

Esperado:
422 quando customer_id estiver ausente

Recebido:
500
Enter fullscreen mode Exit fullscreen mode 
GET /orders/123

Campo:
total

Esperado pelo schema:
number

Recebido:
string
Enter fullscreen mode Exit fullscreen mode 
OpenAPI define:
GET /orders/{id}

Mas a implementação não expõe essa rota.
Enter fullscreen mode Exit fullscreen mode

Esse tipo de feedback é gerado por máquina, específico e acionável.

É por isso que teste de contrato e abordagem schema-first ficam ainda mais importantes em workflows agênticos. A especificação OpenAPI vira a fonte compartilhada de verdade para o agente e para o portão.

Quando código e especificação divergem, o problema deixa de ser uma documentação desatualizada e vira um portão vermelho imediatamente.

Esse é o papel do Apidog em um fluxo agêntico de API: manter design, schema, mock server e testes automatizados no mesmo lugar.

Na prática, isso permite:

  • definir o contrato da API
  • criar cenários de teste
  • validar respostas contra schema
  • usar mock server para dependências ainda não implementadas
  • rodar testes como portão do loop
  • entregar falhas estruturadas ao agente

Equipes que seguem esse padrão podem conectar o acesso às ferramentas do agente com algo como o depurador de agente de IA do Apidog, para que o agente inspecione endpoints de forma parecida com um testador humano.

Se você quer construir esse portão visualmente em vez de montar um executor manual do zero, baixe o Apidog.

Construa um loop de API mínimo hoje

Você não precisa começar com um framework complexo. Use três peças:

  1. Uma especificação.
  2. Um comando de teste.
  3. Um script que conecta agente e portão.

Etapa 1: escreva a especificação

Crie um arquivo de tarefa com critérios verificáveis.

# Tarefa: implementar POST /orders

## Contrato

Usar a definição OpenAPI em `openapi.yaml`.

## Critérios de aceite

- POST /orders retorna 201 com pedido criado
- customer_id é obrigatório
- ausência de customer_id retorna 422
- total deve ser number
- resposta deve validar contra o schema `Order`
- payload com campos desconhecidos deve ser rejeitado
Enter fullscreen mode Exit fullscreen mode

A regra é simples: se não pode ser verificado, está vago demais.

Etapa 2: escolha um comando de teste

O comando precisa retornar código diferente de zero quando falhar.

Pode ser:

  • pytest
  • Newman
  • Jest
  • Playwright API tests
  • Apidog CLI
  • um script interno
  • pipeline local de contrato

Exemplo:

apidog run ./tests/orders-suite --reporter json > result.json
Enter fullscreen mode Exit fullscreen mode

O loop só precisa de duas coisas:

  • exit code
  • saída com falhas legíveis

Etapa 3: conecte o loop

Exemplo simplificado:

import subprocess

MAX_ITERATIONS = 8

task = """
Implemente a API de pedidos conforme openapi.yaml.
Não altere os arquivos de teste nem a especificação.
Corrija apenas a implementação.
"""

feedback = None

for attempt in range(MAX_ITERATIONS):
    run_agent(
        task=task,
        feedback=feedback
    )

    gate = subprocess.run(
        [
            "apidog",
            "run",
            "./tests/orders-suite",
            "--reporter",
            "json"
        ],
        capture_output=True,
        text=True
    )

    if gate.returncode == 0:
        print(f"verde na tentativa {attempt + 1}")
        break

    feedback = parse_failures(gate.stdout)

else:
    print("8 tentativas e ainda vermelho; escalando para humano")
Enter fullscreen mode Exit fullscreen mode

A função parse_failures deve transformar o resultado bruto em feedback direto.

Exemplo:

def parse_failures(stdout: str) -> str:
    failures = extract_failed_assertions(stdout)

    return "\n".join([
        f"""
Falha: {failure.name}
Endpoint: {failure.endpoint}
Esperado: {failure.expected}
Recebido: {failure.actual}
Detalhes: {failure.message}
"""
        for failure in failures
    ])
Enter fullscreen mode Exit fullscreen mode

O objetivo não é gerar um relatório bonito. É gerar o próximo prompt útil.

Etapa 4: proteja o portão

O agente não deve poder editar:

  • arquivos de teste
  • openapi.yaml
  • schemas
  • fixtures críticas
  • scripts de validação
  • configuração do portão

Se ele puder mudar o teste para passar, o loop vira uma máquina de falsificar progresso.

Uma forma simples de proteger:

Arquivos permitidos:
- src/**
- app/**
- package.json, apenas se necessário

Arquivos proibidos:
- tests/**
- openapi.yaml
- schemas/**
- apidog/**
Enter fullscreen mode Exit fullscreen mode

Também vale rodar uma verificação antes do commit:

git diff --name-only | grep -E "^(tests|schemas|openapi.yaml)" && exit 1
Enter fullscreen mode Exit fullscreen mode

Etapa 5: limite custo e tempo

Sempre defina:

  • máximo de iterações
  • timeout por tentativa
  • limite de tokens ou custo
  • logs por execução
  • regra de escalada para humano

Exemplo:

MAX_ITERATIONS = 8
MAX_SECONDS_PER_ATTEMPT = 180
MAX_TOTAL_COST_USD = 5
Enter fullscreen mode Exit fullscreen mode

Se o loop não converge, pare. Um agente preso em falhas repetidas consome orçamento rápido. As práticas de redução de custos de tokens do agente se aplicam diretamente aqui.

Erros comuns ao projetar loops

1. Deixar o agente validar a própria conclusão

Ruim:

Você terminou? Revise seu trabalho.
Enter fullscreen mode Exit fullscreen mode

Isso não é loop. É um chatbot com etapas extras.

O portão deve ser externo ao agente.

2. Usar testes superficiais

Se o portão só cobre três casos felizes, o agente otimiza para esses três casos.

Resultado:

  • testes verdes
  • comportamento incompleto
  • bugs fora da cobertura

A qualidade do loop é limitada pela qualidade do portão.

3. Não definir condição de término

Todo loop precisa de saída.

Sem limite, uma tarefa impossível vira consumo infinito de tempo e dinheiro.

Use:

MAX_ITERATIONS = 8
Enter fullscreen mode Exit fullscreen mode

E escale para humano quando o limite for atingido.

4. Usar portão lento demais

Um conjunto de integração de 15 minutos pode ser bom para CI noturno, mas ruim para loop interno.

Divida os portões:

  • portão rápido para iteração do agente
  • portão completo para merge
  • portão noturno para suíte pesada

Mocks ajudam a evitar dependências externas instáveis.

5. Permitir que o agente altere a especificação

Se o agente muda o OpenAPI para combinar com código bugado, o contrato fica verde pelo motivo errado.

A especificação é a constituição. O agente trabalha sob ela, não sobre ela.

6. Criar tarefas grandes demais

Ruim:

Construa todo o serviço de pedidos.
Enter fullscreen mode Exit fullscreen mode

Melhor:

Implemente POST /orders com validação de schema.
Enter fullscreen mode Exit fullscreen mode

Loops pequenos terminam. Loops grandes travam.

Esse padrão se alinha com os cuidados descritos em cabeamento de ferramentas para fluxo de trabalho agêntico, independentemente de você usar Claude Code, Cursor, Codex ou um agente próprio.

Como aplicar isso no seu projeto

Use este checklist para começar.

Checklist do loop mínimo

  • [ ] A tarefa tem critérios de aceite objetivos.
  • [ ] Existe um schema ou contrato claro.
  • [ ] O comando de teste retorna exit code correto.
  • [ ] As falhas são específicas e legíveis.
  • [ ] O agente não pode editar o portão.
  • [ ] Há limite de iterações.
  • [ ] Há timeout.
  • [ ] Há logs por tentativa.
  • [ ] Há escalada para humano.
  • [ ] O portão roda rápido o suficiente.

Exemplo de estrutura de arquivos 

project/
  openapi.yaml              # contrato protegido
  tests/
    orders-suite/           # portão protegido
  src/
    orders/                 # agente pode editar
  agent-loop/
    task.md                 # especificação da tarefa
    loop.py                 # executor do loop
Enter fullscreen mode Exit fullscreen mode

Exemplo de prompt inicial para o agente 

Você deve implementar a tarefa descrita em agent-loop/task.md.

Regras:
- leia openapi.yaml
- altere apenas arquivos em src/**
- não altere tests/**
- não altere openapi.yaml
- rode a implementação conforme o feedback recebido
- corrija somente as falhas reportadas pelo portão
Enter fullscreen mode Exit fullscreen mode

Depois disso, o próximo prompt não precisa vir de você. Ele vem do portão.

Para onde isso está indo

“Pare de dar prompts, comece a usar loops” resume uma mudança maior.

A habilidade valiosa deixa de ser apenas escrever prompts bons. Passa a ser projetar sistemas que dão feedback correto ao agente.

Isso envolve:

  • escrever especificações claras
  • criar portões determinísticos
  • proteger contratos
  • decompor tarefas
  • definir limites
  • integrar testes ao fluxo
  • decidir o que o agente pode editar

Isso está mais perto de design de sistemas do que de “engenharia de prompt”.

Também muda o valor dos testes automatizados. Antes, eles eram vistos como seguro contra regressões. Em workflows agênticos, eles viram o mecanismo de direção.

Um modelo é um gerador rápido, mas não confiável. O portão transforma esse gerador em um sistema que converge.

Equipes com boa cobertura de testes automatizados, contratos limpos e APIs bem especificadas conseguem adotar agentes com mais segurança. Equipes sem isso ganham apenas uma forma mais rápida de gerar código não verificado.

Conclusão

Não foque apenas em melhorar seus prompts para agentes de codificação. Foque em projetar o loop que controla o agente.

O agente gera. O portão verifica. A falha orienta. O limite encerra.

Para quem constrói APIs, o portão provavelmente já existe:

  • testes de API
  • schemas
  • contratos OpenAPI
  • validações automatizadas
  • pipelines de CI

Comece pequeno:

  1. Escolha um endpoint.
  2. Escreva uma especificação curta.
  3. Crie ou selecione uma suíte rápida de testes de API.
  4. Proteja o contrato e os testes.
  5. Rode um loop com limite de tentativas.
  6. Faça o agente corrigir até o portão ficar verde.

Se você quer que esse portão seja visual, consciente de schema e compartilhável com o time, o Apidog reúne design, mocking e testes automatizados em um único workspace. Baixe o Apidog e use seus testes como o mecanismo que direciona seus agentes.

Top comments (0)