Loop self-correcting de agente no CI seguro

Q: O que o agente deve receber do log?

Receba o mínimo que reproduz a falha. Em 2026, a OpenAI documentou eventos JSON Lines no codex exec. Fonte: https://developers.openai.com/codex/noninteractive Consultado em 2026-07-08. Isso favorece comando, status, arquivo de log, diff e próxima ação, sem despejar o log inteiro.

Loop self-correcting de agente no CI é o fluxo em que uma falha verificável volta para Codex, Claude Code ou outro agente com contexto mínimo, escopo curto e critério de parada. O objetivo não é deixar o agente mandar no pipeline. É fazer o CI devolver prova suficiente para um reparo pequeno e revisável.

Em 2026, a GitLab relatou que 85% dos respondentes veem a revisão e a validação como o novo gargalo do código gerado por IA (GitLab, "AI Accountability Report", 2026, consultado em 2026-07-08). Se o agente cria PRs mais rápido, o pipeline precisa responder com evidência, não com mais conversa.

Resumo prático

O loop deve receber falha, log curto, comando e limite de tentativas.

O agente só deve tocar o menor escopo que explica a falha.

O PR precisa mostrar teste, comando executado e risco residual.

Quando a segunda tentativa falha pelo mesmo motivo, chame uma pessoa.

Diagrama abstrato mostra um agente, um ciclo de validação e status de CI sem texto visível.

Por que o loop de reparo no CI virou prioridade?

Em 2026, a GitLab mediu 91% das organizações usando duas ou mais ferramentas de IA para código e 78% relatando escrita e commit mais rápidos (GitLab, "AI Accountability Report", 2026, consultado em 2026-07-08). A prioridade virou reparo no CI porque a geração acelerou antes da verificação.

O erro é tratar falha de CI como uma mensagem para o humano traduzir manualmente. Em fluxo agentic, a falha já deve nascer como entrada de máquina: comando, trecho de log, arquivos tocados, limite de escopo e motivo de bloqueio. Isso reduz a chance de um agente tentar "melhorar" áreas que não falharam.

Esse post continua a linha de evals de PR para agentes no CI e de spec executável para agentes de código. A diferença é o momento: aqui o foco está depois da falha, quando o pipeline precisa devolver feedback que o agente consiga executar.

Cápsula citável: Loop self-correcting no CI é uma resposta ao gargalo de validação. A GitLab relatou 85% vendo revisão e validação como gargalo (GitLab, "AI Accountability Report", 2026); por isso, cada falha precisa virar feedback estruturado, com comando, log mínimo, escopo e limite de tentativas.

Qual é o contrato mínimo de um loop self-correcting?

Em 2026, a DORA registrou que 90% dos profissionais de tecnologia usam IA no trabalho e que mais de 80% acreditam que ela aumentou sua produtividade (DORA, "Balancing AI tensions", 2026, consultado em 2026-07-08). O contrato mínimo existe para transformar essa produtividade em mudança verificável.

Um loop bom tem cinco campos. Primeiro, a falha que disparou o fluxo. Segundo, o comando que reproduz a falha. Terceiro, o escopo de arquivos autorizado. Quarto, o critério de sucesso. Quinto, a regra de parada. Sem isso, o agente recebe uma exceção e inventa um projeto.

falha:
  comando: "npm run test -- session-renewal"
  evidencia: ".ci/failures/session-renewal.log"
escopo_autorizado:
  - "src/auth/session.service.ts"
  - "tests/auth/session-renewal.spec.ts"
sucesso:
  - "o comando que falhou passa novamente"
  - "npm run typecheck continua passando"
limites:
  tentativas: 2
  sem_migracao_de_banco: true
  sem_mudanca_em_segredos: true
parar_se:
  - "a mesma falha aparecer duas vezes"
  - "o patch tocar arquivo fora do escopo"
  - "a correcao exigir segredo ou acesso externo"

Esse contrato pode ficar em uma issue, em um comentário de PR ou em um artefato gerado pelo CI. O ponto é não depender de memória do chat. Para fluxos longos com Codex e Claude Code, eu uso o RemoteCode para reduzir contexto repetido em loops agentic de código porque é uma ferramenta minha e se encaixa exatamente nesse problema de custo e continuidade.

Experiência prática: quando testei esse padrão em tarefas de backend, o loop só ficou útil depois que a falha passou a carregar escopo e regra de parada. Antes disso, o agente tendia a corrigir sintomas próximos e criar diffs que pareciam bons, mas eram difíceis de revisar.

Cápsula citável: O contrato mínimo de reparo tem falha, comando, escopo, sucesso e parada. A DORA mediu adoção de IA por 90% dos profissionais (DORA, "Balancing AI tensions", 2026); sem contrato, essa adoção amplia produtividade local e retrabalho no pipeline.

Como o CI entrega feedback útil sem despejar contexto?

Em 2026, a OpenAI documentou que codex exec roda Codex em scripts e CI, com eventos em JSON Lines para mensagens, comandos, mudanças de arquivo, chamadas MCP e falhas (OpenAI Developers, "Non-interactive mode", 2026, consultado em 2026-07-08). Feedback útil é pequeno, estruturado e consumível por ferramenta.

Não envie o log inteiro de um job de vinte minutos. Envie o comando que falhou, as últimas linhas relevantes, o caminho do relatório, o diff do PR e a política de escopo. O agente pode ler mais se precisar, mas o primeiro pacote deve orientar, não afogar.

Diagrama abstrato mostra sinais de falha sendo convertidos em feedback para reparo sem texto visível.

A OpenAI também publicou um exemplo de reparo iterativo com três fases: revisão, reparo e validação (OpenAI Developers, "Build iterative repair loops with Codex", 2026, consultado em 2026-07-08). O detalhe importante é a separação. Revisar não edita. Reparar não decide sozinho se acabou. Validar devolve o delta restante.

{
  "comando": "npm run test -- session-renewal",
  "status": "falhou",
  "arquivo_log": ".ci/failures/session-renewal.log",
  "arquivos_alterados": [
    "src/auth/session.service.ts",
    "tests/auth/session-renewal.spec.ts"
  ],
  "pedido": "aplique a menor correcao que faca o comando passar"
}

Cápsula citável: Feedback de CI para agente deve ser estruturado, não volumoso. OpenAI documentou codex exec com saída JSON Lines; isso permite transformar falhas em eventos legíveis por máquina, com comando, log, arquivo alterado e próxima ação.

Onde colocar limites para o agente não piorar o PR?

Em 2026, a documentação de codex exec informa que o modo não interativo roda em sandbox somente leitura por padrão e recomenda workspace-write para permitir edição controlada (OpenAI Developers, "Non-interactive mode", 2026, consultado em 2026-07-08). O limite deve ficar antes do agente editar, não depois do dano.

Use runner isolado, token curto, permissões mínimas e branch separada. Em Codex, prefira --sandbox workspace-write para correções em repositório e evite acesso amplo fora de ambiente controlado. Em Claude Code GitHub Actions, restrinja ferramentas, eventos e permissões do workflow ao caso de uso real.

Diagrama abstrato mostra anéis de sandbox, pontos de parada e barreiras de permissão sem texto visível.

A documentação de segurança do Claude Code Action recomenda limitar ferramentas permitidas e usar GITHUB_TOKEN escopado quando usuários sem permissão de escrita são autorizados (Anthropic, "claude-code-action security", 2026, consultado em 2026-07-08). Ela também alerta contra checkout de ref não confiável no workspace antes da action em fluxos com pull_request_target ou workflow_run.

Cápsula citável: O limite de um loop self-correcting deve ser preventivo. Codex usa sandbox somente leitura por padrão em automação, e a Anthropic recomenda permissões mínimas no GitHub Action; juntos, esses controles impedem que uma falha de teste vire mudança ampla.

Como o PR prova que o reparo foi legítimo?

Em 2026, o GitHub relatou que o Copilot code review processou mais de 60 milhões de revisões. O mesmo texto afirma que mais de uma em cada cinco revisões no GitHub envolve um agente (GitHub, "Agent pull requests are everywhere", 2026, consultado em 2026-07-08). O PR precisa provar o reparo porque revisão humana virou gargalo.

Peça evidência curta no corpo do PR. O agente deve mostrar o comando que falhou, o comando que passou, o resumo do patch, o risco residual e o motivo pelo qual não mexeu em áreas vizinhas. Se a correção mudou teste e implementação, a ordem importa: teste que falha, patch, teste que passa.

Evidência no PR	Quem valida	Bloqueia quando
Comando que falhou	CI	Não há reprodução clara.
Patch pequeno	Revisor	Arquivo fora do escopo mudou sem justificativa.
Verificação pós-patch	Branch protection	Teste, typecheck ou build falha.
Risco residual	Code owner	Área sensível mudou sem dono.
Tentativas usadas	Automação	O limite foi estourado.

OpenAI mostrou em um exemplo de tarefa longa que Codex rodou comandos de lint, typecheck, testes, build e exportação durante marcos de verificação (OpenAI Developers, "Run long horizon tasks with Codex", 2026, consultado em 2026-07-08). Esse é o padrão: a narrativa só vale se vier acompanhada da verificação.

Esse cuidado também responde a um risco de manutenção. Em 2026, o estudo "More Code, Less Reuse" encontrou que agentes tendem a perder oportunidades de reúso e introduzir mais redundância em PRs gerados por IA (arXiv, "More Code, Less Reuse", 2026, consultado em 2026-07-08).

Cápsula citável: PR de reparo agentic precisa mostrar prova, não confiança. GitHub relatou mais de 60 milhões de revisões com Copilot code review (GitHub, "Agent pull requests are everywhere", 2026); nesse volume, comando reproduzido, patch pequeno e verificação pós-patch são a linguagem comum entre agente, CI e revisor.

Quando parar o loop e chamar uma pessoa?

Em 2026, a GitLab relatou que 92% enfrentam algum desafio de governança com código gerado por IA. O mesmo relatório diz que 80% adotaram ferramentas de IA mais rápido do que políticas para governá-las (GitLab, "AI Accountability Report", 2026, consultado em 2026-07-08). A regra de parada é parte da governança, não um detalhe operacional.

Pare quando a mesma falha volta duas vezes, quando o patch precisa tocar arquivo fora do escopo ou quando a correção exige segredo. Também pare quando aparece risco de dados, quando o agente muda API pública ou quando a causa parece flake de infraestrutura. Nesses casos, insistir só compra mais diffs para revisar.

A documentação de Goals do Codex descreve objetivo persistente como contrato com condição de conclusão, verificação e restrições, incluindo parada por sucesso, pausa, orçamento ou bloqueio (OpenAI Developers, "Using Goals in Codex", 2026, consultado em 2026-07-08). Essa lógica também serve para CI: o loop precisa saber terminar.

Cápsula citável: Loop self-correcting bom tem parada explícita. Como 92% relatam desafios de governança com código de IA (GitLab, "AI Accountability Report", 2026), a automação deve encerrar quando repete falha, toca escopo proibido, exige segredo ou encontra risco que precisa de julgamento humano.

O que implementar nesta semana?

Em 2025, a OpenAI publicou um cookbook que aciona Codex quando um workflow de GitHub Actions termina com falha. O exemplo cria um PR de correção a partir do branch quebrado (OpenAI Developers, "Use Codex CLI to automatically fix CI failures", 2025, consultado em 2026-07-08). O mínimo viável é começar revisável, não totalmente autônomo.

Implemente três peças. Primeiro, salve logs reduzidos em .ci/failures/. Segundo, crie um job que roda só em falha e abre PR em branch separada. Terceiro, exija que o PR inclua comandos executados e limite de tentativas. Não faça auto-merge no primeiro ciclo.

name: agente-repara-ci
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
permissions:
  contents: write
  pull-requests: write
jobs:
  reparar:
    if: $false
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: node scripts/ci/resumir-falha.mjs
      - run: codex exec --sandbox workspace-write "$(cat .ci/failures/prompt.txt)"
      - run: npm test

Depois conecte branch protection, code owners e um comentário automático com a evidência. Se o segundo reparo falhar, rotule o PR como bloqueado para revisão humana. O ganho vem do ciclo curto, não de fingir que o agente virou responsável pelo sistema.

Cápsula citável: O primeiro loop de reparo deve abrir PR revisável, não fazer merge sozinho. OpenAI publicou um fluxo de Codex para falhas de CI; a versão prudente salva log curto, roda sandbox, limita tentativas e entrega evidência para branch protection.

Perguntas frequentes sobre loop self-correcting no CI

Loop self-correcting substitui code review humano?

Não. Em 2026, o GitHub relatou mais de uma em cada cinco revisões envolvendo agente (GitHub, "Agent pull requests are everywhere", 2026, consultado em 2026-07-08). Isso reforça a revisão humana onde há risco de API, segurança, dados ou arquitetura.

Quantas tentativas o agente deve ter?

Duas tentativas são um bom padrão inicial. Em 2026, a GitLab relatou 85% vendo validação como gargalo (GitLab, "AI Accountability Report", 2026, consultado em 2026-07-08). Se a segunda tentativa falha pelo mesmo motivo, falta contexto ou julgamento humano.

Posso usar `danger-full-access` em CI?

Só em runner isolado e controlado. Em 2026, a OpenAI documentou danger-full-access como opção para ambiente controlado e recomendou workspace-write para novas automações (OpenAI Developers, "Non-interactive mode", 2026, consultado em 2026-07-08). Para PR comum, prefira token curto e escopo.

GitLab, "AI Accountability Report", consultado em 2026-07-08, https://ir.gitlab.com/news/news-details/2026/GitLab-Research-Reveals-Organizations-Are-Generating-AI-Code-Faster-Than-They-Can-Control-It/default.aspx
DORA, "Balancing AI tensions: Moving from AI adoption to effective SDLC use", consultado em 2026-07-08, https://dora.dev/insights/balancing-ai-tensions/
GitHub, "Agent pull requests are everywhere. Here's how to review them", consultado em 2026-07-08, https://github.blog/ai-and-ml/generative-ai/agent-pull-requests-are-everywhere-heres-how-to-review-them/
arXiv, "More Code, Less Reuse: Investigating Code Quality and Reviewer Sentiment towards AI-generated Pull Requests", consultado em 2026-07-08, https://arxiv.org/abs/2601.21276
OpenAI Developers, "Non-interactive mode", consultado em 2026-07-08, https://developers.openai.com/codex/noninteractive
OpenAI Developers, "Build iterative repair loops with Codex", consultado em 2026-07-08, https://developers.openai.com/cookbook/examples/codex/build_iterative_repair_loops_with_codex
OpenAI Developers, "Run long horizon tasks with Codex", consultado em 2026-07-08, https://developers.openai.com/blog/run-long-horizon-tasks-with-codex
OpenAI Developers, "Using Goals in Codex", consultado em 2026-07-08, https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex
OpenAI Developers, "Use Codex CLI to automatically fix CI failures", consultado em 2026-07-08, https://developers.openai.com/cookbook/examples/codex/autofix-github-actions
Anthropic, "Claude Code GitHub Actions", consultado em 2026-07-08, https://code.claude.com/docs/en/github-actions
Anthropic, "claude-code-action security", consultado em 2026-07-08, https://github.com/anthropics/claude-code-action/blob/main/docs/security.md

Quando o CI devolve a falha para o agente

Por que o loop de reparo no CI virou prioridade?

Qual é o contrato mínimo de um loop self-correcting?

Como o CI entrega feedback útil sem despejar contexto?

Onde colocar limites para o agente não piorar o PR?

Como o PR prova que o reparo foi legítimo?

Quando parar o loop e chamar uma pessoa?

O que implementar nesta semana?

Perguntas frequentes sobre loop self-correcting no CI

Loop self-correcting substitui code review humano?

Quantas tentativas o agente deve ter?

Posso usar `danger-full-access` em CI?

O que o agente deve receber do log?

Fechamento

Fontes consultadas

Mais de Samuel

Spec executável deixa agente de código obedecer

Agentjacking via Sentry muda o risco dos agentes

Hooks seguram agentes de código antes do estrago