SDK headless y CI/CD

Ejecución no interactiva con -p

El flag -p (o --print) transforma Claude Code de una herramienta interactiva a un proceso programático que recibe un prompt, ejecuta el trabajo y produce salida en stdout. Este modo permite integrar Claude Code en scripts, pipelines de CI/CD y cualquier flujo de automatización que no requiera interacción humana.

claude -p "Encuentra y corrige el bug en auth.py"

En modo -p, Claude Code no muestra la interfaz interactiva. Procesa el prompt, ejecuta las herramientas necesarias y escribe el resultado directamente en la salida estándar. Esto lo convierte en un componente que se puede encadenar con otras herramientas de la terminal.

El modo -p es el equivalente a lo que se conoce como "headless mode" en otras herramientas. Claude Code opera con todas sus capacidades (lectura, edición, ejecución de comandos) pero sin requerir input del usuario durante la ejecución.

Flags esenciales para automatización

Al ejecutar Claude Code de forma programática, varios flags controlan el comportamiento y la seguridad:

| Flag | Descripción | |---|---| | --print / -p | Salida en stdout, sin interfaz interactiva | | --output-format | Formato de salida: text, json o stream-json | | --allowedTools | Herramientas auto-aprobadas sin prompt de permisos | | --max-tokens | Limitar tokens de salida | | --model | Seleccionar modelo (sonnet, opus, haiku) | | --quiet / -q | Suprimir salida no esencial | | --json-schema | Definir esquema para salida JSON estructurada | | --add-dir | Añadir directorios adicionales al contexto |

Un ejemplo combinando varios flags para un script de revisión automática de código:

claude -p "Revisa el código de src/auth/ y lista los problemas de seguridad" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json \
  --model sonnet

El flag --allowedTools es especialmente relevante en automatización: permite que Claude use ciertas herramientas sin solicitar aprobación, ya que no hay un usuario presente para confirmar cada acción.

Formatos de salida

Texto plano

El formato por defecto produce texto legible, adecuado para scripts simples o para mostrar resultados en logs:

claude -p "Resume los cambios del último commit" --output-format text

JSON estructurado

El formato json produce un objeto JSON con metadatos sobre la ejecución, útil para procesar la salida programáticamente:

claude -p "Extrae los nombres de funciones de auth.py" --output-format json

La salida incluye campos como result (el contenido generado), cost_usd (coste de la ejecución) y session_id.

Salida estructurada con esquema

El flag --json-schema permite definir la estructura exacta de la salida JSON, lo que garantiza un formato predecible para el procesamiento posterior:

claude -p "Analiza las dependencias del proyecto" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "dependencies": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "version": {"type": "string"},
            "outdated": {"type": "boolean"}
          }
        }
      }
    }
  }'

Claude ajusta su respuesta para que se adapte al esquema proporcionado, produciendo JSON que se puede parsear directamente.

Streaming JSON

El formato stream-json emite eventos JSON a medida que Claude trabaja, permitiendo procesamiento en tiempo real:

claude -p "Refactoriza el módulo de pagos" \
  --output-format stream-json \
  --verbose

Cada línea de salida es un objeto JSON independiente que representa un evento: inicio de herramienta, resultado de herramienta, texto generado, etc. Esto es útil para interfaces que necesitan mostrar progreso en tiempo real.

Integración en scripts

Script básico con gestión de errores

#!/bin/bash
output=$(claude -p "Genera la migración de base de datos para añadir campo email a users" \
  --allowedTools "Read,Edit,Write,Bash" \
  --output-format text 2>&1)

if [ $? -ne 0 ]; then
  echo "Error: $output"
  exit 1
fi

echo "Migración generada correctamente"
echo "$output"

Piping de contenido como contexto

Claude Code acepta contenido por stdin cuando se combina con -p, lo que permite inyectar contexto dinámico desde otros comandos:

# Pasar el diff de Git como contexto
git diff --staged | claude -p "Revisa estos cambios y sugiere mejoras"

# Analizar logs de errores
cat error.log | claude -p "Diagnostica la causa raíz de estos errores"

# Procesar salida de otro comando
npm audit --json | claude -p "Resume las vulnerabilidades criticas y sugiere correcciones"

Encadenar múltiples invocaciones

Se pueden encadenar varias ejecuciones de Claude Code en un pipeline donde la salida de una alimenta a la siguiente:

# Analizar y luego generar tests
claude -p "Analiza src/auth/login.ts y describe su comportamiento" \
  --output-format text | \
claude -p "Genera tests unitarios para el comportamiento descrito en stdin" \
  --allowedTools "Read,Write"

GitHub Actions

Claude Code se integra con GitHub Actions para automatizar tareas en el ciclo de desarrollo. La acción oficial permite que Claude Code responda a eventos de GitHub como pull requests, issues y menciones.

Un workflow típico que ejecuta Claude Code cuando se menciona @claude en un PR:

name: Claude Code Review
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude-review:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Casos de uso en CI/CD

Los escenarios más habituales de Claude Code en pipelines de integración continua:

• Revisión automática de PRs: analizar cambios, detectar problemas de calidad y seguridad, sugerir mejoras
• Triaje de issues: clasificar issues entrantes por prioridad y etiquetas
• Generación de migraciones: crear migraciones de base de datos a partir de cambios en modelos
• Documentación automática: generar o actualizar documentación cuando cambia el código
• Validación de convenciones: verificar que los cambios cumplen las convenciones del proyecto

# Ejemplo: validar convenciones antes de merge
claude -p "Verifica que los cambios en $(git diff --name-only main..HEAD) \
  siguen las convenciones definidas en CLAUDE.md. \
  Lista solo las violaciones encontradas." \
  --allowedTools "Read,Grep,Glob" \
  --output-format json

Claude Agent SDK

Además del CLI con -p, Claude Code ofrece el Agent SDK como librería para Python y TypeScript. A diferencia de los SDKs de la API de Anthropic (que solo dan acceso al modelo de lenguaje), el Agent SDK ejecuta el mismo bucle agéntico de Claude Code con todas sus herramientas integradas: lectura y edición de archivos, ejecución de comandos, Git, MCP y subagentes.

# Instalación
npm install @anthropic-ai/claude-agent-sdk   # TypeScript
pip install claude-agent-sdk                  # Python

SDK de TypeScript

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

for await (const message of query({
  prompt: "Encuentra y corrige el bug en auth.py",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  if ("result" in message) console.log(message.result);
}

SDK de Python

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Encuentra y corrige el bug en auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

El Agent SDK y el CLI con -p comparten las mismas capacidades. La diferencia está en el nivel de control: el SDK permite gestionar sesiones, definir hooks como callbacks, configurar subagentes y procesar mensajes de forma granular desde código, mientras que -p es más adecuado para scripts shell y pipelines CI/CD.

Buenas prácticas en automatización

Al integrar Claude Code en pipelines automatizados, conviene tener en cuenta:

• Especificar --allowedTools explícitamente: en entornos sin supervisión, listar solo las herramientas necesarias para la tarea. Evitar aprobar herramientas destructivas como Bash(rm *).

• Usar --output-format json para procesamiento: el formato JSON facilita el parsing y la integración con otras herramientas.

• Definir --json-schema para salidas predecibles: cuando la salida se procesa automáticamente, un esquema garantiza que la estructura sea consistente.

• Limitar tokens con --max-tokens: en pipelines con costes controlados, establecer un límite evita ejecuciones inesperadamente largas.

• Gestionar errores: verificar siempre el código de salida y capturar stderr para diagnóstico de fallos.

• Usar hooks PreToolUse en lugar de PermissionRequest: los hooks de tipo PermissionRequest no se disparan en modo -p, ya que no hay un usuario presente para responder. Para validaciones en modo programático, usar PreToolUse.