Como Criar Workflows Claude Automatizados

Há uma frase circulando que resume para onde o desenvolvimento de código agêntico está caminhando: o objetivo não é um prompt melhor, é um fluxo de trabalho que funciona sem você precisar monitorá-lo. A maioria das pessoas usa Claude da mesma forma que usa uma janela de bate-papo. Você digita, espera, lê, digita novamente. Isso funciona, mas limita sua produção a um agente que você está ativamente supervisionando. Os engenheiros que estão realmente aproveitando o Claude construíram outra coisa: fluxos de trabalho que são iniciados por um agendamento ou um gatilho, fazem o trabalho, verificam seus próprios resultados e só notificam um humano quando algo requer uma decisão.

botão

TL;DR

Um fluxo de trabalho Claude que funciona sem você precisa de cinco partes: uma especificação escrita precisa, execução headless (não interativa), um portão de verificação determinístico que decide aprovação ou reprovação, guardrails rígidos (listas de permissão, iterações limitadas, limites de custo, um botão de desligamento), e uma entrega que notifica um humano ou escala em caso de falha. O modo headless do Claude Code (claude -p), o SDK do Agente Claude, hooks e um agendador (cron ou launchd) fornecem todas as cinco. O agente não é a parte arriscada. Executá-lo sem supervisão, sem um portão e guardrails, é. Construa-os primeiro, depois tire suas mãos.

Por que "funciona sem você" é o objetivo real

O chat supervisionado tem um teto rígido: você. Cada iteração espera que um humano leia a saída e decida o próximo passo. O modelo gera em segundos, depois fica ocioso por minutos enquanto você troca de contexto. Você é o gargalo em um sistema que, de outra forma, é rápido.

Fluxos de trabalho não supervisionados removem esse teto. O agente trabalha, um script o verifica, falhas são automaticamente redirecionadas, e você só intervém nas extremidades. A recompensa não é apenas velocidade. É paralelismo. Uma vez que um fluxo de trabalho funciona sem supervisão, você escala adicionando fluxos de trabalho, não digitando mais rápido. Essa é a mesma mudança que abordamos em fluxos de trabalho dinâmicos do Claude Code, onde uma sessão se expande em muitos agentes paralelos.

Mas "funciona sem você" aumenta os riscos. Um agente supervisionado que faz uma edição ruim é pego quando você lê o diff. Um agente não supervisionado o comete, executa o próximo passo e continua. Assim, a disciplina muda da criação de prompts para o design de sistemas: você está construindo uma máquina que precisa ser correta, limitada e observável quando ninguém está olhando. O artigo da Anthropic sobre construção de agentes eficazes defende o mesmo. A alavancagem vem do ambiente ao redor do modelo, não de uma única mensagem mais inteligente.

As cinco partes que todo fluxo de trabalho não supervisionado precisa

Pule qualquer uma dessas e o fluxo de trabalho fará a coisa errada com confiança ou nunca parará.

Uma especificação precisa. Uma descrição escrita do que está "pronto" que o agente lê no início de cada execução. Especificações vagas produzem trabalho vago. "Corrigir a API" falha; "o endpoint POST /orders retorna 201, valida o corpo contra o esquema, rejeita campos ausentes com 422" tem sucesso.
Execução headless. Claude precisa rodar sem um humano no teclado. Isso significa modo não interativo, não a interface de chat.
Um portão de verificação. Uma verificação determinística que retorna aprovação ou reprovação com uma razão concreta: testes, uma verificação de tipo, uma validação de esquema, um teste de contrato. É isso que permite ao fluxo de trabalho decidir que está realmente concluído em vez de apenas aceitar a palavra do modelo.
Guardrails. Listas de permissão, uma contagem máxima de iterações, um limite de custo, registro (logging) e um botão de desligamento. Isso impede que uma execução confusa cause danos enquanto você está dormindo.
Uma entrega. Quando o fluxo de trabalho termina ou desiste, ele avisa alguém. Uma notificação, um rascunho para revisão, um alerta de falha. O silêncio não é sucesso.

As três do meio são onde a maioria das configurações é fraca. Vamos construir cada uma com as ferramentas que Claude oferece.

Os blocos de construção do Claude

Modo Headless (claude -p)

O modo de impressão do Claude Code executa um prompt de forma não interativa e é encerrado. Esta é a base de todo fluxo de trabalho não supervisionado. Você entrega uma tarefa, restringe suas ferramentas, captura a saída e segue em frente.

claude -p "Implement the orders endpoint per spec.md, then run the test suite" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> run.log 2>&1

A flag --allowedTools importa mais do que parece. Na interface de chat, você aprova cada ação manualmente. No modo headless, não há ninguém para aprovar, então a lista de permissões é seu único controle sobre o que o agente pode tocar. Comece de forma restrita e amplie apenas quando confiar na execução. O conjunto completo de flags está disponível na documentação do Claude Code.

O SDK do Agente Claude

Quando um comando de shell não é suficiente, o SDK do Agente Claude permite que você controle o Claude programaticamente a partir de Python ou TypeScript. Você obtém o loop em código: envia uma tarefa, transmite o resultado, inspeciona as chamadas de ferramentas, decide se continua. É assim que você envolve o agente com um fluxo de controle real.

import { query } from "@anthropic-ai/claude-agent-sdk";

const MAX_ITERATIONS = 8;
let feedback = "";

for (let attempt = 0; attempt < MAX_ITERATIONS; attempt++) {
  for await (const msg of query({
    prompt: `${task}\n\nPrevious failures:\n${feedback}`,
    options: { allowedTools: ["Edit", "Write", "Bash"] },
  })) {
    // stream/log messages as the agent works
  }

  const gate = runVerification();      // your deterministic check
  if (gate.passed) break;              // done
  feedback = gate.failures;            // the next prompt writes itself
}

As assinaturas exatas estão na documentação, mas o formato é o ponto principal: um loop que executa o agente novamente com a última falha como o próximo prompt. Se você está decidindo entre criar seu próprio loop ou usar uma opção hospedada, nossa comparação de agentes gerenciados versus o SDK do Agente detalha quando cada um faz sentido.

Hooks para guardrails determinísticos

Hooks executam seus próprios comandos em pontos fixos do ciclo de vida do Claude, sem o envolvimento do modelo. É assim que você impõe regras que o agente não pode contornar. Quer que o conjunto de testes seja executado após cada edição de arquivo? Um hook PostToolUse faz isso de forma determinística.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm test --silent" }]
      }
    ]
  }
}

Como um hook é código puro, e não uma solicitação ao modelo, ele sempre é acionado. Essa é a propriedade que você deseja para guardrails em uma execução não supervisionada. O agente não pode decidir ignorá-lo.

Um agendador para iniciar execuções

Um fluxo de trabalho que funciona sem você precisa de algo para iniciá-lo sem você. Em um servidor, é o cron; em um Mac, é o launchd. De qualquer forma, você está disparando o comando headless em um cronograma.

# every weekday at 7am: run the maintenance workflow, log everything
0 7 * * 1-5  cd /srv/api && claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Bash" >> logs/run-$(date +\%F).log 2>&1

Essa é a espinha dorsal de uma configuração autônoma: um agendador dispara o Claude headless, o agente trabalha contra uma especificação, hooks e um portão o mantêm honesto, e os logs informam o que aconteceu.

Desenhe o loop, não o prompt

Aqui está a mentalidade que une tudo. Pare de perguntar “o que devo dizer ao Claude?” Comece a perguntar “que loop faria o Claude dizer a si mesmo?” O agente é um gerador rápido sem um senso confiável de se está certo. O loop fornece esse senso através do portão. Aprofundamos nisso em pare de dar prompts ao seu agente de codificação, construa o loop em vez disso, e é a ideia fundamental para o trabalho não supervisionado: a confiança do modelo deixa de importar, apenas o veredito do portão importa.

É também por isso que uma especificação clara supera um prompt inteligente. A mesma especificação impulsiona cada iteração e serve como documentação. Um arquivo design.md ou AGENTS.md que captura a intenção, restrições e a definição de concluído dá ao agente um alvo estável em cada execução, em vez de você ter que reexplicar o contexto a cada vez.

Um exemplo prático: manutenção de API não supervisionada

Vamos concretizar. Digamos que você queira um fluxo de trabalho que mantenha um conjunto de endpoints de API em sincronia com sua especificação OpenAPI, seja executado todas as manhãs e nunca entregue um endpoint quebrado. Aqui está o formato.

Especificação. O contrato reside em um arquivo OpenAPI; o comportamento reside em casos de teste. O agente lê ambos no início da execução.
Gatilho. Um trabalho cron às 7h dispara o Claude headless com a tarefa de manutenção.
Gerar. O agente reconcilia a implementação com a especificação: adiciona endpoints ausentes, corrige formatos de resposta incompatíveis, aprimora a validação.
Portão. O fluxo de trabalho executa o conjunto de testes de API contra o serviço em execução. Asserções de status, validação de esquema JSON em cada resposta, verificações de contrato contra a especificação. Falhas retornam estruturadas: “Esperava 422 em customer_id ausente, obteve 500.” “O campo de resposta total é uma string, o esquema diz número.”
Loop ou escalada. Portão vermelho? A falha estruturada se torna o próximo prompt e o agente corrige a lacuna específica, até o limite de iterações. Verde? Ele abre um rascunho de PR. Sem tentativas? Ele registra um alerta com a última falha e para.
Entrega. Um humano recebe um PR limpo para revisar ou um relatório de falha preciso. Nunca um commit silencioso.

O portão na etapa 4 é o que torna tudo seguro para ser executado sem supervisão. Sem ele, o agente edita o código e relata sucesso com base em sua própria leitura, que é exatamente como endpoints quebrados chegam à produção. É aqui que o Apidog se encaixa em um fluxo de trabalho autônomo: o design da API, o esquema, o mock server e os testes automatizados vivem em um único espaço de trabalho, então o portão e a especificação permanecem em sincronia por padrão. Você aponta a execução para um cenário de teste do Apidog e o agente obtém aprovação/reprovação validada pelo esquema a cada iteração. O mock server substitui dependências que não estão ativas, então uma execução às 3 da manhã não é bloqueada esperando por um terceiro instável. Equipes que conectam o acesso ao endpoint do agente através do depurador de agente de IA do Apidog permitem que ele acesse e inspecione endpoints da mesma forma que um testador humano faria. Baixe o Apidog se preferir construir o portão visualmente em vez de criar um executor manualmente.

Imagem que mostra elementos de um dashboard ou ferramenta de desenvolvimento, com gráficos, código e interfaces de usuário.

Guardrails que tornam as execuções não supervisionadas seguras

Esta é a parte que separa um fluxo de trabalho em que você confia durante a noite de um que o acorda às 3 da manhã. Um agente não supervisionado precisa de limites rígidos, não de boas intenções.

Listas de permissões restritas. No modo headless, a lista de permissões é seu único controle sobre o que o agente pode fazer. Conceda as ferramentas mínimas que a tarefa precisa. Nunca dê a uma execução não supervisionada acesso irrestrito ao shell ou a comandos destrutivos sem um sandbox.
Iterações limitadas. Limite o loop. Uma execução que não consegue atingir um portão verde em N tentativas deve parar e escalar, não continuar para sempre.
Um limite de custo. Loops não supervisionados consomem tokens sem que um humano perceba. Defina um limite de gastos e registre o gasto por execução. Um loop que não está convergindo deve acionar o limite e parar. Nossas notas sobre redução de custos de tokens do agente se aplicam diretamente aqui.
Proteja o portão. Mantenha os arquivos de teste e a especificação fora do conjunto de arquivos que o agente pode editar. Se ele puder reescrever o teste para passar, você construiu uma máquina para falsificar o progresso.
Um sandbox. Execute o trabalho não supervisionado em um espaço de trabalho ou contêiner isolado, não no principal. Um worktree do Git ou um branch descartável contém o raio de explosão de uma execução ruim.
Registro e um botão de desligamento. Capture cada execução em um log que você realmente leia e mantenha uma maneira de parar um trabalho no meio do caminho. Você não pode depurar o que não registrou.
Aprovação humana nas extremidades. "Sem você" não significa "sem ninguém, nunca". Coloque uma pessoa no início (aprovar a tarefa) ou no final (aprovar o PR), mas não no loop interno. Os padrões de conexão e modos de falha aqui se alinham com a conexão de ferramentas de fluxo de trabalho agêntico.

A maioria disso se resume a uma regra: um agente não supervisionado deve ser capaz de fazer seu trabalho e nada mais. Restrinja as ferramentas, limite o loop, isole o espaço de trabalho e torne cada execução observável.

Erros comuns

Alguns padrões afundam rapidamente os fluxos de trabalho autônomos.

Sem portão, apenas intuição. Se a única verificação é “agente, você terminou?”, você não tem um fluxo de trabalho, você tem um chatbot não supervisionado. O portão deve ser externo ao agente.
Uma tarefa gigante. Uma execução instruída a “manter todo o serviço” raramente converge. Decomponha em tarefas do tamanho de um endpoint, cada uma com seu próprio portão. Tarefas pequenas terminam; tarefas grandes falham.
Permissões abertas demais. Conceder todas as ferramentas porque é conveniente transforma um pequeno bug em um grande incidente quando ninguém está observando. Limite estritamente as permissões.
Sucesso silencioso ou falha silenciosa. Um fluxo de trabalho que faz commit sem avisar ninguém, ou morre sem um alerta, é pior do que nenhum fluxo de trabalho. Sempre entregue.
Confiar no autorrelato do modelo. O agente dirá que está pronto. O portão decide se está. Construa para a lacuna entre “parece pronto” e “está pronto”, porque sem supervisão, ninguém está lá para perceber.

Acerte isso e um fluxo de trabalho Claude fará um dia de trabalho limitado e verificado antes mesmo de você tomar café. Erre, e você terá automatizado a produção de código confiante e não testado. A diferença está no portão e nos guardrails, não no modelo. Se você quiser a arquitetura mais profunda, nossa análise do design de estrutura de agente cobre como as peças se encaixam em escala.

Conclusão

Construir fluxos de trabalho Claude que funcionam sem você é menos sobre Claude e mais sobre o sistema que você constrói em torno dele. Cinco partes carregam o peso: uma especificação precisa, execução headless, um portão de verificação determinístico, guardrails rígidos e uma entrega limpa. Acertando isso, o modelo se torna um trabalhador rápido dentro de uma máquina que é correta, limitada e observável quando você não está olhando.

Comece com um fluxo de trabalho. Escreva uma especificação rigorosa, execute-o no modo headless contra um portão de verificação rápido, liste as ferramentas permitidas, limite as iterações, isole o espaço de trabalho e faça-o notificá-lo na conclusão ou falha. Para qualquer coisa que envolva APIs, seu conjunto de testes é o portão que torna as execuções não supervisionadas seguras, e o Apidog oferece o design, mocking e testes automatizados em um único espaço de trabalho para construí-lo. Baixe-o, conecte o portão e deixe o fluxo de trabalho rodar enquanto você faz outra coisa.