Saltar al contenido
Lección 10 de 14

Dominio del CLI e Integracion CI/CD

8 min read

Dos Modos de Operacion

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 categoria 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 conversacion continua, no hay aprobacion interactiva y no hay persistencia. Se comporta como cualquier otra herramienta de linea de comandos Unix.

Esta distincion 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 basica 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. Enfocate 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 automatizacion, 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 util 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 linea a medida que Claude produce salida, lo cual es util para procesamiento en tiempo real en tareas largas.

Flags Esenciales del CLI

Aqui estan los flags que usaras mas frecuentemente en scripts y automatizacion:

# 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 el, Claude podria iterar indefinidamente intentando resolver un problema, quemando tokens y tiempo. Siempre establece un limite razonable.

El flag --allowedTools restringe lo que Claude puede hacer. Para una tarea de revision 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 minimo privilegio.

Procesamiento por Lotes

El modo print brilla cuando necesitas procesar multiples 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 mas 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"'

Integracion con GitHub Actions

Una de las aplicaciones mas poderosas del modo print es integrar Claude Code en pipelines CI/CD. Aqui tienes un flujo de GitHub Actions que usa Claude para revisar pull requests automaticamente:

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
            });

Analisis Automatizado de Tests

Otro pipeline practico 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

Generacion de Documentacion por Lotes

Genera documentacion para un codebase completo en una sola ejecucion 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 automatizacion 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 automaticamente y pueden entregar resultados a traves de hooks o notificaciones.

Gestion de Costos y Limites de Velocidad

Cuando ejecutas Claude Code en pipelines automatizados, el control de costos es critico:

# 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 costara una fraccion de un prompt abierto sin limite de turnos.

Mejores Practicas para Automatizacion

Siempre usa --max-turns en CI. Esto es innegociable. Una sesion sin limite en un pipeline CI puede ejecutarse durante horas y consumir miles de dolares en costos de API.

Usa --output-format json cuando proceses resultados. La salida JSON es determinista en estructura, haciendola 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 codigo, no le des permisos de escritura. Esto previene modificaciones accidentales.

Manten los prompts especificos. En automatizacion, los prompts vagos llevan a resultados impredecibles. En lugar de "revisa este codigo", especifica exactamente que buscar y que formato usar para la salida.

Almacena las API keys como secrets. Nunca hardcodees tu ANTHROPIC_API_KEY en archivos de workflow. Usa la gestion 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.