Saltar al contenido
Lección 10 de 14

Dominio del CLI e Integración CI/CD

8 min read

Dos Modos de Operación

Hasta este punto del curso, has usado Claude Code de forma interactiva -- escribiendo prompts, revisando respuestas, aprobando acciones. Ese REPL interactivo es poderoso para el trabajo diario de desarrollo. Pero Claude Code tiene un segundo modo que desbloquea una categoría completamente diferente de casos de uso: el modo print.

Cuando ejecutas claude sin argumentos, entras al REPL interactivo. Cuando ejecutas claude -p "tu prompt", entras en modo print. En modo print, Claude procesa tu prompt, produce salida a stdout y termina. No hay conversación continua, no hay aprobación interactiva y no hay persistencia. Se comporta como cualquier otra herramienta de línea de comandos Unix.

Esta distinción importa porque el modo print hace a Claude Code componible. Puedes enviarle datos por pipe, capturar su salida, encadenarlo con otras herramientas e integrarlo en scripts y flujos de trabajo CI/CD.

Fundamentos del Modo Print

La sintaxis básica es directa:

# Consulta unica, salida de texto a stdout
claude -p "Explica la diferencia entre map y flatMap en JavaScript"

# Proporcionar un system prompt para contexto
claude -p "Revisa este codigo por problemas de seguridad" --system-prompt "Eres un auditor de seguridad. Enfócate en vulnerabilidades de inyeccion y bypasses de autenticacion."

# Especificar un modelo
claude -p "Resume este archivo" --model claude-sonnet-4-20250514

El modo print acepta entrada desde stdin, lo que significa que puedes enviar contenido directamente a Claude por pipe:

# Enviar un archivo por pipe para analisis
cat src/auth/login.ts | claude -p "Encuentra vulnerabilidades de seguridad potenciales en este codigo"

# Enviar logs de errores por pipe para explicacion
tail -50 /var/log/app/error.log | claude -p "Explica estos errores y sugiere correcciones"

# Enviar un diff por pipe para revision
git diff HEAD~1 | claude -p "Revisa este diff. Senala bugs, problemas de estilo o tests faltantes"

Prueba esto: ejecuta git log --oneline -20 | claude -p "Resume la actividad de desarrollo reciente basandote en estos mensajes de commit" en uno de tus proyectos.

Formatos de Salida

Por defecto, el modo print produce texto plano. Para automatización, frecuentemente necesitas datos estructurados. Claude Code soporta varios formatos de salida:

# Salida JSON — estructurada, parseable
claude -p "Lista todos los comentarios TODO en este proyecto" --output-format json

# JSON en streaming — cada evento como un objeto JSON separado
claude -p "Analiza este codebase" --output-format stream-json

# Texto plano (por defecto)
claude -p "Explica esta funcion" --output-format text

El formato de salida JSON es particularmente útil para pipelines porque puedes procesarlo con jq:

# Extraer solo el texto de respuesta de la salida JSON
claude -p "Lista las 5 funciones mas complejas en src/" --output-format json | jq -r '.result'

# Obtener informacion de uso de tokens
claude -p "Resume este archivo" --output-format json | jq '.usage'

El formato stream-json emite un objeto JSON por línea a medida que Claude produce salida, lo cual es útil para procesamiento en tiempo real en tareas largas.

Flags Esenciales del CLI

Aquí están los flags que usarás más frecuentemente en scripts y automatización:

# Limitar el numero de turnos agentivos (critico para CI para prevenir sesiones descontroladas)
claude -p "Corrige los tests que estan fallando" --max-turns 10

# Establecer modo de permisos para uso no interactivo
claude -p "Refactoriza utils.ts" --permission-mode auto

# Restringir que herramientas puede usar Claude
claude -p "Revisa este PR" --allowedTools "read,grep,glob"

# Reanudar una sesion con nombre
claude -r "my-session"

# Combinar multiples flags
claude -p "Ejecuta tests y corrige fallos" \
  --max-turns 15 \
  --permission-mode auto \
  --output-format json \
  --model claude-sonnet-4-20250514

El flag --max-turns es esencial para cualquier uso automatizado. Sin él, Claude podría iterar indefinidamente intentando resolver un problema, quemando tokens y tiempo. Siempre establece un límite razonable.

El flag --allowedTools restringe lo que Claude puede hacer. Para una tarea de revisión de solo lectura, limita las herramientas a read, grep y glob. Para una tarea que necesita editar archivos, agrega write y edit. Esto sigue el principio de mínimo privilegio.

Procesamiento por Lotes

El modo print brilla cuando necesitas procesar múltiples archivos o elementos:

# Generar documentacion para cada archivo TypeScript en src/
for file in src/**/*.ts; do
  echo "Procesando $file..."
  claude -p "Genera documentacion JSDoc para todas las funciones exportadas en este archivo. Produce solo el codigo documentado." < "$file" > "${file}.documented"
done

# Analizar multiples archivos de log
for log in logs/*.log; do
  echo "=== $log ===" >> analysis.txt
  claude -p "Resume errores y advertencias en este archivo de log" < "$log" >> analysis.txt
done

Para trabajos por lotes más grandes, puedes paralelizar con xargs:

# Procesar 4 archivos en paralelo
find src/ -name "*.ts" | xargs -P 4 -I {} bash -c \
  'claude -p "Busca imports sin usar en este archivo" < "{}" > "/tmp/review-$(basename {}).txt"'

Integración con GitHub Actions

Una de las aplicaciones más poderosas del modo print es integrar Claude Code en pipelines CI/CD. Aquí tienes un flujo de GitHub Actions que usa Claude para revisar pull requests automáticamente:

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

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

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Review PR Changes
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD | claude -p \
            "Revisa este diff de pull request. Busca:
            1. Bugs o errores de logica
            2. Vulnerabilidades de seguridad
            3. Problemas de rendimiento
            4. Manejo de errores faltante
            Produce una revision estructurada con niveles de severidad." \
            --output-format json \
            --max-turns 5 > review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('./review.json');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: review.result
            });

Análisis Automatizado de Tests

Otro pipeline práctico analiza fallos en tests y sugiere correcciones:

- name: Run Tests
  id: tests
  run: npm test 2>&1 | tee test-output.txt
  continue-on-error: true

- name: Analyze Failures
  if: steps.tests.outcome == 'failure'
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    cat test-output.txt | claude -p \
      "Analiza estos fallos de tests. Para cada fallo:
      1. Identifica la causa raiz
      2. Sugiere una correccion especifica
      3. Califica la confianza (alta/media/baja)
      Formatea como markdown." \
      --max-turns 3 > failure-analysis.md

Generación de Documentación por Lotes

Genera documentación para un codebase completo en una sola ejecución de pipeline:

#!/bin/bash
# generate-docs.sh — Generacion de documentacion por lotes

OUTPUT_DIR="docs/api"
mkdir -p "$OUTPUT_DIR"

find src/ -name "*.ts" -not -path "*/node_modules/*" | while read file; do
  filename=$(basename "$file" .ts)
  echo "Documentando $file..."

  claude -p "Genera documentacion de API para este archivo TypeScript. \
    Incluye: firmas de funciones, descripciones de parametros, tipos de retorno \
    y ejemplos de uso. Produce como markdown." \
    --max-turns 3 \
    < "$file" > "$OUTPUT_DIR/${filename}.md"
done

echo "Documentacion generada en $OUTPUT_DIR"

Tareas Programadas

Claude Code soporta automatización recurrente programada con el comando /schedule:

# Programar una verificacion diaria de salud del codebase
/schedule daily "Ejecuta el linter, verifica dependencias desactualizadas con npm outdated y reporta vulnerabilidades de seguridad con npm audit. Resume los hallazgos."

# Programar revision semanal de frescura de documentacion
/schedule weekly "Compara los cambios de codigo fuente de los ultimos 7 dias con la documentacion. Lista cualquier documento que pueda estar desactualizado."

Las tareas programadas se ejecutan en modo print automáticamente y pueden entregar resultados a través de hooks o notificaciones.

Gestión de Costos y Límites de Velocidad

Cuando ejecutas Claude Code en pipelines automatizados, el control de costos es crítico:

# Siempre establece max-turns en CI para prevenir sesiones descontroladas
claude -p "Corrige este bug" --max-turns 10

# Verificar costos despues de una ejecucion
/cost

# Ver estadisticas de uso
/stats

Para pipelines CI, establece un presupuesto de tokens combinando --max-turns con prompts enfocados. Un prompt bien delimitado con --max-turns 5 costará una fracción de un prompt abierto sin límite de turnos.

Mejores Prácticas para Automatización

Siempre usa --max-turns en CI. Esto es innegociable. Una sesión sin límite en un pipeline CI puede ejecutarse durante horas y consumir miles de dólares en costos de API.

Usa --output-format json cuando proceses resultados. La salida JSON es determinista en estructura, haciéndola confiable para procesamiento posterior. La salida de texto plano puede variar en formato.

Restringe herramientas con --allowedTools. Si un paso de CI solo necesita leer y analizar código, no le des permisos de escritura. Esto previene modificaciones accidentales.

Mantén los prompts específicos. En automatización, los prompts vagos llevan a resultados impredecibles. En lugar de "revisa este código", especifica exactamente qué buscar y qué formato usar para la salida.

Almacena las API keys como secrets. Nunca hardcodees tu ANTHROPIC_API_KEY en archivos de workflow. Usa la gestión de secrets de tu plataforma CI.

Prueba localmente primero. Antes de agregar un paso de Claude Code a tu pipeline CI, prueba el comando exacto localmente con claude -p para verificar que produce la salida que esperas.

El modo print transforma Claude Code de un asistente interactivo a un componente programable que encaja en cualquier parte de tu infraestructura de desarrollo.