Claude Code CLI: Automatización de Terminal y Desarrollo Autónomo

4. Paso a paso: ejecuta un barrido de refactorización en modo headless

La sección 2 presentó las invocaciones no interactivas; aquí está el patrón completo y funcional para el trabajo para el que existe el modo headless: una refactorización de todo el repositorio que puedes supervisar por resultados en lugar de por pulsaciones de teclas. Tres pasadas: reconocimiento con herramientas de solo lectura, la edición con un conjunto de herramientas acotado y un presupuesto de turnos, y un resumen legible por máquina para tus registros.

# Pass 1 - recon: plan the change, touch nothing
claude -p "List every file that imports the legacy logger and describe the
change each one needs. Do not edit anything." \
  --allowedTools "Read,Grep,Glob"

# Pass 2 - execute: bounded tools, bounded turns
claude -p "Replace all imports of src/legacy/logger with src/lib/log.
Update the call sites, run the test suite, and stop immediately
if any test fails." \
  --allowedTools "Read,Edit,Bash" --max-turns 20

# Pass 3 - report: JSON summary for CI or your changelog
claude -p "Summarize the changes from this refactor as a changelog entry." \
  --output-format json > refactor-summary.json

Antes de que la pasada 2 se ejecute en serio alguna vez, dale al agente las órdenes permanentes del proyecto en un CLAUDE.md en la raíz del repositorio: Claude Code lo lee al inicio de cada sesión, interactiva o headless:

# Project rules
- Run `npm test` before committing; never commit on a red suite.
- Never edit generated files under src/gen/.
- Log through src/lib/log.ts. The legacy logger in src/legacy/ is
  deprecated and is being removed.
- Prefer small, focused diffs over sweeping rewrites.

Verifica con git, no con confianza

La salida en modo headless es una afirmación; el diff es la evidencia. Incorpora la revisión al flujo: después de cada barrido, inspecciona qué cambió realmente antes de que la siguiente pasada construya sobre ello, y cuando dos refactorizaciones sean independientes, ejecútalas en worktrees de git paralelos para que las ediciones de un árbol no contaminen el otro:

# What did the sweep actually touch?
git diff --stat
git status --porcelain

# A second, independent sweep in its own worktree, in parallel
git worktree add ../repo-docs-sweep HEAD
cd ../repo-docs-sweep
claude -p "Update the README examples to the new logger API from
src/lib/log. Do not change any source files." \
  --allowedTools "Read,Edit" --max-turns 10

El worktree le da al segundo agente una copia completa del mismo commit, con su propio directorio de trabajo y su propia rama, así que ambos barridos avanzan a la vez y se fusionan —o no— como historia normal de git. La autonomía escala cuando la verificación es mecánica.

5. Un ejemplo completo

Pon el barrido sobre rieles: un script de shell corto que refactoriza un módulo por vez y hace commit de cada módulo por separado. Los commits pequeños son la estrategia de supervisión: cada paso se puede revisar con git show y revertir con git revert, y eso es lo que hace aceptable una ejecución sin supervisión:

#!/usr/bin/env bash
# refactor-sweep.sh - rename a deprecated helper, one module at a time
set -euo pipefail

for module in auth billing reports; do
  echo "== Refactoring $module =="
  claude -p "In src/$module, rename the deprecated getUserData() helper
  to fetchUserProfile() and update every caller in that module.
  Run the module's tests when you are done." \
    --allowedTools "Read,Edit,Bash" --max-turns 15

  git add -A
  git commit -m "refactor($module): rename getUserData to fetchUserProfile"
done

echo "Sweep complete. Review with: git log --oneline -3"

Ejecútalo por la tarde y revisa por la mañana tres commits ordenados. Si la refactorización de billing salió mal, revierte ese commit y vuelve a ejecutar solo ese módulo con un prompt más estricto; los otros dos módulos quedan intactos. Combinado con las conexiones MCP de la sección 3 —acceso a esquemas mientras el agente trabaja—, este es el flujo que convierte el modo headless de demostración en infraestructura.

Más adelante: promueve el barrido a un trabajo nocturno de CI

Cuando el barrido se haya ganado la confianza en local, el mismo script corre sin cambios en CI: lo único que se añade es instalar la CLI y aportar la clave de API como secreto, que es exactamente el patrón de autenticación headless de la lista de solución de errores de abajo. Una ejecución nocturna sobre lo fusionado durante el día mantiene pequeñas las refactorizaciones pequeñas:

# .github/workflows/nightly-refactor.yml (excerpt)
- name: Install Claude Code
  run: npm install -g @anthropic-ai/claude-code

- name: Run the refactor sweep
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: ./refactor-sweep.sh

Mantén la salida del flujo como una pull request en lugar de un push directo: los commits por módulo llegan listos para revisar y una persona sigue siendo quien fusiona. La automatización propone; las personas disponen.

6. Solución de errores

• «claude: command not found» justo después de una instalación global exitosa. El directorio bin global de npm no está en tu PATH. Ejecuta npm config get prefix, añade su subdirectorio bin a tu perfil de shell y abre una terminal nueva; o evita el problema por completo con npx @anthropic-ai/claude-code, que ejecuta el mismo paquete sin la instalación global.
• La autenticación falla en CI pero funciona en tu máquina. Tu portátil tiene un inicio de sesión guardado; el runner de CI solo tiene el entorno. La exportación de ANTHROPIC_API_KEY de la sección 1 debe existir en el entorno del trabajo de CI (guárdala como secreto enmascarado), y allí ningún flujo de login interactivo te va a salvar: los entornos headless solo pueden usar la clave.
• La ejecución headless nunca termina. Algo en la sesión está esperando una entrada: un prompt que pide una aclaración o la aprobación de una herramienta sin nadie que la apruebe. Combina siempre -p con --max-turns, restringe --allowedTools a lo que el trabajo necesita y formula el prompt como una instrucción con condición de cierre («detente de inmediato si alguna prueba falla»), no como el inicio de una conversación.
• El agente editó archivos muy fuera del alcance previsto. El alcance es tu trabajo, no el del modelo. Nombra el directorio en el prompt (el ejemplo completo limita cada ejecución a un módulo), deja Edit fuera de --allowedTools en las pasadas de reconocimiento, prohíbe las rutas generadas en CLAUDE.md y revisa git diff antes de que cada commit aterrice: el ritmo de un commit por módulo existe para que un exceso sea una reversión, no un rescate.