Colocar um agente de código no CI é um problema de design de permissões disfarçado de produtividade. A mecânica é trabalho de uma tarde: o modo headless está disponível desde o Claude Code 2.0, em setembro de 2025, e o anthropics/claude-code-action@v1 embrulha tudo isso em uma GitHub Action. Dá para ter um agente comentando em pull requests antes do almoço. Se ele deveria estar fazendo push de commits é uma pergunta diferente, e é a única que importa.

A regra que mantém isso seguro é simples: um agente no CI propõe, ele não faz merge. Cada padrão abaixo é uma variação de onde você traça essa linha.

Modo headless, rapidamente

A flag -p (ou --print) tira o Claude Code do REPL interativo e o coloca em uma única invocação em lote, o que é o que o torna scriptável. As flags que transformam isso de uma demonstração em algo que dá para rodar sem supervisão são as que restringem:

claude -p "Fix the failing unit tests. Do not change public APIs." \
  --output-format json \
  --max-turns 8 \
  --allowedTools "Read,Edit,Bash(npm test)" \
  --model claude-haiku-4-5

Cada uma delas cumpre uma função real. --output-format json retorna um objeto com result, model, usage e stop_reason, para que seu pipeline possa ramificar com base no resultado em vez de fazer grep em texto solto. --max-turns é seu disjuntor. --allowedTools é a lista de permissões, e é a flag mais importante da linha.

Os três padrões, em ordem crescente de audácia

Os times acabam em um de três lugares. Eles não são equivalentes, e a maioria dos times deveria parar no segundo.

  • Consultivo. O agente lê o diff e comenta. Ele não tem acesso de escrita a nada. Cada achado custa trinta segundos de um humano para aceitar ou descartar. É por aqui que se começa, e para muitos times é onde se deve ficar.
  • Proposição. O agente conserta algo e abre um pull request contra a branch. Ele escreve código, mas o botão de merge é humano. O gate de revisão em que você já confia faz o trabalho para o qual foi construído. Esse é o ponto ideal.
  • Autônomo. O agente faz commit direto em uma branch que vai para deploy. É o padrão que as pessoas fazem em demonstrações e é o que gera incidentes, porque o CI é o único lugar da sua stack onde um ator ruim vira um artefato em produção sem um humano no loop.

Note o que muda entre eles: não é a capacidade do agente, é apenas o raio de impacto de um erro. A chance de o agente errar é igual nos três casos. A diferença é o que acontece depois.

O modo de falha que ninguém planeja

A preocupação óbvia é o agente escrever código ruim. Essa já está coberta: seus testes e seus revisores pegam código ruim, é para isso que eles existem.

A falha real é mais sutil. Um agente instruído a deixar o build verde tem exatamente um objetivo, e há mais de uma forma de chegar lá. Apagar a assertion que falha deixa o build verde. Adicionar skip ao teste deixa o build verde. Ampliar um tipo para any faz o erro de tipo sumir. Nada disso é o agente com mau funcionamento. É o agente fazendo exatamente o que você pediu, de um jeito que você não pretendia, porque sua instrução descreveu o sintoma em vez do objetivo.

Duas coisas ajudam. Escreva o objetivo como restrição, não como alvo: "conserte a implementação para que os testes existentes passem, sem modificar arquivos de teste" é uma instrução diferente de "conserte o build". E force isso estruturalmente em vez de confiar no texto, porque texto é um pedido e uma lista de permissões de ferramentas é uma regra.

Guardrails que de fato sustentam o sistema

  • Restrinja a lista de ferramentas ao trabalho. Um agente que conserta testes precisa ler arquivos, editar código-fonte e rodar o comando de teste. Ele não precisa de acesso à rede, não precisa mexer na config de CI e não precisa das credenciais de deploy que por acaso estão no ambiente do runner.
  • Proteja os arquivos que definem o que é correto. Testes, lockfiles, workflows de CI e políticas de IAM pertencem a uma lista de bloqueio de caminhos. Se o agente não pode editar o teste, ele não pode apagar o teste para passar nele.
  • Limite turnos e limite tokens. Um loop que não consegue convergir deve parar e avisar. Um agente sem limite martelando uma tarefa impossível vira conta alta e uma fila de jobs travados.
  • Dê ao runner sua própria identidade. Não um papel amplo de admin que por acaso está ali disponível. O job do agente roda com um papel restrito, com as permissões que aquela tarefa precisa, para que um agente confuso não consiga alcançar algo que nunca deveria ter.
  • Trate commits de agentes como entrada não confiável. Mesmas checagens obrigatórias, mesma revisão, mesma proteção de branch de qualquer contribuidor. O agente não ganha atalho, porque o atalho é a vulnerabilidade.
  • Registre a sessão inteira. Quando uma mudança feita por um agente causa um incidente às três da manhã, "o que foi pedido e o que ele fez" precisa de uma resposta que não seja um dar de ombros. A saída em JSON mais a transcrição da sessão é sua trilha de auditoria. Guarde isso.

A economia é genuinamente boa

Vale a pena ser justo com a ideia: os números são favoráveis. Uma passada de revisão automatizada em um diff de tamanho médio custa alguns centavos e termina em menos de um minuto. Comparado ao custo da troca de contexto de um revisor humano, essa conta fecha em praticamente qualquer volume de pull request, e é exatamente por isso que esse padrão está se espalhando.

Essa também é a armadilha. Barato o suficiente para rodar em cada PR é barato o suficiente para rodar sem pensar, e o custo marginal de adicionar mais uma permissão à lista sempre parece zero no momento em que você a adiciona. O custo chega depois, de uma vez só. Decida o limite enquanto ele ainda é teórico.

A conclusão

Um agente no seu pipeline é um contribuidor sem juízo, com paciência infinita e com quaisquer credenciais que você tenha dado ao runner. Dê a ele as ferramentas estreitas para um trabalho, proteja os arquivos que codificam o que é correto, limite o loop e faça-o abrir um pull request como qualquer outro contribuidor. A produtividade é real. Ela vem do agente fazendo a primeira passada tediosa, não de remover o humano que diz sim.

Leia isso a seguir

Para o lado de pipeline disso, why automated tests are essential in your CI/CD pipeline cobre as checagens que a saída de um agente precisa passar, lá em ercan.cloud. O hub fica em ercanermis.com.