Phase 14 - Lesson 35

Scripts de Inicialización para Agentes

Cada sesión que inicia en frío paga una tasa. El agente lee los mismos archivos, reintenta las mismas comprobaciones y redescubre las mismas rutas. Un script de inicialización paga la tasa una vez y escribe las respuestas en el estado.

Tipo: Build Lenguajes: Python (stdlib) Prerrequisitos: Fase 14 · 32 (Minimal Workbench), Fase 14 · 34 (Repo Memory) Tiempo: ~45 minutos

Objetivos de Aprendizaje

• Identificar el trabajo que un agente nunca debería tener que rehacer por sesión.
• Construir un script de inicialización determinista que examine el entorno de ejecución, las dependencias y la salud del repositorio.
• Persistir el resultado del examen para que el agente lo lea en lugar de volver a ejecutar las comprobaciones.
• Fallar de forma ruidosa (fail loud), rápida y con un único lugar donde buscar cuando la inicialización falle.

El Problema

Abre una sesión. El agente adivina la versión de Python. Adivina el comando de prueba. Lista la raíz del repositorio cinco veces para encontrar el punto de entrada. Intenta importar un paquete que no está instalado. Le pregunta al usuario dónde reside el archivo de configuración. Para el momento en que realiza una edición real, se han gastado diez mil tokens en trabajo de configuración que debería haber sido un solo script.

La solución es un único script de inicialización que se ejecute antes de que el agente haga cualquier otra cosa y escriba un archivo init_report.json que el agente lea al iniciar.

El Concepto

flowchart TD
  Start[Inicio de Sesión] --> Init[init_agent.py]
  Init --> Probes[examinar runtime / deps / rutas / env / pruebas]
  Probes --> Report[init_report.json]
  Report --> Decision{¿saludable?}
  Decision -- sí --> Agent[Loop del Agente]
  Decision -- no --> Halt[fallar ruidosamente, detener, reportar a humano]

Qué examina el script de inicialización

Fallar de forma ruidosa, fallar rápido, fallar en un solo lugar

Una falla en la comprobación significa detenerse y reportar al ser humano. Nada de "el agente lo resolverá". El punto principal del init es negarse a iniciar cuando la mesa de trabajo esté rota.

Idempotente

Ejecútelo dos veces seguidas. La segunda ejecución debería ser una operación sin efecto (no-op), salvo por una marca de tiempo actualizada. La idempotencia es lo que permite integrar el script en CI, hooks o en un comando de barra diagonal previo a la tarea.

Inicialización frente a reglas de inicio

Las reglas (Fase 14 · 33) describen lo que debe ser verdadero para actuar. Init es el script que establece que esas reglas se pueden verificar. Reglas sin init se convierten en un simple "ten cuidado". Init sin reglas se convierte en una falla pulida.

Constrúyalo

code/main.py implementa init_agent.py:

• Cinco comprobaciones: versión de Python, dependencias listadas a través de importlib.util.find_spec, resolubilidad del comando de prueba, variables de entorno requeridas y frescura del archivo de estado.
• Cada comprobación devuelve (name, status, detail).
• El script escribe init_report.json con el conjunto completo de comprobaciones y sale con un código distinto de cero si falla alguna comprobación de severidad de bloqueo.

Ejecútelo:

python3 code/main.py

El script imprime la tabla de comprobaciones, escribe init_report.json y finaliza con código cero en la ruta feliz (happy path) o con un código distinto de cero con una lista de las comprobaciones que fallaron.

Patrones de producción en el mundo real

Tres patrones separan un script de inicialización útil de una simple ceremonia.

Anclaje al commit de última integridad conocida (LKG). Compara el commit actual frente a un archivo LKG escrito en la última fusión (merge) exitosa. Si el diff supera un límite (50 archivos por defecto), se niega a iniciar y requiere que un humano ratifique el nuevo punto de partida. Esto es lo que utiliza AI Code Review de Cloudflare para delimitar el alcance de los agentes revisores: cada sesión de revisión se ancla al mismo commit de última integridad conocida y nunca acumula desvíos entre sesiones.

Archivos de bloqueo (lock files) con TTL. Escribe un prereqs.lock después de la primera comprobación exitosa. Las ejecuciones posteriores confían en el bloqueo durante N horas (24h por defecto) y omiten las comprobaciones costosas. El script de inicialización lee el bloqueo primero; si está fresco y el hash del manifiesto de dependencias coincide, realiza un atajo (short-circuit). Este es el mismo patrón que utiliza Docker para los cachés de capas: comprobación idempotente + hash de contenido = omitir.

Sin red, sin LLM, sin sorpresas en el camino crítico. Las comprobaciones de inicialización son tuberías deterministas. Una comprobación que llama a un LLM para clasificar una falla o que contacta a un servicio externo para verificar una licencia no es una comprobación; es un flujo de trabajo. Si una comprobación tarda más de tres segundos en una ejecución de prueba (dry run), considérelo un síntoma de problemas (smell) en la mesa de trabajo y sáquela de la inicialización o guarde su resultado en caché.

Cómo usarlo

En producción:

• Hooks de Claude Code. El hook pre-task llama al script de inicialización y se niega a iniciar el agente si este falla.
• GitHub Actions. Un trabajo setup-agent ejecuta el script de inicialización; el trabajo del agente depende de él.
• Docker entrypoint. El contenedor del agente ejecuta el script de inicialización antes de iniciar el entorno de ejecución del agente; los registros se muestran en caso de falla.

El script de inicialización es portátil porque no realiza llamadas a un framework específico. Puede envolverse en Bash, Make o un archivo de tareas.

Envíelo

El archivo outputs/skill-init-script.md analiza el proyecto, clasifica su trabajo de configuración en comprobaciones y genera un init_agent.py específico para el proyecto junto con un flujo de trabajo de CI que lo ejecuta antes de cualquier paso del agente.

Ejercicios

1. Agregue una comprobación que compare el commit actual con el commit de última integridad conocida y se niegue a iniciar si cambiaron más de 50 archivos.
2. Configure el script para escribir un archivo prereqs.lock y negarse a iniciar si el bloqueo tiene más de siete días de antigüedad.
3. Agregue una bandera --fix que instale automáticamente las dependencias de desarrollo faltantes pero que nunca modifique las dependencias de runtime sin aprobación.
4. Mueva las comprobaciones de funciones fijas (hardcoded) a un registro YAML. Defienda la relación de compromiso.
5. Agregue un presupuesto de tiempo por comprobación. Una comprobación que se ejecute durante más de tres segundos es un síntoma de problemas (smell) en la mesa de trabajo.

Términos Clave

Lecturas Adicionales

• Anthropic, Effective harnesses for long-running agents
• GitHub Actions, composite actions for setup
• microservices.io, GenAI dev platform: guardrails — verificaciones de pre-commit + CI como inicialización
• Augment Code, How to Build Your AGENTS.md (2026) — expectativas de inicialización
• Codex Blog, Codex CLI Context Compaction — inicio de sesión como inicialización consciente de compactación
• Fase 14 · 33 — el conjunto de reglas que habilita este script
• Fase 14 · 34 — el archivo de estado que este script alimenta
• Fase 14 · 38 — la puerta de verificación alimentada por el script de inicialización
• Fase 14 · 40 — la transferencia (handoff) que consume la última integridad conocida del reporte de inicialización