En el pipeline. Sin desarrollador en el bucle.

Módulo 2 · Instalación y entornos · Lección 5 de 5

Una vez que un equipo de cliente tiene Claude Code funcionando de forma interactiva, la siguiente pregunta es siempre la misma: ¿podemos automatizarlo? Al terminar esta lección conocerás los flags, los patrones y la integración con GitHub Actions, y estarás listo para diseñar un flujo de trabajo headless de Claude Code para un proyecto real.

El concepto: el flag -p es el interruptor para el uso en pipelines

El modo headless no es un producto distinto ni una herramienta diferente. Es un flag. Esa simplicidad merece énfasis ante un equipo de cliente que cree que una integración con CI implica un nuevo despliegue que gestionar.

Añadir -p al comando de Claude Code lo ejecuta de forma no interactiva: toma el prompt del argumento de la línea de comandos, lo ejecuta y termina. Sin esperar entrada, sin sesión interactiva. Esto es lo que hace que Claude Code sea componible con scripts de shell, pipelines de CI, hooks de pre-commit y cualquier flujo automatizado. El mismo binario, la misma autenticación y el mismo modelo, solo que invocados sin una persona en el bucle.

Cinco flags que dan forma a todo flujo headless

La mayoría de los comandos headless de Claude Code en un proyecto combinan algunos de estos cinco. Conoce lo que controla cada uno y cuándo recurrir a él.

1. -p: modo no interactivo. Ejecuta Claude Code sin sesión interactiva, lo que lo hace obligatorio para cualquier uso en pipelines. Toma el prompt como argumento de cadena: claude -p "Your prompt here". Úsalo siempre que Claude Code se ejecute en un script o en un flujo automatizado.

2. --allowedTools: restricción de herramientas. Restringe qué herramientas puede usar Claude Code en esta ejecución. Acepta una lista separada por comas: --allowedTools "Bash,Read,Edit". Úsalo cuando el pipeline debe estar limitado: por ejemplo, una revisión de código que lee archivos pero no ejecuta comandos de shell.

3. --append-system-prompt: instrucciones del pipeline. Inyecta una instrucción de nivel de sistema que se aplica a esta ejecución. Úsalo para fijar el contexto de una tarea automatizada: «esto es una revisión de seguridad», «responde siempre en JSON», «céntrate solo en los archivos modificados». Así especializas la misma herramienta para distintas etapas del pipeline.

4. --output-format json: salida estructurada. Devuelve la respuesta de Claude Code como JSON en lugar de prosa. Es imprescindible cuando la salida alimenta otro sistema: un panel, un ticket o una base de datos. Especifica el esquema esperado en el propio prompt: «Devuelve un array JSON donde cada elemento tenga ‘path’ (string) y ‘method’ (string).» Para flujos que requieren conformidad estricta de esquema, implementa lógica de reintento y valida el formato de salida en el pipeline. Prueba el cumplimiento del esquema en una ejecución controlada antes de desplegar en producción.

5. --bare: modo CI reproducible. Desactiva para esta ejecución los hooks locales, las skills, los plugins, los servidores MCP, la memoria automática y la carga de CLAUDE.md. Úsalo cuando necesitas un comportamiento consistente entre entornos: el mismo comando produce el mismo resultado independientemente de lo que esté configurado en la máquina de cada desarrollador. Combínalo con -p para flujos de CI totalmente aislados y reproducibles: claude -p --bare 'Your prompt here'.

En la práctica: tres patrones para mostrar a un equipo de cliente, cada uno de un caso de uso real

Estos patrones provienen directamente del material fuente. Son funcionales, no ilustrativos: muéstralos en ejecución, no solo descritos.

1. Revisión automática de código

Envía el diff de un PR a Claude Code con un prompt de sistema de revisión de seguridad. La salida es JSON, apta para publicarla de vuelta en el PR o alimentar un panel.

2. Bucle de tests y corrección

Ejecuta la suite de tests e indica a Claude Code que corrija los fallos. Limita el acceso a herramientas a las operaciones necesarias, sin permisos adicionales. Se detiene tras la ejecución de tests, independientemente del resultado.

3. Extracción estructurada

Extrae información estructurada de una base de código (endpoints de API, dependencias, valores de configuración) y la devuelve como JSON con una estructura específica que las herramientas posteriores pueden parsear directamente. El esquema se define en el prompt.

# Patrón 1: revisión automática de código en un PR
gh pr diff "$1" | claude -p \
--append-system-prompt "Review for security vulnerabilities" \
--output-format json
# Patrón 2: ejecutar tests y corregir fallos
claude -p "Run test suite, fix any failures" \
--allowedTools "Bash,Read,Edit"
# Patrón 3: salida estructurada: listar endpoints de la API
claude -p 'List all API endpoints in this codebase. Output a JSON array where each item has "path" (string) and "method" (string).' \
--output-format json

Integración con CI/CD: GitHub Actions, la configuración son dos pasos y un disparador

El equipo de desarrollo del cliente casi seguro ya usa GitHub Actions. Integrar Claude Code es una adición a su flujo existente, no un reemplazo.

Para configurar Claude Code en GitHub Actions, ejecuta /install-github-app desde una sesión activa de Claude Code. Esto instala la app de GitHub en la organización del cliente. Una vez instalada, los desarrolladores pueden activar Claude Code en cualquier issue o PR mencionando @claude en un comentario. Claude Code lee el contexto y responde, sin necesidad de configuración de pipeline manual en el caso básico.

Flujos personalizados

Los flujos personalizados automatizan Claude Code sin esperar a que un desarrollador mencione @claude. Un YAML de flujo personalizado tiene cuatro bloques de construcción:

flowchart LR
  T["1. Disparador: cada pull request, programado o evento personalizado"] --> E["2. Entorno: ANTHROPIC_API_KEY desde GitHub Secrets"]
  E --> C["3. Comando de Claude: -p, --output-format json, --allowedTools"]
  C --> S["4. Salida: comentario en el PR, archivo o siguiente acción"]

1. Disparador: en cada pull request, según programación o en un evento personalizado.
2. Entorno: ANTHROPIC_API_KEY inyectada desde GitHub Secrets.
3. Comando de Claude: flags de tarea y de formato de salida: -p (no interactivo), --output-format json, --allowedTools.
4. Gestión de la salida: publicar el resultado como comentario en el PR, guardarlo en un archivo o enviarlo a otra acción.

A diferencia del disparador básico @claude, en el que Claude Code lee el contexto del PR y responde en prosa, los flujos personalizados definen la tarea exacta, la estructura de la respuesta y el destino de la respuesta.

Autenticación en CI: es una cuestión de gestión de secretos, no de Claude Code

El mecanismo es el mismo que para cualquier credencial de API en un pipeline. La configuración varía según la plataforma de CI.

Claude Code en modo headless se autentica con ANTHROPIC_API_KEY, sin navegador ni login interactivo. En GitHub Actions, esto significa añadir la clave como secreto del repositorio o de la organización y referenciarla en el YAML del flujo con ${{ secrets.ANTHROPIC_API_KEY }}. El mismo patrón se aplica en GitLab CI (variables de CI/CD), Jenkins (almacén de credenciales) y otras plataformas. El equipo de DevOps del cliente reconocerá este patrón de inmediato: es exactamente la forma en que gestionan cualquier otra clave de API en sus pipelines.

Comprueba tu comprensión

Escenario: diseñar el comando correcto para el pipeline.

Un responsable de ingeniería del cliente está diseñando un flujo automatizado de revisión de PRs.

El responsable dice: «Queremos que Claude Code revise cada PR automáticamente y genere un informe JSON estructurado que nuestro panel interno de seguridad pueda consumir. ¿Cuál es la combinación correcta de flags?»

• A. -p solamente: el flag -p gestiona tanto la ejecución no interactiva como el formato de salida.
• B. --json-schema solamente: el flag de esquema basta para que Claude Code devuelva JSON estructurado.
• C. -p + --output-format json + esquema en el prompt: ejecución no interactiva y formato JSON como flags, con el esquema definido en el propio texto del prompt.
• D. -p + --allowedTools: el modo headless junto con la restricción de herramientas resuelve el requisito de salida estructurada.

Ver respuesta

Correcta: C. A, B y D son incorrectas.

C es correcta. Dos flags, cada uno con una función distinta, más diseño del prompt: -p la hace no interactiva (se ejecuta sin esperar entrada); —output-format json indica a Claude Code que devuelva JSON en lugar de prosa; y la estructura esperada (campos, tipos, anidamiento) se especifica en el propio prompt. La guía del esquema en el prompt da forma a la salida, pero para pipelines de producción, incorpora validación y lógica de reintento; no des por hecho que la forma coincidirá siempre exactamente. Usar --output-format json sin especificar la estructura en el prompt deja la forma del JSON indefinida: el panel no sabrá qué parsear.

Práctica: instalar y ejecutar en tres entornos

Ya tienes las piezas. Ahora móntalas.

Entorno 1: CLI (local)

De la Lección 2.1 conoces la secuencia de instalación y puedes verificarla con claude --version. Ejecuta esto primero.

Entorno 2: integración con IDE

De la Lección 2.2, instala la extensión de IDE (VS Code o JetBrains). Abre un archivo pequeño, hazle una pregunta a Claude Code sobre él y verifica que la respuesta aparece en línea. No estás ejecutando un comando headless aquí; compruebas que la integración con el IDE funciona como herramienta interactiva.

Entorno 3: dev container

Requiere una configuración que no se cubre en el Curso 2. Deberás: (1) crear un devcontainer.json o una configuración de Docker que incluya Claude Code, (2) iniciar el contenedor y (3) verificar que claude --version funciona dentro de él. Consulta la documentación de tu plataforma de contenedores y la referencia de la CLI de Claude Code para los pasos de instalación. Los conceptos de aislamiento de la Lección 2.4 se aplican aquí: el contenedor es el sandbox.

Script headless: ejecución de extremo a extremo

De la Lección 2.5 sabes que el flag -p ejecuta Claude Code de forma no interactiva. Crea un script de prueba sencillo:

echo "What does this function do?" | claude -p --stdin --output-format text

Ejecútalo desde tu entorno de CLI (Entorno 1). Lo que verificas: (1) el prompt llega a Claude Code, (2) Claude Code se ejecuta sin esperar entrada (flag -p) y (3) aparece la salida. Después ejecuta el mismo comando dentro de tu dev container (Entorno 3). El éxito es que ambos produzcan salida.

Criterios de éxito

• claude --version devuelve una cadena de versión en los tres entornos.
• La extensión de IDE carga sin errores y responde a una consulta sencilla.
• El comando headless -p produce salida tanto en el contexto de la CLI como en el del contenedor.

Lo que aprenderás haciendo esto: por qué los dev containers son una ventaja para el cliente (reproducibles, aislados, con la versión fijada), qué significa «headless» en la práctica (ejecución no interactiva que alimenta pipelines de CI) y dónde están las lagunas de tu entorno (normalmente la autenticación en contenedores o el contexto de shell).

Artefacto del curso: Installation Configuration Pack (sección de especificación de contenedor)

Esta lección aporta la sección de especificación de contenedor: la definición del dev container y la configuración del pipeline headless que el equipo de DevOps del cliente necesita para reproducir el entorno en CI.

1. Registra la referencia de la feature de devcontainer y cualquier flag de fijación de versión. Si el proyecto requiere un ciclo de actualización controlado, documenta la sobrescritura que desactiva las actualizaciones automáticas.
2. Documenta el patrón de invocación headless: el flag no interactivo, el formato de salida y la fuente de entrada por tubería que usará el equipo (git log, salida de tests, artefactos de build).
3. Anota la ruta de integración con CI: el disparador de GitHub Actions, la ubicación del archivo de flujo y el patrón de comando @claude que los desarrolladores usarán para invocarlo desde un pull request.

Entrega estas dos secciones (la de configuración de la lección 4 y esta de especificación de contenedor) a los responsables de TI y DevOps del cliente: juntas cubren cada requisito que hay que resolver antes de que pueda empezar un despliegue de Claude Code.

Pruébalo

Has cubierto todos los entornos en los que se ejecuta Claude Code: CLI local, extensiones de IDE, dev containers y pipelines headless. Antes de avanzar, instala Claude Code en los tres entornos y ejecuta un script headless de extremo a extremo. Captura la salida. Ese único ejercicio confirma que tu configuración está limpia, que tus flags son correctos y que puedes guiar a un desarrollador del cliente por el mismo proceso sin dudar.

Ideas clave

Al terminar esta lección tienes los flags, los patrones y la integración con GitHub Actions para diseñar un flujo headless en un proyecto real. El Installation Configuration Pack queda completo con la especificación de contenedor que entregas al equipo de DevOps.

• El flag -p convierte Claude Code en no interactivo; no es un producto distinto, es el mismo binario, la misma autenticación y el mismo modelo.
• Los cinco flags clave son -p, --allowedTools, --append-system-prompt, --output-format json y --bare.
• La salida JSON requiere especificar la estructura en el prompt y, en producción, validación con reintentos.
• En GitHub Actions, la autenticación es un secreto (ANTHROPIC_API_KEY) gestionado igual que cualquier otra clave de API del pipeline.
• Los flujos personalizados definen disparador, entorno, comando y gestión de la salida; el disparador básico @claude responde en prosa.

Siguiente: Marco de decisión de despliegue