DEV Community

Cover image for Como Criar Workflows Claude Automatizados
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Criar Workflows Claude Automatizados

Há uma frase que resume bem o rumo do desenvolvimento agêntico: o objetivo não é escrever um prompt melhor, é criar um fluxo de trabalho que funcione sem você precisar monitorá-lo. Usar Claude como chat é útil, mas mantém você como gargalo: você digita, espera, lê, decide e digita de novo. Para ganhar escala, trate Claude como parte de um sistema: um gatilho inicia a execução, o agente trabalha, verificações determinísticas validam o resultado e um humano só é chamado quando há decisão ou falha.

Experimente o Apidog hoje

TL;DR

Um fluxo Claude não supervisionado precisa de cinco peças:

  1. Especificação precisa
  2. Execução headless
  3. Portão de verificação determinístico
  4. Guardrails rígidos
  5. Entrega ou escalada para humanos

O modo headless do Claude Code (claude -p), o SDK do Agente Claude, hooks e um agendador como cron ou launchd cobrem essa arquitetura. O risco não está no agente em si, mas em executá-lo sem limites, sem verificação e sem observabilidade.

Por que “funciona sem você” é o objetivo real

No chat supervisionado, cada iteração espera um humano. O modelo responde em segundos, mas o fluxo para enquanto você lê a saída, interpreta o diff e decide o próximo passo.

Fluxos não supervisionados removem esse teto:

  • o agente executa a tarefa;
  • um script valida o resultado;
  • falhas voltam como feedback estruturado;
  • o loop tenta novamente até um limite;
  • no fim, ele abre um PR, envia um alerta ou escala a falha.

A recompensa não é só velocidade. É paralelismo. Depois que um fluxo funciona sozinho, você escala criando mais fluxos, não digitando mais rápido. Essa mesma ideia aparece em fluxos de trabalho dinâmicos do Claude Code, onde uma sessão pode se expandir em vários agentes paralelos.

Mas a execução autônoma aumenta o risco. Um agente supervisionado que faz uma edição ruim pode ser interrompido quando você lê o diff. Um agente não supervisionado pode commitar, executar o próximo passo e continuar. Por isso, o foco muda de “prompt engineering” para design de sistema. A Anthropic também defende isso em building effective agents: a alavancagem vem do ambiente ao redor do modelo, não de uma única mensagem mais esperta.

As cinco partes de um fluxo Claude não supervisionado

1. Especificação precisa

O agente precisa saber o que significa “pronto”.

Evite tarefas vagas:

Corrigir a API.
Enter fullscreen mode Exit fullscreen mode

Prefira critérios verificáveis:

Implementar POST /orders.

Critérios:
- Retornar 201 quando o pedido for válido.
- Validar o corpo contra o schema OpenAPI.
- Retornar 422 quando customer_id estiver ausente.
- Retornar total como número, não string.
- Todos os testes em tests/orders.test.ts devem passar.
Enter fullscreen mode Exit fullscreen mode

Use um arquivo versionado, por exemplo:

tasks/orders-maintenance.md
spec/openapi.yaml
AGENTS.md
Enter fullscreen mode Exit fullscreen mode

A mesma especificação deve ser usada em todas as iterações.

2. Execução headless

Claude precisa rodar sem interface de chat. No Claude Code, use o modo de impressão:

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
Enter fullscreen mode Exit fullscreen mode

A flag mais importante aqui é:

--allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

No chat, você aprova ações manualmente. No modo headless, ninguém está no teclado. A lista de ferramentas permitidas vira seu principal controle de segurança.

Comece restrito. Amplie apenas quando o fluxo estiver estável.

Documentação: Claude Code overview.

3. Portão de verificação determinístico

O agente não deve decidir sozinho que terminou. Um portão externo deve aprovar ou reprovar.

Exemplos de portões:

  • npm test
  • pytest
  • go test ./...
  • tsc --noEmit
  • validação OpenAPI
  • testes de contrato
  • lint com regras críticas
  • checagem de schema JSON

Exemplo simples:

#!/usr/bin/env bash
set -euo pipefail

npm test -- --runInBand
npm run typecheck
npm run lint
Enter fullscreen mode Exit fullscreen mode

Se o script sai com código 0, o fluxo passa. Se sai com código diferente de 0, o fluxo falha e o erro vira feedback para a próxima tentativa.

4. Guardrails

Um agente não supervisionado precisa de limites concretos:

  • ferramentas permitidas;
  • número máximo de tentativas;
  • limite de custo;
  • workspace isolado;
  • testes protegidos contra edição;
  • logs;
  • botão de desligamento.

Regra prática: o agente deve conseguir fazer o trabalho e nada além disso.

5. Entrega

O fluxo nunca deve terminar em silêncio.

Ao final, ele deve:

  • abrir um rascunho de PR;
  • enviar um alerta;
  • registrar um relatório;
  • notificar Slack, email ou issue tracker;
  • escalar a falha com logs e último erro.

“Sem você no loop” não significa “sem humanos no processo”. Significa que humanos aprovam nas extremidades, não a cada iteração.

Blocos de construção do Claude

Modo headless com claude -p

Use claude -p para executar uma tarefa e encerrar:

claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> logs/claude-run.log 2>&1
Enter fullscreen mode Exit fullscreen mode

Um arquivo de tarefa pode conter:

# Tarefa

Sincronizar os endpoints de orders com spec/openapi.yaml.

## Regras

- Não editar arquivos em tests/.
- Não editar spec/openapi.yaml.
- Alterar apenas arquivos em src/orders/.
- Rodar npm test ao final.
- Se os testes falharem, corrigir a causa.
Enter fullscreen mode Exit fullscreen mode

Essa abordagem é melhor do que passar um prompt longo inline, porque:

  • fica versionada;
  • pode ser revisada;
  • pode ser reutilizada;
  • reduz ambiguidade entre execuções.

SDK do Agente Claude

Quando você precisa controlar o loop em código, use o SDK do Agente Claude.

Exemplo em TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { execSync } from "node:child_process";

const MAX_ITERATIONS = 8;

const task = `
Implementar o endpoint POST /orders conforme spec/openapi.yaml.

Regras:
- Não editar tests/.
- Não editar spec/openapi.yaml.
- Usar os erros do portão como feedback.
`;

function runVerification() {
  try {
    execSync("npm test -- --runInBand", { stdio: "pipe" });
    execSync("npm run typecheck", { stdio: "pipe" });

    return {
      passed: true,
      failures: "",
    };
  } catch (error: any) {
    return {
      passed: false,
      failures: error.stdout?.toString() || error.message,
    };
  }
}

let feedback = "";

for (let attempt = 1; attempt <= MAX_ITERATIONS; attempt++) {
  const prompt = `
${task}

Tentativa: ${attempt}

Falhas anteriores:
${feedback || "Nenhuma."}
`;

  for await (const msg of query({
    prompt,
    options: {
      allowedTools: ["Edit", "Write", "Bash"],
    },
  })) {
    // Envie para logs, observabilidade ou auditoria.
    console.log(JSON.stringify(msg));
  }

  const gate = runVerification();

  if (gate.passed) {
    console.log("Portão aprovado.");
    process.exit(0);
  }

  feedback = gate.failures;
}

console.error("Limite de iterações atingido.");
process.exit(1);
Enter fullscreen mode Exit fullscreen mode

O padrão é simples:

  1. execute o agente;
  2. rode o portão;
  3. se falhar, injete o erro na próxima tentativa;
  4. pare ao passar ou ao atingir o limite.

Se você está decidindo entre implementar seu próprio loop ou usar uma opção hospedada, veja a comparação entre agentes gerenciados e o SDK do Agente.

Hooks para guardrails determinísticos

Hooks executam comandos em pontos fixos do ciclo de vida do Claude. Eles não dependem do modelo decidir que deve validar algo.

Exemplo: rodar testes sempre que Claude editar ou escrever um arquivo.

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

Isso é útil porque o hook é determinístico. O agente não pode simplesmente “esquecer” de rodar o teste.

Use hooks para:

  • rodar testes após alterações;
  • bloquear comandos perigosos;
  • validar arquivos modificados;
  • registrar eventos;
  • impedir edições em diretórios críticos.

Agendador para iniciar execuções

Um fluxo autônomo precisa de um gatilho.

Em servidores Linux, use cron:

# Todos os dias úteis às 7h
0 7 * * 1-5 cd /srv/api && claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Bash" \
  >> logs/run-$(date +\%F).log 2>&1
Enter fullscreen mode Exit fullscreen mode

Para deixar mais seguro, encapsule em um script:

#!/usr/bin/env bash
set -euo pipefail

cd /srv/api

RUN_ID="$(date +%F-%H%M%S)"
LOG_FILE="logs/run-${RUN_ID}.log"

git checkout -B "agent/nightly-${RUN_ID}"

claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> "$LOG_FILE" 2>&1

npm test -- --runInBand
npm run typecheck

echo "Execução concluída: $RUN_ID"
Enter fullscreen mode Exit fullscreen mode

Depois, o cron chama apenas o script:

0 7 * * 1-5 /srv/api/scripts/run-nightly-agent.sh
Enter fullscreen mode Exit fullscreen mode

Desenhe o loop, não o prompt

A pergunta principal não é:

O que devo dizer ao Claude?
Enter fullscreen mode Exit fullscreen mode

A pergunta útil é:

Que loop faria Claude corrigir o próprio trabalho com base em sinais confiáveis?
Enter fullscreen mode Exit fullscreen mode

O agente gera soluções rapidamente, mas não é uma fonte confiável de verdade. O portão fornece esse sinal. A confiança do modelo deixa de importar; o que importa é o veredito do teste.

Esse padrão também é discutido em pare de dar prompts ao seu agente de codificação, construa o loop em vez disso.

Uma especificação clara também vence um prompt “esperto”. Um arquivo como design.md ou AGENTS.md dá ao agente:

  • intenção;
  • restrições;
  • arquivos permitidos;
  • definição de concluído;
  • exemplos de entrada e saída;
  • critérios de validação.

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

Vamos implementar o padrão em um caso comum: manter endpoints de API sincronizados com uma especificação OpenAPI.

Objetivo:

Todos os dias às 7h, Claude verifica se a implementação dos endpoints está alinhada ao contrato OpenAPI. Se encontrar divergências, corrige. Se os testes passarem, abre um PR. Se falhar, envia um relatório.
Enter fullscreen mode Exit fullscreen mode

Estrutura sugerida 

.
├── spec/
│   └── openapi.yaml
├── src/
│   └── orders/
├── tests/
│   └── orders.test.ts
├── tasks/
│   └── api-maintenance.md
├── scripts/
│   ├── run-agent.sh
│   └── verify-api.sh
└── AGENTS.md
Enter fullscreen mode Exit fullscreen mode

Especificação da tarefa

tasks/api-maintenance.md:

# Manutenção de API

Sincronizar a implementação dos endpoints de orders com spec/openapi.yaml.

## Escopo permitido

- src/orders/**
- src/shared/validation/**

## Arquivos proibidos

- spec/openapi.yaml
- tests/**
- package.json
- package-lock.json

## Critérios de sucesso

- npm test passa.
- npm run typecheck passa.
- Todas as respostas seguem o schema OpenAPI.
- Erros de validação retornam 422.
- Campos ausentes são rejeitados.
Enter fullscreen mode Exit fullscreen mode

Script de verificação

scripts/verify-api.sh:

#!/usr/bin/env bash
set -euo pipefail

npm test -- --runInBand
npm run typecheck
Enter fullscreen mode Exit fullscreen mode

Esse script é o portão. Ele deve ser externo ao agente e protegido contra edição.

Script de execução

scripts/run-agent.sh:

#!/usr/bin/env bash
set -euo pipefail

MAX_ATTEMPTS=5
FEEDBACK_FILE=".agent-feedback.txt"
LOG_DIR="logs"

mkdir -p "$LOG_DIR"
echo "" > "$FEEDBACK_FILE"

for attempt in $(seq 1 "$MAX_ATTEMPTS"); do
  echo "Tentativa $attempt"

  claude -p "$(cat tasks/api-maintenance.md)

Falhas anteriores:
$(cat "$FEEDBACK_FILE")
" \
    --allowedTools "Edit,Write,Bash" \
    --output-format json \
    >> "$LOG_DIR/agent-$(date +%F).log" 2>&1

  if ./scripts/verify-api.sh > "$FEEDBACK_FILE" 2>&1; then
    echo "Portão aprovado."
    exit 0
  fi

  echo "Portão falhou. Reexecutando com feedback."
done

echo "Falha após $MAX_ATTEMPTS tentativas."
cat "$FEEDBACK_FILE"
exit 1
Enter fullscreen mode Exit fullscreen mode

Gatilho com cron 

0 7 * * 1-5 cd /srv/api && ./scripts/run-agent.sh >> logs/cron.log 2>&1
Enter fullscreen mode Exit fullscreen mode

Entrega

Depois que o portão passa, você pode abrir um PR com GitHub CLI:

gh pr create \
  --title "chore: sync API implementation with OpenAPI spec" \
  --body "Atualização gerada por fluxo Claude headless. Testes e typecheck aprovados."
Enter fullscreen mode Exit fullscreen mode

Se falhar, envie o último erro para o canal da equipe:

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{\"text\":\"Fluxo Claude falhou após 5 tentativas. Verifique logs/agent-$(date +%F).log\"}"
Enter fullscreen mode Exit fullscreen mode

Onde o Apidog entra nesse fluxo

O portão é a parte que torna o fluxo seguro. Para APIs, esse portão precisa validar contrato, schema, status code, corpo da resposta e cenários de erro.

É aqui que o Apidog se encaixa: design de API, schema, mock server e testes automatizados ficam no mesmo workspace. Assim, a especificação e o portão permanecem sincronizados.

Um fluxo prático pode ser:

  1. manter o contrato no Apidog;
  2. executar cenários de teste automatizados;
  3. retornar aprovação/reprovação para o loop do agente;
  4. usar falhas estruturadas como feedback para a próxima tentativa.

O mock server também ajuda quando dependências externas não estão disponíveis. Uma execução às 3h não precisa falhar porque um serviço de terceiros está instável.

Se o agente precisa acessar e inspecionar endpoints como um testador humano, veja o depurador de agente de IA do Apidog. Se preferir montar o portão visualmente em vez de criar um executor manual, baixe o Apidog.

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

Guardrails para execuções não supervisionadas

Esta é a checklist mínima antes de deixar um agente rodar sem supervisão.

1. Use listas de permissões restritas

Não permita tudo por conveniência.

Evite:

--allowedTools "*"
Enter fullscreen mode Exit fullscreen mode

Prefira:

--allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

E limite o que o shell pode executar por sandbox, wrapper ou política de hooks.

2. Limite as iterações

Um loop que não converge deve parar.

const MAX_ITERATIONS = 5;
Enter fullscreen mode Exit fullscreen mode

Se o agente não consegue passar no portão em cinco tentativas, o problema provavelmente precisa de humano, especificação melhor ou decomposição da tarefa.

3. Defina limite de custo

Loops não supervisionados podem consumir tokens sem ninguém perceber.

Registre por execução:

  • número de tentativas;
  • tokens usados;
  • tempo total;
  • custo estimado;
  • resultado final.

As práticas de redução de custos de tokens do agente se aplicam diretamente aqui.

4. Proteja testes e especificações

O agente não deve poder editar o portão.

Se ele pode alterar tests/ ou openapi.yaml para passar, você criou uma máquina para falsificar progresso.

No arquivo de tarefa, deixe explícito:

Arquivos proibidos:
- tests/**
- spec/**
- scripts/verify-api.sh
Enter fullscreen mode Exit fullscreen mode

E reforce isso com hooks ou validações no Git.

5. Use sandbox

Nunca rode o fluxo diretamente no branch principal.

Use:

  • branch descartável;
  • Git worktree;
  • container;
  • workspace isolado;
  • ambiente sem credenciais sensíveis.

Exemplo com branch temporário:

git checkout -B "agent/run-$(date +%F-%H%M%S)"
Enter fullscreen mode Exit fullscreen mode

6. Registre tudo

Você não consegue depurar o que não registrou.

Capture:

  • prompt usado;
  • ferramentas chamadas;
  • arquivos alterados;
  • saída do portão;
  • erro final;
  • tempo e custo da execução.

7. Mantenha um botão de desligamento

Tenha uma forma simples de interromper o fluxo:

if [ -f ".agent-disabled" ]; then
  echo "Agente desativado."
  exit 0
fi
Enter fullscreen mode Exit fullscreen mode

Coloque essa checagem no início do script.

8. Coloque humanos nas extremidades

O humano não precisa aprovar cada edição, mas deve aprovar a tarefa inicial ou o PR final.

Padrões de conexão e falhas comuns são discutidos em conexão de ferramentas de fluxo de trabalho agêntico.

Erros comuns

Sem portão, só autorrelato

Se a verificação é:

Claude, você terminou?
Enter fullscreen mode Exit fullscreen mode

Você não tem automação confiável. Tem um chatbot sem supervisão.

O portão deve ser externo ao agente.

Tarefa grande demais

Evite:

Manter todo o serviço.
Enter fullscreen mode Exit fullscreen mode

Prefira:

Sincronizar POST /orders com o contrato OpenAPI.
Enter fullscreen mode Exit fullscreen mode

Tarefas pequenas convergem. Tarefas enormes ficam ambíguas.

Permissões abertas demais

Dar acesso irrestrito ao shell em execução não supervisionada aumenta muito o raio de dano.

Prefira escopo mínimo:

--allowedTools "Edit,Write"
Enter fullscreen mode Exit fullscreen mode

Adicione Bash apenas quando necessário e com restrições.

Falha silenciosa

Um fluxo que morre sem alerta é pior do que nenhum fluxo. Sempre notifique:

  • sucesso;
  • falha;
  • limite de iterações;
  • custo excedido;
  • erro inesperado.

Sucesso silencioso

Um agente não deve commitar e seguir sem revisão. Para código de produção, faça o fluxo abrir PR, não merge automático.

Confiar na confiança do modelo

O agente pode dizer que está pronto. O portão decide se está.

Construa para a diferença entre:

Parece correto.
Enter fullscreen mode Exit fullscreen mode

e:

Foi validado.
Enter fullscreen mode Exit fullscreen mode

Se você quiser a arquitetura em mais profundidade, veja o guia sobre design de estrutura de agente.

Conclusão

Construir fluxos Claude que funcionam sem você é menos sobre Claude e mais sobre o sistema em volta dele.

A arquitetura mínima é:

  1. especificação precisa;
  2. execução headless;
  3. portão determinístico;
  4. guardrails rígidos;
  5. entrega clara.

Comece pequeno. Escolha um endpoint, escreva uma especificação objetiva, rode Claude em modo headless, valide com testes, limite as ferramentas, limite as tentativas e envie o resultado para revisão humana.

Para fluxos envolvendo APIs, o conjunto de testes é o portão que torna a execução não supervisionada segura. O Apidog ajuda a manter design, mocking e testes automatizados no mesmo workspace. Baixe-o, conecte o portão e deixe o fluxo rodar enquanto você trabalha em outra coisa.

Top comments (0)