Automatizar flujos de desarrollo con Claude Code

Automatizar un flujo de desarrollo con Claude Code no significa dejar que un agente haga merge sin supervisión. La versión útil es más pequeña y más segura: pedirle que resuma Issue, prepare cambios acotados, revise PR, genere informes de mantenimiento y se detenga cuando una persona debe decidir.

Esta guía muestra ejemplos que puedes copiar y ejecutar con gh, git, node, npm y claude. El patrón funciona porque trata la automatización como un arnés: entradas controladas, acciones permitidas, logs, reintentos, rollback y puntos de aprobación humana.

Define primero el límite de automatización

Etapa	Claude Code puede hacer	La persona decide
Clasificación	Resumir Issue, diff y logs fallidos	Prioridad y criterio de producto
Cambio	Arreglos pequeños, pruebas, documentación	Alcance y publicación
Revisión	Bugs, riesgos de seguridad, pruebas faltantes	Qué sugerencias aceptar
Operación	Revisiones programadas, TODO antiguos, dependencias	Merge, eliminación, release, impacto de cobro

flowchart LR
  A["Issue / PR"] --> B["Prompt pequeño"]
  B --> C["Claude Code"]
  C --> D["Diff y logs"]
  D --> E["Pruebas"]
  E --> F["Aprobación humana"]
  F --> G["PR / release"]

Para el diseño de la canalización completa, consulta también la guía de CI/CD con Claude Code y la guía de Hooks de Claude Code.

Caso de uso 1: crear una rama segura desde un Issue

Este script lee un Issue de GitHub, crea o reutiliza una rama determinista, pide a Claude Code el cambio mínimo, ejecuta pruebas y deja el commit en manos humanas.

Guárdalo 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
Eres el asistente de desarrollo de este repositorio.
Lee el Issue de abajo y aplica el cambio útil más pequeño.

Restricciones:
- Inspecciona los archivos relacionados antes de editar.
- Respeta la arquitectura, los nombres y el estilo de pruebas existentes.
- Si el requisito es ambiguo, deja un TODO o una pregunta en vez de inventar un diseño grande.
- No toques secretos, archivos de entorno ni artículos no relacionados.
- Deja el repositorio listo para ejecutar npm test.
- No hagas commit, push, creación de PR ni 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"

Las protecciones son simples. Si falta ANTHROPIC_API_KEY, el script falla al inicio. La rama es idempotente porque usa siempre el mismo nombre para el mismo Issue. Los logs quedan en .claude-logs, así que puedes auditar qué se pidió y qué prueba falló.

Caso de uso 2: añadir una revisión PR en GitHub Actions

La acción oficial de Claude Code para GitHub Actions puede ejecutarse en eventos de PR. Este flujo solo revisa; no modifica código, no hace push y no hace merge.

Guárdalo 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: |
            Revisa este Pull Request.
            Enfócate en bugs, seguridad, pruebas faltantes, compatibilidad hacia atrás y logs operativos.
            Marca cada hallazgo como high, medium o low y da una sugerencia concreta.
            No edites código, no hagas push y no hagas merge.
          claude_args: |
            --max-turns 6
            --permission-mode plan

Mantén permisos estrechos. Para una revisión de PR, normalmente bastan contents: read y pull-requests: write. Añade issues: write solo si el flujo también comenta en Issue.

Antes de copiar ejemplos antiguos, revisa la referencia oficial de Claude Code CLI, la documentación oficial de Claude Code GitHub Actions y la sintaxis oficial de GitHub Actions. Los ejemplos viejos con @beta o direct_prompt deben migrarse a @v1 y prompt.

Caso de uso 3: informe de mantenimiento con Node.js

Un mantenimiento programado no tiene que cambiar archivos. Un informe que resuma pruebas fallidas, diffs grandes, TODO viejos, falta de logs o riesgo de rollback ya reduce trabajo repetido.

Guárdalo 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 = [
    "Eres el revisor de mantenimiento de este repositorio.",
    "Lee git status y la salida de pruebas, y resume los riesgos de hoy.",
    "No edites, borres, hagas commit ni push.",
    "Agrupa 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 });
}

Si no usas Jest, cambia npm test -- --runInBand por el comando de tu proyecto. El script solo envía los últimos 12000 caracteres de salida para evitar un prompt demasiado largo.

Caso de uso 4: programar con cron o Task Scheduler

En Linux y macOS puedes usar cron. En Windows, usa el Programador de tareas. schedule de GitHub Actions también sirve, pero una ejecución local suele ser mejor si necesitas base de datos local, VPN o credenciales internas.

# Ejecutar a las 08:15 de lunes a viernes
15 8 * * 1-5 cd /path/to/repo && /usr/bin/node scripts/claude-maintenance.mjs >> .claude-logs/cron.log 2>&1

# Registrar una tarea diaria en 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\""

La ejecución programada debe ser idempotente: repetirla no debe crear PR duplicados, comentarios duplicados ni ramas nuevas para el mismo Issue. Usa locks, nombres estables, comprobación de estado y logs.

Caso de uso 5: escribir las aprobaciones humanas en el prompt

Un prompt corto no siempre es más seguro. El prompt de flujo debe decir qué está permitido, qué está prohibido y qué requiere aprobación humana.

claude -p "
Objetivo:
  Aplicar el feedback de revisión del PR #123.

Permitido:
  - Editar archivos de implementación y pruebas relacionados.
  - Ejecutar npm test.
  - Resumir logs fallidos.

Prohibido:
  - git push
  - gh pr merge
  - Mostrar .env o secretos
  - Refactorizaciones no relacionadas

Requiere aprobación humana:
  - Cambios de compatibilidad en respuestas API
  - Migraciones de base de datos
  - Eliminación de pruebas existentes

Informe final:
  - Archivos cambiados
  - Pruebas ejecutadas
  - Riesgos restantes
  - Pasos de rollback
" --max-turns 6 --permission-mode acceptEdits

Para estructurar revisiones, consulta la lista de revisión de Claude Code y el flujo de recibo de verificación.

Fallos que debes diseñar de antemano

Fallo	Qué ocurre	Solución práctica
Prompt demasiado largo	Las restricciones se pierden y la ejecución se alarga	Pasar solo archivos relevantes y el final de logs
Credenciales faltantes	CI falla por ANTHROPIC_API_KEY o GH_TOKEN	Validar variables al inicio
Sin idempotencia	PR, comentarios o ramas duplicadas	Nombres estables, locks y comprobación de estado
Sin logs	Nadie sabe qué intentó el agente	Guardar .claude-logs o artifacts de GitHub
Reintento ingenuo	Un fallo temporal se convierte en escritura duplicada	Reintentar lecturas y revisar estado antes de escribir
Sin rollback	Un commit enorme es difícil de revertir	PR pequeños y notas de rollback
Sin aprobación	El agente toma decisiones de producto o release	Compatibilidad, datos, cobro, borrado y merge requieren persona

Para temas cercanos, lee auditoría de seguridad con Claude Code, estrategias de pruebas con Claude Code y automatización del flujo Git.

CTA de monetización y AdSense

La conversión natural aquí es ayuda práctica. Si trabajas solo, empieza con la chuleta gratuita de Claude Code. Si tu equipo necesita prompts por repositorio, puertas de revisión, política de aprobación y formación, revisa la página de formación y consultoría de Claude Code. Para material de configuración listo para usar, la guía de configuración de Claude Code es el atajo de pago.

No pongas anuncios ni CTA en medio de una secuencia de comandos. Para calidad de AdSense, este tipo de artículo necesita código ejecutable, fallos reales, enlaces oficiales, enlaces internos y un resultado práctico.

Conclusión

La automatización con Claude Code es fiable cuando diseñas primero dónde se detiene. Empieza con clasificación de Issue y revisión de PR. Después añade cambios pequeños. Al final, incorpora mantenimiento programado y puertas de CI con aprobación humana explícita.

En la prueba práctica de Masa, el mayor beneficio no fue crear PR automáticamente, sino guardar logs repetibles de Issue y usar un prompt fijo de revisión. La falta de ANTHROPIC_API_KEY, una salida de pruebas demasiado larga y la repetición sobre la misma rama causaron errores una vez; las validaciones de entorno, recortar logs y usar ramas deterministas facilitaron mucho el siguiente diagnóstico.