Automatizar fluxos de desenvolvimento com Claude Code

Automatizar um fluxo de desenvolvimento com Claude Code não significa deixar um agente fazer merge sem supervisão. A versão segura é menor e mais prática: usar Claude Code para resumir Issue, preparar mudanças pequenas, revisar PR, gerar relatórios de manutenção e parar quando uma pessoa precisa decidir.

Este guia traz exemplos copiáveis com gh, git, node, npm e claude. O padrão funciona porque trata a automação como um suporte para o agente: entradas controladas, ações permitidas, logs, retries, rollback e pontos de aprovação humana.

Defina primeiro o limite da automação

Etapa	Claude Code pode fazer	A pessoa decide
Triagem	Resumir Issue, diff e logs com falha	Prioridade e decisão de produto
Mudança	Correções pequenas, testes, documentação	Escopo e publicação
Revisão	Bugs, riscos de segurança, testes ausentes	Quais sugestões aceitar
Operação	Checagens programadas, TODO antigos, dependências	Merge, exclusão, release, impacto de cobrança

flowchart LR
  A["Issue / PR"] --> B["Prompt pequeno"]
  B --> C["Claude Code"]
  C --> D["Diff e logs"]
  D --> E["Testes"]
  E --> F["Aprovação humana"]
  F --> G["PR / release"]

Para a visão de pipeline completa, leia também o guia de CI/CD com Claude Code e o guia de Hooks do Claude Code.

Caso de uso 1: criar uma branch segura a partir de um Issue

Este script lê um Issue do GitHub, cria ou reutiliza uma branch determinística, pede a menor mudança útil ao Claude Code, executa testes e deixa o commit para você.

Salve como scripts/claude-issue-work.sh.

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

ISSUE_NUMBER="${1:-}"
if [ -z "$ISSUE_NUMBER" ]; then
  echo "Usage: ./scripts/claude-issue-work.sh <issue-number>"
  exit 1
fi

for command_name in git gh claude npm; do
  if ! command -v "$command_name" >/dev/null 2>&1; then
    echo "Missing command: $command_name"
    exit 1
  fi
done

: "${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY before running this script}"

mkdir -p .claude-logs
ISSUE_FILE=".claude-logs/issue-${ISSUE_NUMBER}.md"
LOG_FILE=".claude-logs/issue-${ISSUE_NUMBER}-$(date +%Y%m%d-%H%M%S).log"
BRANCH="claude/issue-${ISSUE_NUMBER}"

gh issue view "$ISSUE_NUMBER" --json title,body,labels --jq '
  "# " + .title + "\n\n" + (.body // "") + "\n\nLabels: " + ([.labels[].name] | join(", "))
' > "$ISSUE_FILE"

if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
  git switch "$BRANCH"
else
  git switch -c "$BRANCH"
fi

PROMPT=$(cat <<PROMPT
Você é o assistente de desenvolvimento deste repositório.
Leia o Issue abaixo e aplique a menor mudança útil.

Restrições:
- Inspecione os arquivos relacionados antes de editar.
- Prefira a arquitetura, nomes e estilo de testes existentes.
- Se o requisito estiver ambíguo, deixe um TODO ou pergunta em vez de inventar um grande desenho.
- Não toque em segredos, arquivos de ambiente nem artigos sem relação.
- Deixe o repositório pronto para npm test.
- Não faça commit, push, criação de PR nem merge.

Issue:
$(cat "$ISSUE_FILE")
PROMPT
)

claude -p "$PROMPT" \
  --max-turns 8 \
  --permission-mode acceptEdits \
  --output-format text 2>&1 | tee "$LOG_FILE"

npm test 2>&1 | tee -a "$LOG_FILE"
git diff --stat | tee -a "$LOG_FILE"

echo "Review the diff, then commit manually if it is correct."
echo "Log: $LOG_FILE"

As proteções evitam problemas comuns. Sem ANTHROPIC_API_KEY, o script para logo no início. A branch é idempotente porque usa o mesmo nome para o mesmo Issue. Os logs ficam em .claude-logs, facilitando entender qual prompt foi usado e qual teste falhou.

Caso de uso 2: revisão de PR no GitHub Actions

A ação oficial Claude Code para GitHub Actions pode rodar em eventos de PR. Este workflow pede apenas revisão; não permite edição, push ou merge.

Salve como .github/workflows/claude-review.yml.

name: Claude Review Gate

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Revise este Pull Request.
            Foque em bugs, segurança, testes ausentes, compatibilidade retroativa e logs operacionais.
            Marque cada achado como high, medium ou low e escreva sugestões concretas.
            Não edite código, não faça push e não faça merge.
          claude_args: |
            --max-turns 6
            --permission-mode plan

Mantenha permissões estreitas. Para revisão de PR, contents: read e pull-requests: write costumam ser o núcleo. Use issues: write apenas se o fluxo também comentar em Issue.

Antes de copiar exemplos antigos, confira a referência oficial do Claude Code CLI, a documentação oficial do Claude Code GitHub Actions e a sintaxe oficial de workflows do GitHub Actions. Exemplos antigos com @beta ou direct_prompt devem ser migrados para @v1 e prompt.

Caso de uso 3: relatório de manutenção com Node.js

Manutenção programada não precisa alterar arquivos. Um relatório sobre testes falhando, diffs grandes, TODO antigos, falta de logs ou risco de rollback já reduz retrabalho.

Salve como scripts/claude-maintenance.mjs.

#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";

const logDir = ".claude-logs";
const lockFile = join(logDir, "maintenance.lock");
const stamp = new Date().toISOString().replace(/[:.]/g, "-");
const logFile = join(logDir, `maintenance-${stamp}.log`);

function fail(message) {
  console.error(message);
  process.exit(1);
}

function run(command, args, options = {}) {
  const result = spawnSync(command, args, {
    encoding: "utf8",
    shell: process.platform === "win32",
    ...options,
  });

  const output = `${result.stdout || ""}${result.stderr || ""}`;
  if (result.status !== 0) {
    writeFileSync(logFile, output);
    fail(`Command failed: ${command} ${args.join(" ")}. See ${logFile}`);
  }
  return output;
}

if (!process.env.ANTHROPIC_API_KEY) {
  fail("Set ANTHROPIC_API_KEY before running this script.");
}

mkdirSync(logDir, { recursive: true });
if (existsSync(lockFile)) {
  fail(`Another maintenance run is active: ${lockFile}`);
}

writeFileSync(lockFile, String(process.pid));

try {
  const status = run("git", ["status", "--short"]);
  const tests = run("npm", ["test", "--", "--runInBand"]);
  const prompt = [
    "Você é o revisor de manutenção deste repositório.",
    "Leia o git status e a saída dos testes, depois resuma os riscos de hoje.",
    "Não edite, apague, faça commit nem push.",
    "Agrupe por credentials / idempotency / retry / rollback / logs / human approval.",
    "",
    "git status:",
    status || "(clean)",
    "",
    "test output:",
    tests.slice(-12000),
  ].join("\n");

  const review = run("claude", [
    "-p",
    prompt,
    "--max-turns",
    "5",
    "--permission-mode",
    "plan",
    "--output-format",
    "text",
  ]);

  writeFileSync(logFile, review);
  console.log(`Maintenance report written to ${logFile}`);
} finally {
  rmSync(lockFile, { force: true });
}

Se você não usa Jest, troque npm test -- --runInBand pelo comando de teste do seu projeto. O script envia só os últimos 12000 caracteres para evitar um prompt longo demais.

Caso de uso 4: agendar com cron ou Agendador de Tarefas

No Linux e macOS, use cron. No Windows, use o Agendador de Tarefas. O schedule do GitHub Actions também funciona, mas execução local costuma ser melhor quando há banco local, VPN ou credenciais internas.

# Executar às 08:15 em dias úteis
15 8 * * 1-5 cd /path/to/repo && /usr/bin/node scripts/claude-maintenance.mjs >> .claude-logs/cron.log 2>&1

# Registrar uma tarefa diária no Windows
schtasks /Create /TN "ClaudeMaintenance" /SC DAILY /ST 08:15 /F /TR "powershell -NoProfile -ExecutionPolicy Bypass -Command \"cd C:\path\to\repo; node scripts\claude-maintenance.mjs\""

Automação programada precisa ser idempotente: rodar duas vezes não deve criar PR, comentário ou branch duplicados. Use locks, nomes estáveis, checagem de estado e logs.

Caso de uso 5: colocar aprovações humanas no prompt

Um prompt curto nem sempre é mais seguro. Um bom prompt de workflow diz o que é permitido, o que é proibido e o que exige aprovação humana.

claude -p "
Objetivo:
  Aplicar o feedback de revisão do PR #123.

Permitido:
  - Editar arquivos relacionados de implementação e testes.
  - Executar npm test.
  - Resumir logs com falha.

Proibido:
  - git push
  - gh pr merge
  - Mostrar .env ou segredos
  - Refatorações sem relação

Exige aprovação humana:
  - Mudanças de compatibilidade em respostas API
  - Migrações de banco de dados
  - Remoção de testes existentes

Relatório final:
  - Arquivos alterados
  - Testes executados
  - Riscos restantes
  - Passos de rollback
" --max-turns 6 --permission-mode acceptEdits

Para estruturar revisões, veja a lista de revisão do Claude Code e o workflow de recibo de verificação.

Falhas que você deve prever

Falha	O que acontece	Correção prática
Prompt longo demais	Restrições se perdem e a execução fica lenta	Enviar só arquivos relevantes e o fim dos logs
Credenciais ausentes	CI falha em ANTHROPIC_API_KEY ou GH_TOKEN	Validar variáveis no início
Sem idempotência	PR, comentários ou branches duplicados	Nomes estáveis, locks e checagem de estado
Sem logs	Ninguém sabe o que o agente tentou	Salvar .claude-logs ou artifacts do GitHub
Retry ingênuo	Falha temporária vira escrita duplicada	Repetir leituras e checar estado antes de escrever
Sem rollback	Um commit grande fica difícil de reverter	PR pequenos e notas de rollback
Sem aprovação	O agente toma decisões de produto ou release	Compatibilidade, dados, cobrança, exclusão e merge ficam com humanos

Para temas próximos, leia auditoria de segurança com Claude Code, estratégias de teste com Claude Code e automação de fluxo Git.

CTA de monetização e AdSense

A conversão natural deste tema é ajuda prática. Quem trabalha sozinho pode começar pela folha gratuita do Claude Code. Equipes que precisam de prompts por repositório, portas de revisão, política de aprovação e treinamento podem usar a página de treinamento e consultoria Claude Code. Para material pronto de configuração, o guia de configuração Claude Code é o atalho pago.

Não coloque anúncios ou CTA no meio de uma sequência de comandos. Para qualidade do AdSense, este artigo precisa de código executável, falhas concretas, links oficiais, links internos e resultado testado.

Conclusão

A automação de workflows com Claude Code fica confiável quando os pontos de parada vêm primeiro. Comece por triagem de Issue e revisão de PR. Depois adicione pequenas mudanças. Por fim, use manutenção programada e gates de CI com aprovação humana explícita.

No teste prático de Masa, o maior ganho não foi criar PR automaticamente, mas manter logs repetíveis de Issue e um prompt fixo de revisão. Falta de ANTHROPIC_API_KEY, saída de teste longa demais e reexecução na mesma branch causaram uma falha cada; validação de ambiente, corte do fim dos logs e nomes determinísticos de branch tornaram o diagnóstico seguinte bem mais fácil.