Claude Academy
Cargando

Tareas programadas y headless

Lección 67 min
Cargando

Tareas programadas y headless

Una vez que confías en que Claude haga una tarea, el siguiente paso es dejar de hacerla manualmente. Si es el mismo prompt en un disparador recurrente, no deberías tener que quedarte ahí sentado para iniciarlo tú mismo cada vez. Esta lección cubre dos formas de delegar ese trabajo: las tareas programadas en la nube (antes llamadas rutinas), donde no construyes nada, y el modo headless, donde obtienes control total desde tus propios scripts.

Piénsalo como un espectro. En un extremo tienes las tareas programadas en la nube que se ejecutan en la infraestructura administrada de Anthropic. En el otro extremo tienes el modo headless y el Agent SDK, que ejecutan Claude Code desde tu propio código. Empecemos por el extremo donde construyes menos.

Tareas programadas: un prompt guardado que se ejecuta en la nube

Una tarea programada en la nube es la forma más directa de automatizar el trabajo repetitivo. No hay script ni servidor. Agrupa tres cosas: un prompt, el repositorio sobre el que trabaja y cualquier conector que necesite. Luego ejecuta ese conjunto en la nube cada vez que se activa.

La parte clave es que la infraestructura es de Anthropic. No hay ninguna máquina tuya que deba permanecer encendida toda la noche, y no hay ningún archivo de flujo de trabajo que debas mantener. Describes el trabajo una vez y simplemente se ejecuta.

Una tarea programada no necesita una programación. Puede activarse con algunos tipos de disparadores:

  • Una programación cron, como todas las mañanas a las 9am.
  • Una solicitud HTTP POST a su endpoint de API, para que tu propio código pueda iniciarla.
  • Un evento de GitHub, como la llegada de un nuevo pull request.

Cualquier cosa que sea el mismo prompt en un disparador recurrente es un buen candidato. Una auditoría matutina de dependencias. Un clasificador de PR que se activa cuando llega un nuevo pull request. Un escaneo diario de tus tickets de Sentry para determinar qué es más urgente.

Este es el modelo mental de lo que une una tarea programada: un prompt, el repositorio, los conectores y un disparador.

Dos formas de crear una

Puedes crear una tarea programada desde la web en claude.ai/code/routines. Le das un nombre, escribes las instrucciones que describen lo que Claude debe hacer en cada sesión, eliges un repositorio y seleccionas un disparador.

También puedes crear una sin salir de Claude Code, sin dejar tu terminal. Simplemente ejecuta el comando /schedule y describe lo que quieres en lenguaje natural, por ejemplo:

/schedule daily dependency audit at 9am

La misma idea, desde cualquiera de los dos puntos de entrada. Elige el que mejor se adapte a tu flujo.

Tres cosas que debes saber antes de confiar en las tareas programadas en la nube

Antes de apoyarte en las tareas programadas en la nube para algo importante, ten en cuenta estos tres límites.

  • Las tareas programadas en la nube son una vista previa de investigación. El comportamiento y los límites seguirán cambiando, así que no te sorprendas si las cosas cambian.
  • Una programación recurrente se ejecuta como máximo cada hora. Si necesitas algo más frecuente, una tarea programada en la nube no es la herramienta adecuada.
  • Las ejecuciones comienzan desde una copia nueva de tu rama predeterminada y envían los cambios a una rama claude/, a menos que tu prompt indique otra rama. Cuando un evento de pull request de GitHub activa la ejecución, el repositorio del pull request comienza desde el commit principal (head commit) del pull request en su lugar, siempre que sea el primer repositorio de la tarea programada. Para controlar a qué ramas puede enviar cambios una ejecución, usa reglas de protección de ramas o conjuntos de reglas en GitHub. GitHub las aplica al acceso de GitHub que conectaste, así que una regla que tu acceso pueda eludir no bloqueará el envío.

Modo headless: cuando necesitas tu propio entorno

Las tareas programadas en la nube son excelentes cuando el trabajo puede ejecutarse en la infraestructura de Anthropic. Pero a veces el trabajo necesita tu entorno, o lógica envuelta alrededor de la ejecución. Ahí es cuando pasas al modo headless, que la documentación ahora llama modo no interactivo.

El núcleo del modo headless es la bandera -p (abreviatura de --print). Ejecuta Claude Code como un comando de una sola vez sin interfaz interactiva. Lee la entrada estándar y escribe la salida estándar, así que se puede canalizar como cualquier otra herramienta de shell:

claude -p "summarize the changes in this diff"

Algo que vale la pena saber: por sí sola, -p carga el mismo contexto que cargaría una sesión interactiva, incluyendo hooks, skills, plugins, servidores MCP y el archivo CLAUDE.md. Para omitir todo eso, agrega --bare, que se cubre más adelante.

Obtener salida estructurada de vuelta

Como el modo headless se canaliza como cualquier herramienta de shell, a menudo querrás recibir datos estructurados en lugar de prosa. Puedes combinar un esquema JSON con el formato de salida JSON, y Claude restringirá su salida para que coincida con tu esquema.

El objeto que coincide con tu esquema llega al campo structured_output de la respuesta JSON. Así que puedes extraerlo con un comando jq y canalizarlo hacia una base de datos u otro script:

bash
claude -p "Extract the exported function names from src/core/style.js" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output.functions'

Eso te da un arreglo limpio que puedes entregar a lo que venga después.

Automatización de varios pasos con sesiones

Para trabajos que ocurren en varios pasos, no tienes que meter todo en un solo comando. Captura el ID de la sesión desde la salida JSON y reanúdala más tarde:

claude --resume "$(jq -r .session_id /tmp/plan.json)"

Un script inicia el trabajo. Otro lo reanuda más tarde con el contexto completo. Esto es útil cuando la primera pasada produce un plan y una segunda pasada lo lleva a cabo.

Ejecuciones consistentes para CI

Cuando CI necesita la misma configuración en cada máquina, hay un modo diseñado para eso.

La bandera --bare omite el descubrimiento automático de hooks, skills, plugins, servidores MCP y el archivo CLAUDE.md. Obtienes Claude con las herramientas Bash, lectura de archivos y edición de archivos, más lo que pases con una bandera como --settings o --mcp-config. Así, cada máquina parte de la misma configuración, y el inicio es más rápido. El modo bare no usa el inicio de sesión de tu suscripción, así que configura primero ANTHROPIC_API_KEY.

El Agent SDK: Claude Code dentro de tu propia aplicación

El último paso en el espectro es el Agent SDK. Esto te da una biblioteca que incorpora Claude Code dentro de tus propias aplicaciones de TypeScript o Python.

Ambos lenguajes exponen una función query y las mismas primitivas que la CLI. Pasas un prompt más opciones, como:

  • allowedTools para controlar lo que Claude puede hacer,
  • una indicación del sistema,
  • y un modo de permisos.

Luego iteras sobre los mensajes que Claude transmite de vuelta y los manejas como tu aplicación lo necesite. Es el mismo motor que la CLI, solo que invocable desde dentro de tu producto.

¿Cuál deberías usar?

Aquí tienes la guía rápida de decisión:

  • Las tareas programadas en la nube son la opción predeterminada para trabajo repetitivo. Se ejecutan en la infraestructura de Anthropic sin nada que tengas que alojar.
  • El modo headless con -p es para cuando el trabajo necesita tu pipeline y quieres canalizar datos a través de un script.
  • --bare es para cuando CI necesita la misma configuración en cada máquina.
  • El Agent SDK es para cuando el trabajo pertenece dentro de tu propio producto.

Empieza con las tareas programadas en la nube. Baja en el espectro solo cuando el trabajo necesite el control adicional.