DEV Community

Cover image for Cómo crear workflows de Claude automáticos
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo crear workflows de Claude automáticos

Hay una frase que resume hacia dónde va la codificación agéntica: el objetivo no es escribir un mejor “prompt”, sino diseñar un flujo de trabajo que se ejecute sin que tú lo supervises. Usar Claude como una ventana de chat funciona, pero limita la producción a un agente que estás vigilando activamente. El salto real ocurre cuando Claude se activa por horario o evento, ejecuta una tarea, verifica sus propios resultados y solo escala a un humano cuando necesita una decisión.

Prueba Apidog hoy

En resumen

Un flujo de trabajo de Claude que se ejecuta sin intervención humana necesita cinco piezas:

  1. Una especificación escrita y precisa.
  2. Ejecución sin interfaz, por ejemplo con claude -p.
  3. Una puerta de verificación determinista que devuelva aprobado o fallido.
  4. Barandales estrictos: permisos por lista blanca, límite de iteraciones, límite de costos, logs y un interruptor de apagado.
  5. Una entrega clara: notificación, PR, alerta o escalada.

Claude Code, el SDK de Agente de Claude, los hooks y un programador como cron o launchd te dan la base para construirlo. El riesgo no es usar un agente. El riesgo es ejecutarlo sin supervisión, sin una puerta de validación y sin límites.

Por qué “se ejecuta sin ti” es el verdadero objetivo

El chat supervisado tiene un cuello de botella: tú. Cada iteración espera a que leas la salida, evalúes el resultado y escribas el siguiente paso. El modelo responde en segundos, pero el flujo se detiene durante minutos mientras cambias de contexto.

Un flujo desatendido elimina ese bloqueo:

trigger → agente → verificación → corrección o entrega → notificación
Enter fullscreen mode Exit fullscreen mode

La ventaja no es solo velocidad. Es paralelismo. Una vez que un flujo se ejecuta solo, puedes escalar creando más flujos, no escribiendo más rápido. Es el mismo salto que explicamos en flujos de trabajo dinámicos de Claude Code, donde una sesión puede ramificarse en varios agentes paralelos.

Pero ejecutar sin supervisión sube el riesgo. En una sesión interactiva, detectas un error cuando revisas el diff. En una ejecución autónoma, el agente puede cometer el error, ejecutar el siguiente paso y seguir avanzando. Por eso el foco cambia del “prompt engineering” al diseño del sistema: necesitas una máquina delimitada, verificable y observable.

Anthropic plantea una idea similar en la construcción de agentes efectivos: el apalancamiento viene del entorno que rodea al modelo, no de un único mensaje más inteligente.

Las cinco partes de un flujo de trabajo desatendido

Si omites una de estas piezas, el flujo puede hacer lo incorrecto con confianza o no detenerse nunca.

1. Especificación precisa

El agente debe leer una descripción clara al inicio de cada ejecución.

Mal:

Arregla la API.
Enter fullscreen mode Exit fullscreen mode

Mejor:

Implementa POST /orders.

Criterios:
- Devuelve 201 cuando el cuerpo es válido.
- Valida el body contra el esquema OpenAPI.
- Rechaza campos faltantes con 422.
- No modifiques los tests ni el archivo openapi.yaml.
Enter fullscreen mode Exit fullscreen mode

Una especificación vaga produce trabajo vago. Una especificación verificable permite automatizar.

2. Ejecución sin interfaz

Claude debe ejecutarse sin que haya una persona en el teclado. Eso significa usar modo no interactivo, no la ventana de chat.

3. Puerta de verificación

La puerta debe ser externa al modelo y devolver un resultado objetivo:

  • tests unitarios;
  • tests de integración;
  • validación de tipos;
  • validación de esquema;
  • pruebas de contrato;
  • ejecución de escenarios de API.

El agente no decide si terminó. La puerta lo decide.

4. Barandales

Un flujo desatendido necesita límites explícitos:

  • herramientas permitidas;
  • número máximo de intentos;
  • límite de gasto;
  • sandbox;
  • logs;
  • apagado manual;
  • escalada si no converge.

5. Entrega

El flujo nunca debe terminar en silencio. Al finalizar debe:

  • abrir un PR;
  • enviar una notificación;
  • crear una alerta;
  • adjuntar logs;
  • escalar con el último fallo.

El silencio no es éxito.

Bloques de construcción de Claude

Modo sin interfaz con claude -p

El modo de impresión de Claude Code ejecuta un prompt de forma no interactiva y termina. Es la base para cualquier flujo desatendido.

claude -p "Implementa el endpoint de pedidos según spec.md, luego ejecuta la suite de pruebas" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> run.log 2>&1
Enter fullscreen mode Exit fullscreen mode

El flag más importante aquí es --allowedTools.

En una sesión interactiva, apruebas acciones manualmente. En una ejecución sin interfaz no hay nadie para aprobarlas, así que la lista blanca es tu control principal.

Empieza con permisos mínimos:

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

Luego amplía solo si la tarea lo requiere:

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

Evita dar acceso amplio a shell si el trabajo no lo necesita. La documentación completa está en la documentación de Claude Code.

SDK de Agente de Claude

Cuando un comando de shell no basta, el SDK de Agente de Claude permite controlar Claude desde Python o TypeScript.

La ventaja es que puedes construir el bucle completo en código:

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

const MAX_ITERATIONS = 8;

const task = `
Implementa POST /orders según spec.md.
No modifiques los tests ni openapi.yaml.
`;

let feedback = "";

for (let attempt = 0; attempt < MAX_ITERATIONS; attempt++) {
  for await (const msg of query({
    prompt: `${task}

Fallos anteriores:
${feedback}`,
    options: {
      allowedTools: ["Edit", "Write", "Bash"],
    },
  })) {
    // Registra o transmite mensajes mientras el agente trabaja
    console.log(msg);
  }

  const gate = runVerification();

  if (gate.passed) {
    console.log("Puerta verde. Flujo completado.");
    break;
  }

  feedback = gate.failures;

  if (attempt === MAX_ITERATIONS - 1) {
    notifyHuman({
      status: "failed",
      reason: gate.failures,
    });
  }
}
Enter fullscreen mode Exit fullscreen mode

La estructura importante es esta:

ejecutar agente → verificar → si falla, pasar el fallo como contexto → repetir → entregar o escalar
Enter fullscreen mode Exit fullscreen mode

Si estás decidiendo entre construir tu propio bucle o usar una opción alojada, esta comparación de agentes gestionados vs el SDK de Agente explica cuándo conviene cada opción.

Hooks para barandales deterministas

Los hooks ejecutan comandos propios en puntos fijos del ciclo de vida de Claude. No dependen del modelo. Eso los hace útiles para reglas que no quieres que el agente pueda omitir.

Ejemplo: ejecutar tests después de cada edición.

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

Como el hook es código determinista, se activa siempre que coincida el evento. El agente no puede decidir saltárselo.

Programador para iniciar ejecuciones

Un flujo que se ejecuta sin ti necesita un disparador que también funcione sin ti.

En un servidor, usa cron. En macOS, usa launchd.

Ejemplo con cron:

# Días laborables a las 7:00:
# ejecuta el flujo de mantenimiento y guarda logs
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

Esa es la columna vertebral:

cron → claude -p → especificación → edición → hooks/tests → logs → entrega
Enter fullscreen mode Exit fullscreen mode

Diseña el bucle, no el prompt

La pregunta correcta no es:

¿Qué debería decirle a Claude?
Enter fullscreen mode Exit fullscreen mode

La pregunta útil es:

¿Qué bucle hace que Claude reciba automáticamente el siguiente contexto correcto?
Enter fullscreen mode Exit fullscreen mode

Claude es un generador rápido, pero no tiene una garantía fiable de que su salida sea correcta. El bucle aporta esa garantía mediante una puerta externa. Esta idea se desarrolla más en deja de “prompting” a tu agente de codificación, construye el bucle en su lugar.

Por eso una especificación clara supera a un prompt ingenioso. Un archivo como design.md o AGENTS.md puede capturar:

# Objetivo

Mantener los endpoints de pedidos sincronizados con openapi.yaml.

# Restricciones

- No modificar openapi.yaml.
- No modificar tests.
- No hacer commits directos a main.
- Solo editar archivos en src/orders.

# Definición de terminado

- npm test pasa.
- Los tests de contrato pasan.
- El endpoint POST /orders devuelve 201 con payload válido.
- Payloads inválidos devuelven 422.
Enter fullscreen mode Exit fullscreen mode

Ese archivo se convierte en contexto estable para cada ejecución.

Ejemplo práctico: mantenimiento desatendido de una API

Supón que quieres mantener endpoints sincronizados con una especificación OpenAPI. El flujo se ejecuta cada mañana y nunca debe enviar un endpoint roto.

1. Especificación

El contrato vive en un archivo OpenAPI. El comportamiento vive en tests.

Ejemplo de tarea:

# Tarea

Sincroniza la implementación de la API con openapi.yaml.

# Alcance

- Revisar endpoints en /orders.
- Añadir endpoints faltantes.
- Corregir códigos de estado.
- Corregir validación de request body.
- Corregir formas de respuesta.

# No permitido

- No editar openapi.yaml.
- No editar archivos de test.
- No hacer commit directo.

# Puerta

Ejecutar:
npm test
npm run contract:test
Enter fullscreen mode Exit fullscreen mode

2. Disparador

Un cron inicia Claude a las 7:00.

0 7 * * 1-5 cd /srv/api && claude -p "$(cat tasks/api-maintenance.md)" \
  --allowedTools "Edit,Write,Bash" \
  >> logs/api-maintenance-$(date +\%F).log 2>&1
Enter fullscreen mode Exit fullscreen mode

3. Generación

El agente compara implementación, tests y especificación. Puede:

  • añadir endpoints faltantes;
  • ajustar validaciones;
  • corregir respuestas;
  • reparar códigos de estado;
  • ejecutar tests.

4. Puerta

La puerta ejecuta pruebas contra el servicio.

Ejemplo de salida útil:

{
  "passed": false,
  "failures": [
    "POST /orders sin customer_id esperaba 422, obtuvo 500",
    "El campo response.total es string, pero el esquema espera number"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Esa salida se convierte en el siguiente prompt del agente.

5. Bucle o escalada

Si la puerta falla, el flujo reintenta con el fallo estructurado:

Corrige estos fallos específicos:

- POST /orders sin customer_id esperaba 422, obtuvo 500.
- response.total debe ser number, no string.

No modifiques tests ni openapi.yaml.
Enter fullscreen mode Exit fullscreen mode

Si la puerta pasa, el flujo abre un PR. Si supera el límite de intentos, envía una alerta.

6. Entrega

El resultado debe ser uno de estos:

✅ PR listo para revisión
Enter fullscreen mode Exit fullscreen mode

o:

❌ Flujo fallido tras 8 intentos
Último fallo:
POST /orders sin customer_id esperaba 422, obtuvo 500
Enter fullscreen mode Exit fullscreen mode

Nunca debe ser un commit silencioso.

La puerta del paso 4 es lo que hace seguro este flujo. Sin ella, el agente podría editar código y declarar éxito basándose en su propia interpretación.

Aquí es donde Apidog encaja en un flujo autónomo: el diseño de API, el esquema, el servidor de simulación y las pruebas automatizadas viven en un solo espacio de trabajo. Eso ayuda a mantener sincronizadas la especificación y la puerta de validación. Puedes apuntar la ejecución a un escenario de prueba de Apidog y obtener un aprobado/fallo validado por esquema en cada iteración. El servidor de simulación también permite reemplazar dependencias no disponibles, para que una ejecución nocturna no se bloquee por un tercero inestable.

Los equipos que conectan el acceso del agente a endpoints mediante el depurador de agentes de IA de Apidog permiten que el agente inspeccione endpoints de forma parecida a como lo haría un tester humano. Si prefieres construir la puerta visualmente en lugar de codificarla desde cero, puedes descargar Apidog.

Imagen del flujo de trabajo

Barandales para ejecuciones desatendidas

Un agente sin supervisión necesita límites estrictos, no buenas intenciones.

Usa listas blancas de permisos

Sin interfaz, la lista blanca es la frontera principal.

Mejor:

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

Con más riesgo:

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

Evita comandos destructivos o shell ilimitado salvo que el entorno esté aislado.

Limita iteraciones

Un flujo que no consigue una puerta verde en N intentos debe detenerse.

const MAX_ITERATIONS = 8;
Enter fullscreen mode Exit fullscreen mode

Si llega al límite:

notifyHuman({
  status: "failed",
  reason: lastGateFailure,
});
Enter fullscreen mode Exit fullscreen mode

No permitas bucles infinitos.

Establece un techo de costos

Los bucles desatendidos pueden consumir tokens sin que nadie lo note. Registra gasto por ejecución y corta cuando supere el límite.

if (runCostUsd > MAX_COST_USD) {
  notifyHuman({
    status: "stopped",
    reason: "Cost limit reached",
  });

  process.exit(1);
}
Enter fullscreen mode Exit fullscreen mode

Estas prácticas se alinean con las notas sobre cómo reducir los costos de tokens del agente.

Protege la puerta

No permitas que el agente edite:

  • tests;
  • especificaciones;
  • snapshots críticos;
  • scripts de verificación.

Si el agente puede cambiar la prueba para que pase, has automatizado la falsificación del progreso.

Ejemplo de restricción en la especificación:

No modifiques:
- openapi.yaml
- tests/**
- contract-tests/**
- scripts/verify.sh
Enter fullscreen mode Exit fullscreen mode

Ejecuta en sandbox

No ejecutes el trabajo desatendido directamente sobre main.

Usa:

  • rama temporal;
  • git worktree;
  • contenedor;
  • workspace aislado.

Ejemplo:

git worktree add ../api-agent-run -b agent/nightly-$(date +%F)
cd ../api-agent-run
claude -p "$(cat tasks/api-maintenance.md)" --allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

Registra todo

Cada ejecución debe dejar evidencia:

mkdir -p logs

claude -p "$(cat tasks/api-maintenance.md)" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> logs/run-$(date +%F-%H%M).jsonl 2>&1
Enter fullscreen mode Exit fullscreen mode

No puedes depurar una ejecución que no registraste.

Mantén un interruptor de apagado

Implementa una condición simple que detenga el flujo.

if [ -f /srv/api/STOP_AGENT_RUNS ]; then
  echo "Agent runs disabled"
  exit 0
fi
Enter fullscreen mode Exit fullscreen mode

Colócala al inicio del script programado.

Mantén aprobación humana en los bordes

“Sin ti” no significa “sin humanos nunca”.

Patrones seguros:

humano aprueba tarea → agente itera → puerta valida → PR para humano
Enter fullscreen mode Exit fullscreen mode

o:

cron inicia → agente itera → puerta valida → humano aprueba merge
Enter fullscreen mode Exit fullscreen mode

La persona no debe estar en el bucle interno, pero sí puede estar al inicio o al final. Los detalles de conexión y fallos comunes se relacionan con los patrones de cableado y trampas de las herramientas del flujo de trabajo agéntico.

Errores comunes

No tener puerta

Si la única verificación es:

Claude, ¿terminaste?
Enter fullscreen mode Exit fullscreen mode

no tienes un flujo de trabajo autónomo. Tienes un chatbot sin supervisión.

La puerta debe estar fuera del agente.

Dar una tarea demasiado grande

Mal:

Mantén todo el servicio.
Enter fullscreen mode Exit fullscreen mode

Mejor:

Sincroniza POST /orders con openapi.yaml.
Enter fullscreen mode Exit fullscreen mode

Las tareas pequeñas convergen. Las tareas enormes se atascan.

Permisos demasiado amplios

Dar todas las herramientas por comodidad aumenta el radio de impacto cuando nadie está mirando. Usa permisos mínimos y sandbox.

Éxito o fallo silencioso

Un flujo que hace commit sin avisar, o falla sin alerta, es peor que no tener flujo. Siempre entrega un resultado visible.

Confiar en el autoinforme del modelo

Claude puede decir que terminó. La puerta decide si terminó.

Diseña para la diferencia entre:

parece hecho
Enter fullscreen mode Exit fullscreen mode

y:

está hecho
Enter fullscreen mode Exit fullscreen mode

Si quieres profundizar en la arquitectura, el desglose del diseño del arnés del agente explica cómo encajan estas piezas a escala.

La conclusión

Construir flujos de trabajo de Claude que se ejecuten sin tu intervención tiene menos que ver con Claude y más con el sistema que lo envuelve.

Las cinco piezas son:

  1. especificación precisa;
  2. ejecución sin interfaz;
  3. puerta de verificación determinista;
  4. barandales estrictos;
  5. entrega limpia.

Empieza con un flujo pequeño. Escribe una especificación estricta, ejecútala con claude -p, valida con una puerta rápida, limita herramientas, corta por iteraciones, aísla el workspace y notifica al finalizar o fallar.

Para cualquier flujo que toque APIs, la suite de pruebas es la puerta que hace segura la ejecución desatendida. Apidog reúne diseño, simulación y pruebas automatizadas en un solo espacio de trabajo para construir esa puerta. Puedes descargarlo, conectar la verificación y dejar que el flujo haga sus ciclos mientras tú haces otra cosa.

Top comments (0)