Headless en CI, sesiones, comandos y skills

Un job de CI le pide a Claude Code que revise cada pull request y se queda colgado esperando que alguien apruebe un permiso. Alguien propone saltear todos los controles para que no pregunte nunca más. En el mismo equipo, cada viernes una persona escribe de memoria el mismo prompt largo para armar las notas de versión. Las dos cosas se resuelven con piezas que Claude Code ya trae.

Sin nadie mirando: el modo headless

El modo headless (headless mode) corre Claude Code sin interfaz, con claude -p "..." (o --print). Para CI importa:

• --output-format json devuelve un objeto con el resultado, el ID de sesión, el uso y el costo; stream-json emite eventos JSON línea por línea mientras trabaja.
• --json-schema junto con --output-format json devuelve la salida estructurada en el campo structured_output. Si no llegó (por ejemplo, porque Claude se negó), el campo falta: el script tiene que chequearlo.
• --allowedTools aprueba solo lo necesario, con la sintaxis de reglas de permisos: "Read,Grep,Bash(git diff *)".
• --bare evita cargar hooks, skills, plugins, servidores MCP y CLAUDE.md de la máquina, para que el resultado sea igual en cualquier runner; lo que haga falta se pasa con flags.
• El código de salida es 0 si salió bien y distinto de 0 si falló, así el pipeline puede ramificar.

Modos de permisos

Los modos de permisos (permission modes) fijan qué corre sin preguntar:

Modo	Qué corre sin preguntar
default (manual)	Solo lecturas
acceptEdits	Lecturas, ediciones de archivos y comandos comunes de archivos en el directorio de trabajo
plan	Analiza y propone un plan sin editar
auto	Casi todo, con un clasificador que revisa cada acción y bloquea lo que se sale del pedido
dontAsk	Lo preaprobado; lo que preguntaría se deniega (útil para CI cerrado)
bypassPermissions	Todo; solo en contenedores o máquinas aisladas

Para menos avisos con red de seguridad está auto; “permisos totales para que no pregunte” casi nunca es la respuesta.

Sesiones

• claude --continue abre la sesión más reciente del directorio; claude --resume <nombre> retoma una sesión puntual. Las sesiones se nombran con -n al arrancar o con /rename.
• Para bifurcar una sesión (fork a session) y probar otro camino sin tocar la original: /branch adentro, o --fork-session junto con --resume o --continue.
• /clear empieza con contexto vacío (la sesión anterior queda guardada) y /compact reemplaza el historial por un resumen.

Ojo: si después de una investigación abriste otra sesión, --continue ya no te lleva a la investigación. Para reanudar una sesión (resume a session) puntual, va --resume con su nombre.

Comandos, skills, agentes y memoria

• Comandos de barra (slash commands) integrados: /init, /clear, /compact, /resume, /memory, entre otros.
• Skills: un procedimiento que se repite va en .claude/skills/<nombre>/SKILL.md del proyecto, se commitea y todos lo invocan con /nombre. Los comandos propios de .claude/commands/ siguen funcionando y se comportan igual. Al inicio solo se carga la descripción; el cuerpo, cuando se usa. Con disable-model-invocation: true, Claude no lo dispara solo, lo que importa si tiene efectos (crear un borrador de release, desplegar).
• Agentes: subagentes en .claude/agents/, con sus herramientas y su propio contexto, para tareas que conviene aislar.
• Memoria automática (auto memory): notas que Claude escribe solo a partir de tus correcciones, por repositorio. Se revisa y se apaga con /memory. Es contexto, igual que CLAUDE.md.

Las trampas típicas

• bypassPermissions o permisos totales en CI “para que no se trabe”.
• Parsear la salida en texto plano en lugar de --output-format json.
• Usar --continue para volver a una sesión que ya no es la más reciente.
• Reescribir a mano cada semana un prompt que podría ser una skill del proyecto.
• Dejar que Claude invoque solo una skill con efectos.

En el examen

Si algo tiene que correr sin nadie mirando, buscá claude -p con salida JSON y --allowedTools acotado. Si hay que volver a una sesión puntual y probar alternativas, buscá --resume con el nombre y /branch. Y si alguien repite un procedimiento a mano, buscá una skill versionada en el proyecto, con invocación del modelo desactivada si tiene efectos.