Antes que o código escrito por um agente seja enviado para produção, as seguintes condições devem ser rigorosamente atendidas: a suíte de testes passa com sucesso, o lint e as verificações de tipos são aprovados, o diff tem o tamanho e o escopo exatos solicitados no plano, o projeto compila sem erros, uma varredura de segurança não relata nada de novo e um engenheiro humano leu e aprovou o diff. Cada uma dessas etapas é um portão de verificação (verification gate): uma checagem que deve passar antes que o trabalho avance para o próximo estágio. Há mais um portão que atua antes que qualquer código exista: a aprovação humana do plano. É ele quem economiza mais recursos financeiros, pois um plano rejeitado custa zero em execução. Este artigo define o conceito de portões, lista aqueles indispensáveis para o código de agentes e descreve como o Ivy Tendril os executa.

O que é um portão de verificação

Um portão é uma condição obrigatória vinculada à transição entre estágios. O trabalho no estágio N não pode avançar para o estágio N+1 até que a condição seja satisfeita. A condição precisa ser avaliada exatamente da mesma forma a cada execução, e o resultado deve ser registrado para que possa ser auditado posteriormente.

Três propriedades distinguem um portão de uma simples recomendação:

Ele bloqueia. Um portão com falha interrompe a transição imediatamente. Uma verificação cuja falha é meramente consultiva é um relatório, não um portão.
Ele é automático ou explícito. Ou um programa o avalia de maneira objetiva (testes, lint, compilação), ou uma pessoa identificada toma uma decisão registrada (revisão de código). «Alguém provavelmente olhou» não atende a nenhum dos dois critérios.
Ele possui um caminho definido para falhas. Quando o portão falha, o trabalho é encaminhado para um destino certo: de volta ao agente, de volta ao plano ou a um humano. Código que falha em um portão e fica sem dono é a causa mais comum de desperdício e perda de trabalho de agentes.

O código escrito por humanos também atravessa portões: integração contínua e revisão de pull requests. A diferença fundamental com agentes é o volume. Quando um único desenvolvedor pode abrir vinte pull requests por dia, a revisão humana se torna o gargalo mais lento. Por isso, os portões que antecedem a revisão devem eliminar o máximo possível de problemas antes que uma pessoa comece a ler o diff. O artigo Padrões de orquestração para agentes de código detalha como a verificação se conecta a filas, isolamento e controle de custos.

Os portões indispensáveis para o código gerado por agentes

Portão	O que verifica	O que uma falha geralmente indica
Aprovação do plano	Um humano leu o plano e validou a abordagem e o escopo	A tarefa foi mal especificada ou a estratégia técnica está incorreta
Testes	Testes existentes continuam passando; novo comportamento possui testes	O agente quebrou funcionalidades existentes ou não cobriu suas alterações
Lint e checagem de tipos	O código obedece às regras do projeto e compila	Violações de regras, código não utilizado ou erros de tipo introduzidos para fazer os testes passarem
Tamanho e escopo do diff	Arquivos alterados coincidem com o plano; o diff é revisável	O agente modificou arquivos fora do escopo ou refatorou código não relacionado
Compilação (Build)	O projeto completo compila a partir da branch	Algo funciona isoladamente, mas quebra quando integrado ao projeto
Varredura de segurança	Sem novos segredos/chaves expostos, dependências vulneráveis ou padrões proibidos	O agente inseriu credenciais, uma dependência insegura ou chamadas não permitidas
Aprovação do diff	Um humano leu o diff e aprovou sua implementação	Tudo o que portões automatizados não podem julgar: intenção de produto, nomenclatura, manutenibilidade

Os seis primeiros ocorrem antes do envolvimento humano: o portão de plano roda antes da execução, e os demais rodam de forma isolada dentro do worktree do agente após a geração de código. Dois deles merecem atenção especial.

Os riscos específicos do código gerado por modelos — tratamento inseguro de saídas, inserções maliciosas na cadeia de suprimentos, vazamento de credenciais — estão catalogados no OWASP Top 10 for LLM Applications, que serve como excelente lista de verificação para o que a segurança deve procurar.

Tamanho e escopo do diff é o portão que as equipes mais costumam ignorar, sendo muito mais crítico para agentes do que para pessoas. Um agente instruído a corrigir uma verificação de nulo muitas vezes aproveita para reformatar o arquivo inteiro, renomear variáveis e alterar três pontos de chamada externos. Juntas, essas mudanças transformam uma revisão simples de 10 linhas em um diff ilegível de 300 linhas. Um portão de escopo compara os arquivos e módulos tocados contra o plano original e acusa qualquer inconsistência.

A varredura de segurança identifica credenciais no código, vulnerabilidades em pacotes externos e padrões perigosos. Como os agentes imitam padrões do código ao redor, um repositório com um único padrão inseguro tende a acumular outros rapidamente.

Por que a checagem do plano evita execuções inúteis

Todos os portões posteriores à execução compartilham uma característica: quando falham, tokens e dinheiro já foram consumidos. Testes, lint, build e varredura mostram que a execução deu errado. Apenas o portão de plano avisa antes que o gasto ocorra.

Observe o que os portões posteriores capturam: uma falha de teste porque o agente interpretou mal o requisito é um problema do plano. Uma violação de escopo porque o agente mexeu em módulos não mencionados na tarefa é um problema do plano. Uma falha de build porque o plano solicitou uma mudança em um pacote sem prever os impactos nos dependentes é um problema do plano. Em cada um desses cenários, um revisor humano lendo o plano redigido durante dois minutos teria detectado o erro, com custo de execução exatamente igual a zero.

É exatamente por isso que o fluxo da fábrica de software — a definição da Ivy para a sequência repetível de planejar, executar, verificar e revisar — possui rigorosamente dois pontos de controle humanos e posiciona um deles antes de qualquer linha de código existir. No ponto de controle do plano, definem-se escopo, metodologia e sequenciamento. No ponto de controle do diff, confirma-se a exatidão técnica. Tudo entre eles é 100% automático.

Como o Ivy Tendril executa portões de verificação

O Ivy Tendril é um aplicativo desktop local-first (macOS, Windows, Linux) que conduz uma tarefa desde o plano até a pull request revisada. Os dois pontos de controle humanos e os portões automatizados intermediários estão integrados organicamente em seu ciclo de vida. Consulte a documentação do aplicativo Review para conhecer a interface.

Portão de plano. O plano nasce como rascunho (Draft). Um engenheiro o analisa e pode expandir (Expand), dividir (Split), atualizar (Update) ou comentar diretamente no texto para que o plano seja reescrito. A execução do código jamais começa sem a aprovação do plano.
Execução em isolamento. Cada plano é executado em seu próprio git worktree em uma branch exclusiva, garantindo que a verificação seja feita exatamente sobre as mudanças daquele plano e nada mais. O artigo Worktrees do Git para agentes de IA paralelos explica por que o isolamento confere confiabilidade aos portões.
Abas de verificação. Ao final da execução, o aplicativo Review exibe testes, lint e diff em abas separadas, para que o revisor analise todas as três perspectivas antes de tomar sua decisão.
Importação de CI no Pro. Equipes cujos portões rodam em CI — GitHub Actions ou qualquer outro orquestrador — podem importar os resultados para o Review no plano Pro, eliminando a necessidade de alternar entre ferramentas externas.
Caminho para falhas. Quando uma verificação não passa, o trabalho retorna ao agente com a saída de erro anexada. O agente recebe o log real de teste ou lint (sem resumos artificiais) e tenta novamente no mesmo worktree. A visualização Jobs transmite o streaming de logs e tool calls do agente em tempo real durante todo o processo.
Portão do diff. Somente após a aprovação em todos os testes técnicos e o aceite formal do diff por um humano é que o Tendril abre a pull request no GitHub. Nada é entregue sem ambas as assinaturas.

O custo é registrado por plano e por job, de modo que um plano que exigiu três tentativas antes de passar revela com clareza o custo das reexecuções — fornecendo a base empírica para avaliar se o portão de plano deveria ter sido mais criterioso.

Como começar

Escreva e liste seus portões atuais: a maioria das equipes descobre que possui testes e revisão de código, e que o linter roda em algum lugar sem que ninguém saiba com certeza se ele bloqueia a entrega.
Instale o Tendril: curl -sSf https://cdn.ivy.app/install-tendril.sh | sh (macOS, Linux) ou irm https://cdn.ivy.app/install-tendril.ps1 | iex (Windows). Instruções em instalação.
Execute um primeiro plano pelo ciclo de vida completo e avalie as abas de testes e lint antes de inspecionar o diff. Observe o que você teria deixado passar caso tivesse olhado apenas o diff.
Adicione uma checagem de escopo à revisão de planos: a lista de arquivos que o agente pode modificar coincide estritamente com o plano?

O Tendril é gratuito e com código disponível sob a Functional Source License. Importação de verificações de CI, ferramentas de equipe, hospedagem on-premise e SSO estão presentes nos planos Pro e Enterprise.

Perguntas frequentes

Os portões de verificação devem bloquear automaticamente ou apenas avisar o revisor?

Testes, lint, checagem de tipos e compilação devem bloquear de forma compulsória; um revisor não deveria gastar tempo analisando um diff que sequer compila. Alertas de escopo e segurança devem ser expostos ao revisor com permissão de aceite manual, pois ambas as áreas admitem exceções operacionais legítimas.

Quantas tentativas (retries) um agente deve ter em caso de falha na verificação?

Defina um limite claro e registre-o. Falhas recorrentes na verificação quase sempre decorrem de problemas no plano, não na execução; retorne o trabalho para a fase de planejamento em vez de pagar por uma quinta tentativa infrutífera. O controle de custos por tarefa torna transparente o desperdício com novas tentativas.

A revisão humana do diff continua necessária se todos os portões automáticos passarem?

Sim, sem exceção. Portões automatizados verificam estritamente o que pode ser formalizado de antemão. Eles não são capazes de julgar se a alteração cumpre o propósito real da demanda, se a solução será sustentável ao longo do tempo ou se o próprio plano era conceitualmente adequado. É exatamente por essa razão que o ponto de controle do diff permanece como um dos dois portões humanos obrigatórios.

Primeiros passos com o Ivy Tendril

Pronto para a orquestração paralela de agentes em nível de engenharia?

Explore o código: Confira o Ivy Tendril no GitHub (Código aberto).
Consulte a documentação: Encontre guias de integração em tendril.ivy.app.
Agende uma sessão técnica: Entre em contato pelo e-mail renco@ivy.app para uma consultoria de arquitetura de 30 minutos.

Portões de verificação: o que precisa ser verdade antes do código de agentes ir para produção