Claude Code Routines vs GitHub Actions: Onde Agendar Agentes

Claude Code Routines, que a Anthropic lançou em abril de 2026, é uma configuração salva do Claude Code: um prompt, um ou mais repositórios e conectores, empacotados uma vez e executados automaticamente na infraestrutura de nuvem gerenciada pela Anthropic. A documentação oficial descreve três tipos de disparo: cadência agendada, API (HTTP POST com bearer token) e eventos do GitHub. GitHub Actions, por outro lado, executa os scripts que você escreve em runners hospedados no GitHub. Ambos podem executar agentes de IA agendados. Não são a mesma coisa, e escolher errado custa dinheiro ou horas de luta com YAML. Este post mapeia a decisão, apresenta a fila de blog worker e cobre recuperação de falhas.

Escolha Cloud Routines, Desktop, Session Loops ou Actions

Existem quatro opções de hospedagem. Elas não são intercambiáveis.

Cloud Routines executam na infraestrutura da Anthropic independentemente de seu laptop estar ligado. De acordo com a documentação, cada rotina pode ter um disparo agendado, um disparo de API ou um disparo de evento do GitHub, e você pode combinar os três em uma rotina. O custo: cada execução faz um clone fresco, então arquivos locais nunca estão disponíveis.

Tarefas agendadas no desktop rodam na sua máquina. Elas têm acesso total ao seu filesystem local, bancos de dados locais e arquivos .env. Se a máquina estiver desligada, a tarefa não executa. Simples.

Agendamento com escopo de sessão (as ferramentas CronCreate, CronList, CronDelete) funciona apenas dentro de uma sessão CLI aberta. Estas são ferramentas de agendamento de sessão, não a API de rotinas de nuvem. Elas desaparecem quando a sessão termina.

GitHub Actions com um disparo cron é um arquivo YAML de workflow que o GitHub executa em um runner hospedado. Gratuito para repos públicos, barato para privados, determinístico e profundamente integrado ao seu código. O overhead é real se você não já vive no GitHub, mas para desenvolvedores que vivem, é mínimo.

Então: como você escolhe?

1. A tarefa executa independentemente de sua máquina estar ligada e precisa de verdadeiro raciocínio de IA (resumir, rascunhar, triagar)? Cloud Routine.
2. A tarefa precisa de seu .env local, um banco de dados local ou ferramentas locais? Tarefa agendada de desktop.
3. A tarefa é um pipeline de CI/CD, manipulador de evento de PR ou um script determinístico que chama uma API e posta no Slack? GitHub Actions, possivelmente com um breve script Python e nenhum LLM.
4. A tarefa é exploratória e vive dentro de uma única sessão que você já está executando? Session loop.

O breakdown do AI Magicx deixa claro: se sua rotina é "chamar uma API, transformar, postar no Slack," GitHub Actions com um script Python de 10 linhas é mais barato e simples. Routines se tornam a escolha certa quando o trabalho genuinamente se beneficia do raciocínio do Claude: decidir o que relatar, escrever uma narrativa, revisar qualidade.

Persistência, Arquivos Locais e Credenciais por Host

É aqui que operadores se queimam. A tabela abaixo usa informações da documentação oficial e pesquisa da comunidade, não resultados de testes afirmados.

O write-up de 2026 do Shareuhack sinaliza uma pegadinha específica que vale a pena citar:

"Cada execução da Cloud Routine realiza um clone recente no ambiente de nuvem da Anthropic, não consegue acessar seu .env.local local, bancos de dados locais ou outro estado local."

E mais uma: o acesso à rede em cloud routines é padrão como "trusted", o que algumas APIs rejeitam completamente. Se você está recebendo erros na ClickUp ou em outra API que rejeita requisições em modo trusted, mude para acesso de rede "full" nas configurações de ambiente da rotina. Há uma pequena compensação de segurança, então sopese isso contra a sensibilidade do seu repo.

Para GitHub Actions, secrets ficam nas configurações de Secrets do repositório e são injetados como variáveis de ambiente em tempo de execução. A ação anthropics/claude-code-action@v1, que é construída sobre o Claude Agent SDK, as captura automaticamente. Você passa --model, --max-turns e --allowedTools através da entrada claude_args para controlar o que o agente pode realmente fazer.

Leia o Blog Queue Worker Atual

O blog queue worker é uma rotina (ou trabalho agendado equivalente) que pega um post de uma fila, gera conteúdo e marca como concluído. Aqui está a estrutura atual, com ressalvas claras sobre o que o código realmente faz versus o que você poderia assumir.

A afirmação condicional: o worker verifica se um post já foi reivindicado antes de pegá-lo. Isso previne duas execuções de pegarem o mesmo item simultaneamente, pelo menos no caminho feliz. O que o código atual não possui é recuperação de reivindicação obsoleta. Se um worker morre durante a execução com um post marcado como "em progresso", esse post permanece reivindicado até alguém reiniciá-lo manualmente. Não descreva isso como entrega exatamente uma vez ou garantia de um post por dia; ambas as afirmações vão além do que o código suporta.

O diagrama do worker se parece mais ou menos assim:

1. Buscar fila, filtrar por status = queued
2. Reivindicar o primeiro post disponível (definir status = in_progress, escrever um timestamp)
3. Executar o prompt de geração contra os metadados do post reivindicado
4. Em caso de sucesso: definir status = published, escrever o caminho de saída
5. Em caso de falha: incrementar retry_count, redefinir status = queued (se houver tentativas restantes) ou definir status = failed

O passo 5 é onde a maioria das equipes não investe o suficiente. A lógica de retry precisa estar no prompt da rotina ou no script wrapper, porque a infraestrutura de nuvem em si não executa novamente uma rotina que sai com erro.

Se você está construindo pipelines de conteúdo assim e quer que a camada agentic seja tratada para você, o trabalho que fazemos em agentic engineering cobre exatamente este padrão.

Agendar Jobs Vencidos e Tratar Retentativas

Agendar uma rotina via CLI requer Claude Code v2.1.225 ou superior. Antes da v2.1.211, o CLI reportava um horário de próxima execução fantasma (ano 1) para rotinas sem gatilho de agendamento. Vale a pena saber se você está lendo logs antigos.

Uma rotina com apenas gatilhos de API ou evento GitHub não tem horário de próxima execução. O CLI não mostra nada. Esse é o comportamento correto, não um bug.

Para tratar retentativas, você tem duas opções:

• Retentativa dentro do prompt. Escreva o prompt para tentar novamente a etapa que falha até N vezes antes de marcar o job como failed. O raciocínio do Claude pode distinguir entre um erro de rede transitório e um problema genuíno de conteúdo.
• Retentativa via uma rotina agendada separada. Uma rotina "requeue" leve é executada a cada hora, procura posts onde status = queued e retry_count < 3, e dispara novamente o worker principal via seu gatilho de API (um POST para o endpoint por rotina com um bearer token).

O segundo padrão é mais limpo em escala. Ele desacopla a política de retentativa do prompt de geração, e você pode ajustar os limites de retry sem tocar a rotina principal.

Os caps de execução diária e o uso de assinatura compartilhada são uma restrição real para as equipes, como aponta o relatório enterprise do Arcade. Sua recomendação: agrupar o trabalho em uma única rotina "meta-orquestrador" diária e reservar gatilhos em tempo real apenas para eventos de alta prioridade.

Para o lado de recuperação de palavras-chave SEO de um pipeline de conteúdo, a stack de automação que documentamos em DataForSEO + Claude Code trata isso separadamente e vale a pena ler antes de você projetar o esquema de fila.

Detectar Reivindicações Presas e Verificar Saída Publicada

Reivindicações obsoletas são o matador silencioso de pipelines baseados em fila. Um post que está in_progress há seis horas quase certamente está preso, não executando.

Uma rotina de detecção pode ser tão simples quanto:

• Consultar posts onde status = in_progress e claimed_at < now() - 2 hours
• Redefinir essas para status = queued, zerar o identificador do worker, registrar o reset
• Alerte via Slack ou webhook se a contagem de resets exceder um limite

Execute isso como uma rotina separada de baixa frequência (a cada duas horas está bem) em vez de embutir na tarefa principal. Separação de responsabilidades é importante aqui: a tarefa principal não deve ser responsável por limpar atrás de si mesma.

Verificar a saída publicada é um problema diferente. "Published" como um sinalizador de status significa que o banco de dados foi escrito. Não significa que o post apareceu corretamente no site, passou em uma verificação de legibilidade ou foi indexado. Uma etapa de verificação deve:

• Buscar a URL ativa e confirmar que retorna um 200
• Verificar a contagem de palavras ou um sinal leve de qualidade em relação a um limite definido (escolha seu próprio número e rotule-o como uma heurística da equipe, não um padrão universal)
• Se a verificação falhar, reverta o status para queued com um retry_count incrementado e um sinalizador verification_failed

O pipeline humanizer que descrevemos em AI Content Humanizer Pipeline executa uma passagem de verificação pós-publicação similar e vale a pena referência cruzada se você está construindo essa camada.

Custo Operacional e Propriedade

É aqui que a narrativa "rotinas são mais simples" encontra atrito.

Cloud Routines rodam na infraestrutura do Anthropic e consomem limites de sessão do Claude Code da mesma forma que uma sessão interativa. O preview de pesquisa torna isso explícito: rotinas drenam seus limites. Para um pequeno operador independente executando três ou quatro rotinas por dia, isso provavelmente está bem. Para uma equipe processando 20+ execuções diárias, você atingirá o limite e precisará arquitetar em volta.

GitHub Actions é gratuito para repositórios públicos e cobrado por minuto para privados. Uma execução de agente do Claude Code dentro de Actions via anthropics/claude-code-action@v1 ainda consome tokens de API (cobrados conforme sua taxa de API do Anthropic), mas você controla o runner, o timeout e toda a lógica de retry. Essa propriedade é o ponto.

A divisão de propriedade na prática:

• Rotinas possuem: tarefas pesadas em julgamento que precisam do raciocínio do Claude, tarefas que devem rodar sem supervisão sem overhead de infraestrutura, análises de PR disparadas pelo GitHub, e triagem de Sentry/logs.
• GitHub Actions possuem: pipelines CI/CD, manipulação de eventos de PR e fluxos de instalação, sequências determinísticas build-test-deploy, e qualquer tarefa onde um script Python de 10 linhas genuinamente faz o trabalho.

Nenhum substitui o outro. O write-up do Shareuhack enquadra bem: "A combinação ótima deixa GitHub Actions lidar com CI/CD enquanto Rotinas lidam com as partes intensivas em raciocínio." Esse enquadramento está correto, e é o limite de decisão que vale a pena marcar.

FAQ

Uma Cloud Routine pode escrever de volta para meu repositório?

Sim. Rotinas se conectam a um ou mais repositórios, e podem fazer push de commits e abrir pull requests através do repositório conectado. O que não podem fazer é acessar arquivos que existem apenas na sua máquina local. Qualquer coisa que a rotina precisar deve estar no repositório ou configurada como uma variável de ambiente nas configurações do ambiente em nuvem da rotina.

O que acontece se uma Cloud Routine atinge um limite de taxa no meio de uma execução?

A rotina em si não tenta novamente automaticamente em erros de limite de taxa. Se sair com um erro, permanece falha até a próxima execução agendada ou até você acioná-la manualmente via ponto de extremidade da API. Construir lógica de retry no prompt (detectar uma resposta de limite de taxa, aguardar, tentar novamente) ou usar uma rotina de requeue separada são ambas mitigações razoáveis.

A instalação do GitHub App é separada do comando web-setup da CLI?

Sim, e isso pega as pessoas. Executar /web-setup na CLI concede acesso de clone à rotina mas não instala o GitHub App. A entrega de webhook para acionadores de eventos do GitHub requer a instalação separada do GitHub App. O fluxo de configuração da rotina guia você através disso, mas os dois passos são distintos.

Acionadores de eventos do GitHub em Rotinas têm limites de taxa durante o preview de pesquisa?

De acordo com a documentação oficial de rotinas, eventos de webhook do GitHub estão sujeitos a limites horários por rotina e por conta durante a prévia de pesquisa. Eventos além do limite são descartados até a janela ser zerada. Planeje adequadamente se você espera picos de atividade de PR.

Posso usar skills dentro de um fluxo de trabalho do GitHub Actions com `anthropics/claude-code-action`?

Sim. A entrada de prompt aceita invocações de skill como /skill-name. Você precisa de um passo `actions/checkout` antes da ação para que os arquivos de skill em .claude/skills/ estejam presentes no runner. Skills e commands são conceitos distintos no Claude Code; consulte a documentação oficial de skills antes de confundi-los.

A ressalva mais importante de tudo acima: Cloud Routines consomem seus limites de sessão do Claude Code exatamente como sessões interativas fazem, e o worker de fila atual não tem recuperação de claim obsoleto integrada. Projete para ambos antes de colocar qualquer coisa em produção.