Formatos de salida y permisos en CI

Para que Claude trabaje en un pipeline hacen falta dos cosas: que su salida sea parseable por otro programa, y que pueda actuar sin que nadie apruebe prompts. Esta lección cubre las dos.

Salida estructurada con --output-format

Por defecto la salida es texto. Para scripts, pídela en JSON:

claude -p "Resume este proyecto" --output-format json | jq -r '.result'

El JSON trae el coste por invocación (total_cost_usd), útil para vigilar gasto en CI. Y si necesitas que la salida cumpla un esquema concreto, combina --output-format json con --json-schema:

claude -p "Extrae los nombres de función de auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Así otro paso del pipeline consume la salida sin parsear texto libre.

Permisos sin humano: el problema de CI

En tu terminal, cuando Claude quiere editar o ejecutar algo, te pregunta. En CI no hay nadie para decir "sí". Si no resuelves esto, el run se queda colgado o aborta. Dos enfoques, ambos del curso de permisos:

Pre-aprobar tools concretas

claude -p "Corre los tests y arregla los fallos" \
  --allowedTools "Bash,Read,Edit"

--allowedTools usa la sintaxis de reglas de permisos, con prefijos:

claude -p "Revisa los cambios staged y haz un commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Fijar una línea base con permission mode

En vez de listar tools, pon un modo (lo viste en el curso de permisos):

• dontAsk — deniega todo lo que no esté en tus reglas allow (más lo de solo lectura). Ideal para CI bloqueado: defines exactamente qué puede hacer y nada más.
• acceptEdits — deja escribir ficheros y comandos de filesystem comunes sin preguntar; el resto, según reglas.

claude -p "Aplica los fixes de lint" --permission-mode acceptEdits

Regla para CI: empieza con dontAsk + una allow mínima y ábrela solo a lo que el job necesite. Es el mínimo privilegio del curso de permisos, llevado al pipeline: un run automatizado no debería poder hacer más de lo que su tarea exige.

Acotar el trabajo: --max-turns

Para que un job no se desboque (ni en iteraciones ni en coste), limita las vueltas del agent loop:

claude -p "..." --max-turns 10

Qué llevas hasta aquí

• --output-format json (con --json-schema si hace falta) hace la salida parseable por otros pasos; incluye el coste.
• En CI no hay quien apruebe: pre-aprueba con --allowedTools o fija un permission mode (dontAsk para bloqueado).
• --max-turns acota iteraciones y coste.

Con el modo headless dominado, en la siguiente lección lo llevamos a GitHub Actions.

Fuente oficial: Run Claude Code programmatically · Permission modes