Claude Code modo headless: scripts e automações em lote

Claude Code modo headless: scripts e automações em lote

O modo headless do Claude Code é a forma de executá-lo sem a interface interativa: você passa um prompt pela linha de comando, ele faz o trabalho e devolve o resultado ao script, sem conversa em tempo real. Para usar em lote ou em tarefa agendada, defina antes quais ferramentas ele pode acionar, quantos passos pode dar e onde cada execução será registrada. Sem esses três limites, o que existe é um processo autônomo que ninguém acompanha.

Principais pontos

• O modo headless roda um prompt por execução e termina, o que o torna adequado a scripts, tarefas agendadas e etapas de CI.
• Sem ninguém para aprovar pedidos de permissão, a lista de ferramentas permitidas passa a ser a principal barreira de segurança.
• Saída estruturada (JSON) e logs por execução transformam a automação em algo que se audita, repete e depura.
• O resultado deve cair em um lugar revisável, como um rascunho ou uma proposta de alteração, e não direto em produção.
• Comece por um fluxo pequeno, com critério de sucesso combinado, antes de agendar qualquer coisa para rodar sozinha.

O que é o modo headless e quando ele faz sentido?

No uso interativo, uma pessoa acompanha cada passo, lê o que o Claude Code propõe e aprova ou nega ações. No modo headless essa pessoa sai de cena. Você chama o comando com a opção de impressão (print, em geral escrita como -p) e um prompt, o agente executa o que for preciso e imprime o resultado. É o mesmo agente, mas operando dentro de um script, e por isso a responsabilidade pelo controle passa da conversa para a configuração.

O ganho aparece quando a tarefa é repetitiva, tem entrada clara e saída verificável. Alguns exemplos: revisar um lote de arquivos contra um padrão da equipe, redigir notas de versão a partir de commits, classificar chamados exportados de um sistema, atualizar trechos de documentação ou resumir falhas de uma rotina de testes.

Um guia rápido de decisão:

• Use headless se a tarefa se repete, a entrada é previsível e alguém consegue conferir o resultado em poucos minutos.
• Use headless se o pior erro possível é um rascunho ruim que será descartado na revisão.
• Prefira o modo interativo se a tarefa exige exploração, perguntas de volta ou decisões ao longo do caminho.
• Não automatize, por ora, tarefas com impacto financeiro, jurídico ou de reputação sem aprovação humana antes da ação final.

Para a fronteira do que não deve ser delegado, vale ler também Guardrails para agentes de IA: entrada, saída e ação na prática.

Como rodar o Claude Code em um script, passo a passo

Os nomes exatos de opções mudam entre versões, então confirme na documentação oficial da versão instalada. O desenho geral, porém, é estável.

• Escreva o prompt como uma especificação: objetivo, arquivos ou dados de entrada, formato de saída esperado e o que fazer quando não houver informação suficiente (por exemplo, devolver um campo vazio e uma justificativa).
• Guarde o prompt em um arquivo versionado no repositório, e não dentro do script, para que mudanças tenham histórico e revisão.
• Chame o Claude Code com a opção de impressão e peça saída em JSON, para que o script leia campos em vez de interpretar texto livre.
• Defina a lista de ferramentas permitidas e um teto de turnos (passos do agente) para a execução.
• Rode a partir de um diretório de trabalho controlado, com apenas os arquivos necessários.
• Leia o código de saída do processo. Se for diferente de sucesso, o script registra a falha e avisa uma pessoa, em vez de tentar de novo sem limite.
• Valide a saída antes de usá-la: o JSON tem os campos esperados? Os valores estão dentro do intervalo aceitável? Só então o resultado segue adiante.

Quando o fluxo cresce, as regras do projeto (convenções, comandos de teste, áreas proibidas) pertencem a um arquivo de instruções do repositório, e tarefas recorrentes podem virar habilidades reutilizáveis. Veja Skills no Claude Code e Como escrever um bom CLAUDE.md para essa camada.

Como limitar o que uma execução sem supervisão pode fazer?

Sem uma pessoa para clicar em aprovar, o que não estiver explicitamente permitido deve ser negado ou simplesmente não rodar. Trate a configuração de permissões como o contrato da automação. Os controles mais úteis são estes:

• Lista de ferramentas permitidas: libere somente o necessário. Uma tarefa de leitura e resumo não precisa de escrita em disco nem de acesso à rede.
• Lista de ferramentas negadas: bloqueie explicitamente o que nunca deve acontecer, como apagar arquivos, alterar configuração de implantação ou executar comandos de rede arbitrários.
• Teto de turnos: limita quantos passos o agente dá, o que contém laços e tarefas que fogem do escopo.
• Modo de permissão conservador: evite qualquer modo que dispense confirmações fora de um ambiente isolado e descartável.
• Isolamento: execute em contêiner ou máquina de uso único, sem acesso à rede interna além do estritamente necessário.
• Credenciais mínimas: use chaves com permissão de leitura, restritas ao que a tarefa toca, guardadas no gerenciador de segredos do agendador e nunca no repositório.
• Integrações por MCP: conecte somente servidores auditados e, de preferência, com acesso de leitura. Isso é tratado em Configurar MCP no Claude Code.

Há um risco específico de automações em lote: o agente lê conteúdo que você não escreveu, como e-mails, chamados, páginas e comentários. Esse conteúdo pode conter instruções disfarçadas de dados. A orientação da OWASP sobre prevenção de injeção de prompt vale aqui: separe instruções de dados, não dê ao agente ferramentas que um texto malicioso poderia usar para causar dano e valide a saída antes de agir. Para um panorama de permissões, sandbox e segredos em ambiente corporativo, veja Segurança no Claude Code para empresas.

O que registrar de cada execução?

Uma automação sem registro vira uma caixa-preta: quando algo sair estranho, ninguém saberá o que foi pedido, o que foi lido e o que foi produzido. Registre por execução:

• Identificador único da execução, data, hora e duração.
• Versão do prompt (o hash do commit do arquivo serve) e versão do Claude Code usada.
• Referência da entrada, como o nome do lote ou os identificadores dos itens, e não o conteúdo completo quando houver dados pessoais.
• Ferramentas permitidas naquela execução e teto de turnos.
• Saída estruturada devolvida e resultado da validação.
• Código de saída, erros e número de tentativas.
• Quem revisou o resultado e qual foi a decisão: aceito, ajustado ou descartado.

A saída em JSON costuma trazer metadados da execução, como identificador de sessão e informações de uso, que ajudam a compor esse registro. Para acompanhar uma execução longa em tempo real, existe também o formato de saída em fluxo. Confirme os campos disponíveis na documentação da sua versão antes de depender deles.

Se a empresa já tem observabilidade, envie esses eventos para o mesmo lugar. O primer de observabilidade do OpenTelemetry é uma boa base conceitual sobre logs, métricas e traces, e há convenções semânticas em andamento para IA generativa.

Um cuidado de LGPD: o log também é um tratamento de dados. Se as entradas contêm dados pessoais, defina o que entra no registro, por quanto tempo fica guardado e quem acessa. Na dúvida, registre referências e não o conteúdo.

Como agendar sem perder o controle?

O agendador pode ser um cron em um servidor, uma rotina de CI ou uma ferramenta de orquestração que a empresa já usa. O que importa é o comportamento ao redor do comando:

• Trava de concorrência: evite que duas execuções do mesmo fluxo rodem ao mesmo tempo sobre os mesmos itens.
• Tempo máximo: se a execução passar do limite, o processo é encerrado e uma pessoa é avisada.
• Reexecução segura: projete para que repetir a tarefa não duplique efeitos. O conceito de idempotência, bem explicado na documentação de requisições idempotentes da Stripe, se aplica igualmente a lotes de IA: cada item processado tem uma chave, e itens já concluídos são ignorados.
• Estado entre execuções: para tarefas longas, mantenha um arquivo de progresso que diga o que já foi feito. A Anthropic descreve esse tipo de prática em seu material sobre estruturas para agentes de longa duração.
• Destino revisável: a saída vai para um rascunho, uma proposta de alteração ou uma fila de revisão. A etapa que realmente altera algo importante fica com uma pessoa ou com código determinístico, validado.
• Alerta de falha: uma automação que falha em silêncio é pior que uma que nunca existiu, porque cria falsa confiança.

Quando parte do fluxo é determinística (buscar dados, formatar, enviar), mantenha-a em código comum e chame o Claude Code apenas onde há julgamento, como interpretar texto livre. Essa divisão deixa o sistema mais barato, mais previsível e mais fácil de testar.

Cenário ilustrativo: revisão em lote de documentação

Imagine, como exemplo hipotético, uma empresa de software com um repositório de documentação interna que fica desatualizado. Toda semana, uma rotina agendada roda o Claude Code em modo headless sobre os arquivos alterados nos últimos dias.

O prompt, versionado no repositório, pede para apontar trechos que contradizem o código atual e sugerir correção em formato estruturado. As ferramentas permitidas são apenas leitura de arquivos e busca. Edição, execução de comandos e rede estão bloqueadas. O teto de turnos é baixo e a execução roda em um contêiner descartável.

O script valida o JSON, descarta sugestões sem referência de arquivo e abre uma proposta de alteração com as sugestões restantes. Uma pessoa da equipe revisa, aceita ou rejeita e o registro guarda a decisão. Depois de algumas semanas, a equipe compara as sugestões aceitas com as rejeitadas, ajusta o prompt e decide se amplia o escopo, mantém como está ou desliga. Nada nesse fluxo toca produção sem uma pessoa.

Para definir o critério de sucesso desse tipo de piloto, o roteiro de Como Medir um Piloto de Automação com IA ajuda a combinar métricas e pontos de decisão antes de começar.

Como o método mapear, limitar, pilotar e transferir se aplica?

Mapear: descreva o processo atual, quem faz, quanto tempo leva e quais erros aparecem hoje. Sem essa linha de base, não há como saber se a automação melhorou algo.

Limitar: defina dados acessíveis, ferramentas permitidas, ações proibidas e o ponto onde uma pessoa entra. Essa é a etapa em que a lista de permissões, o isolamento e as credenciais mínimas são decididos.

Pilotar: rode um único fluxo real, com registro de cada execução e um critério de sucesso acordado. Observe falhas, revisões e casos que o prompt não previu.

Transferir: entregue à equipe o prompt versionado, a configuração, o painel de registros e o procedimento de desligamento. Depois, a decisão é expandir, ajustar ou parar, com base no que o piloto mostrou. Nada disso é garantia de resultado: é uma forma de descobrir cedo se a automação merece continuar.

Perguntas frequentes

O modo headless do Claude Code é o mesmo que usar a API da Anthropic diretamente? Não exatamente. Ele executa o agente do Claude Code, com suas ferramentas de leitura de arquivos, busca e comandos, enquanto a API devolve apenas a resposta do modelo e exige que você construa o laço do agente. Para tarefas que mexem em arquivos e repositórios, o headless costuma ser o caminho mais curto. Para fluxos totalmente customizados, pode fazer mais sentido construir sobre a API ou o SDK.

Preciso de um servidor dedicado para rodar automações em lote? Não necessariamente. Uma rotina de CI, uma máquina virtual pequena ou um contêiner agendado já resolvem muitos casos. O importante é que o ambiente seja isolado, tenha segredos bem guardados e permita reter os logs. A comparação de opções está em Onde hospedar um agente de IA.

Posso deixar o Claude Code rodando sem nenhuma supervisão humana? Só em tarefas de baixo risco, com ferramentas muito restritas e saída validada por código. Mesmo assim, alguém precisa olhar os registros e os alertas de forma periódica. Para qualquer ação com efeito externo, como enviar mensagem a cliente, alterar cadastro ou publicar, mantenha uma aprovação humana.

Como evitar que uma mudança no prompt piore o resultado sem eu perceber? Versione o prompt, mantenha um conjunto pequeno de casos de referência com a resposta esperada e rode essa verificação a cada alteração, de preferência na integração contínua. Compare os resultados antes de publicar a nova versão. A prática é detalhada em Teste de regressão de prompts no CI.

Fontes

• Anthropic: Effective harnesses for long-running agents
• OWASP: prompt injection prevention
• OpenTelemetry: observability concepts
• Stripe: idempotent requests