sxivansx/loop-engineering

Ingeniería en Bucle

Configura un bucle: un sistema autónomo que incita al agente para que tú no tengas que hacerlo. Defines el objetivo y la condición de parada una sola vez; el bucle encuentra trabajo, lo hace, lo verifica, registra lo ocurrido y se repite hasta que se cumple la meta. Este skill implementa ese bucle dentro de tu proyecto existente: lee cómo ya pruebas, construyes y rastreas el trabajo, y luego adapta el bucle a tus convenciones en lugar de imponer unas genéricas.

Un bucle se construye a partir de seis primitivas. Configura solo las que el objetivo necesite.

Primitiva	Función en el bucle	Mecanismo de Claude Code
Disparador	inicia cada ciclo, según un horario o un evento	/goal (trabajar a través de turnos hasta que se cumpla una condición), /loop, tareas programadas, hooks, GitHub Actions
Estado	la memoria del bucle entre ciclos, en disco	un archivo markdown (LOOP.md) o un rastreador de incidencias vía MCP
Descubrimiento	encuentra en qué trabajar este ciclo	un paso de triaje que lee CI, incidencias, diffs, una cola
Creador	realiza una unidad de trabajo	un subagente en .claude/agents/
Verificador	verifica al creador, de forma independiente	un subagente diferente en .claude/agents/
Condición de parada	la regla que termina el bucle	una comprobación verificable que ejecuta el verificador

Para cualquier bucle que se ejecute sin supervisión, añade un monitor: un agente de supervisión que vigila todo el bucle y lo detiene ante deriva (desviación del objetivo), giro en vacío (sin progreso neto) o un límite superado (demasiados ciclos, demasiado tiempo). El creador y el verificador mantienen cada elemento correcto; el monitor mantiene todo el bucle apuntando al objetivo, para que no se desvíe silenciosamente y se ejecute durante horas.

Dos complementos opcionales más: árboles de trabajo (git worktree) aíslan creadores paralelos para que no editen los mismos archivos, y conectores MCP permiten que el bucle toque herramientas reales (abrir un PR, actualizar un ticket, publicar estado). Agrégalos cuando el objetivo necesite paralelismo o efectos secundarios externos.

Procedimiento de configuración

Esto se ejecuta dentro de un proyecto existente. Sigue estos pasos cuando se invoque. Confirma con el usuario antes de cualquier acción con efectos secundarios: trabajos programados, pushs, escrituras en tickets, despliegues.

1. Lee el proyecto primero. Antes de crear cualquier andamio, conoce el repositorio: cómo ejecuta pruebas, compilación y lint (revisa package.json, Makefile, configuración de CI, CLAUDE.md); qué convenciones y skills existentes o .claude/agents/ ya tiene; y de dónde viene el trabajo (CI, un rastreador de incidencias, un backlog, una cola). El bucle debe encajar en este proyecto. Reutiliza sus comandos y convenciones reales, no inventes otros nuevos.

2. Fija el objetivo y la condición de parada. Pregúntale al usuario el único objetivo del bucle y la condición verificable que significa que está listo (pruebas con salida 0, la cola vacía, cero comprobaciones fallidas). Un bucle sin condición de parada es lo único que nunca debes enviar. Si el usuario no puede nombrar una, establece un límite de seguridad (para después de N ciclos) y dilo en voz alta. En Claude Code, /goal <condición> lo hace ejecutable: Claude sigue trabajando entre turnos hasta que se cumple la condición, y /goal clear lo termina antes de tiempo.

3. Escribe el archivo de estado. Copia ${CLAUDE_SKILL_DIR}/templates/LOOP.md a la raíz del repositorio y completa el objetivo, la condición de parada, la cadencia y la puerta humana. Tiene tres secciones vivas que el bucle mantiene: ## Abierto (encontrado, no hecho), ## Hecho (con la evidencia que lo verificó), ## Bloqueado (necesita a un humano), más una sección ## Reglas que es el conjunto de instrucciones permanentes que todo agente en el bucle sigue. El bucle lee esto primero cada ciclo y lo escribe al final.

4. Crea el subagente creador. Copia ${CLAUDE_SKILL_DIR}/templates/loop-maker.md a .claude/agents/loop-maker.md y apúntalo a las convenciones y al comando de prueba que encontraste en el paso 1. Realiza exactamente un elemento de ## Abierto, sigue los skills y convenciones existentes del proyecto, y nunca marca su propio trabajo como hecho. Si ya existe un archivo con ese nombre, actualízalo en lugar de sobrescribirlo a ciegas.

5. Crea el subagente verificador. Copia ${CLAUDE_SKILL_DIR}/templates/loop-checker.md a .claude/agents/loop-checker.md. Es un agente diferente del creador, ejecuta la verificación real del proyecto (el comando real de prueba, compilación o lint del paso 1, no una descripción), y es el único agente autorizado para mover un elemento a ## Hecho.

6. Crea el subagente monitor (recomendado para cualquier bucle desatendido). Copia ${CLAUDE_SKILL_DIR}/templates/loop-monitor.md a .claude/agents/loop-monitor.md, y ejecútalo cada pocos ciclos o con un temporizador más lento que el del bucle. Vigila todo el bucle en lugar de cualquier elemento individual: comprueba si el bucle sigue convergiendo hacia el objetivo, y detiene el bucle y escala a un humano en caso de deriva (trabajo que no sirve al objetivo), giro en vacío (sin progreso neto, elementos rebotando entre Abierto y Bloqueado) o un límite superado. Esto es lo que impide que un bucle se desvíe silenciosamente y se ejecute durante horas.

7. Establece la cadencia de revisión de código y auditoría de seguridad (pregunta al usuario). Pregunta con qué frecuencia debe ejecutarse cada una, y registra ambas en LOOP.md. Ofrece opciones claras e incluye siempre nunca:

   • Revisión de código (/code-review): cada cambio, antes de cada PR o fusión, cada N ciclos, semanalmente, o nunca.
   • Auditoría de seguridad (/security-review): cada cambio, antes de cada PR o fusión, semanalmente, mensualmente, o nunca.

   En la cadencia elegida, el bucle ejecuta esa pasada integrada y archiva lo que encuentra en ## Abierto como nuevos elementos de trabajo, para que el creador los corrija y el verificador verifique la corrección. Si el usuario elige nunca, salta esa pasada por completo y registra nunca en LOOP.md para que el bucle no la reintroduzca.

8. Define el descubrimiento. Escribe el paso de triaje que llena ## Abierto cada ciclo desde donde realmente vive el trabajo de este proyecto (estado de CI, incidencias abiertas, commits recientes, una cola de trabajo), y cómo convierte los hallazgos en elementos discretos y verificables individualmente. Hazlo determinista siempre que sea posible.

9. Elige el aislamiento (opcional). Si se ejecuta más de un creador por ciclo, dale a cada uno su propio git worktree y rama para que nunca escriban el mismo archivo. Un worktree por elemento.

10. Conecta los conectores (opcional). Si el bucle debe abrir PRs, actualizar tickets o publicar estado, conecta el servidor MCP correspondiente. De lo contrario, la salida del bucle permanece local y un humano la retransmite.

11. Establece el disparador. Elige el mecanismo más ligero que se ajuste a la cadencia:

    • ejecutar hasta que se cumpla el objetivo, en esta sesión → /goal <condición de parada> (Claude trabaja entre turnos hasta que la condición es verdadera; /goal clear lo termina antes de tiempo)
    • repetir según una cadencia, bajo demanda → /loop
    • periódico y desatendido → una tarea programada (o cron / un GitHub Action para bucles del lado de CI)
    • reaccionar a un evento (push, PR, cambio de archivo) → un hook o un GitHub Action

Confirma con el usuario antes de crear cualquier trabajo programado.

12. Prueba en seco, verifica y luego activa. Ejecuta un ciclo manualmente. Lee todo lo que produjo. Confirma que el verificador realmente bloquea la salida incorrecta y que se escribió el estado. Solo entonces activa el disparador.

Salvaguardas (no negociables)

• El verificador nunca es el creador. El agente que escribió el código no puede declararlo correcto.
• La condición de parada es verificable, no sensaciones. "Parece listo" no es una condición de parada. Un comando que sale con 0 lo es.
• El estado se escribe cada ciclo. Si el bucle olvida lo que intentó, se repite. El modelo olvida; el archivo no.
• Una puerta humana permanece en todo lo irreversible. Enviar, desplegar, eliminar, gastar dinero. El bucle redacta, una persona confirma. Un bucle desatendido comete errores desatendidos.
• Bloqueado es mejor que adivinar. Cuando el bucle no puede verificar o continuar, escribe en ## Bloqueado y detiene ese elemento. No envía una suposición.
• Un bucle largo es vigilado y acotado. Cualquier bucle desatendido se ejecuta con un monitor y un límite. Si se desvía del objetivo o supera el límite, el monitor lo detiene y escala. Un bucle nunca debe ejecutarse para siempre en la dirección equivocada.

Aspecto del bucle una vez configurado

tu-proyecto/
├── LOOP.md                   # objetivo, condición de parada, límites, reglas, Abierto/Hecho/Bloqueado
├── .claude/
│   └── agents/
│       ├── loop-maker.md     # realiza una unidad de trabajo
│       ├── loop-checker.md   # la verifica, de forma independiente
│       └── loop-monitor.md   # vigila todo el bucle por deriva + descontrol
└── (disparador: /goal, /loop, una tarea programada o un GitHub Action)

Anti-patrones: no envíes estos

• Un bucle sin condición de parada (se ejecuta para siempre, quema tokens).
• Un agente que escribe y califica su propio trabajo.
• Un bucle sin archivo de estado (re-deriva todo, repite trabajo, olvida lo que falló).
• Un bucle desatendido sin monitor ni límites (se desvía del objetivo y se ejecuta durante horas antes de que alguien lo note).
• Envío desatendido sin puerta humana para acciones irreversibles.
• Un bucle que lleva muchos trabajos no relacionados. Un bucle, un objetivo, una condición de parada. Divide el resto en sus propios bucles.

Archivos de este skill

• templates/LOOP.md: el archivo de estado para copiar en el repositorio de destino.
• templates/loop-maker.md: la definición del subagente creador.
• templates/loop-checker.md: la definición del subagente verificador.
• templates/loop-monitor.md: la definición del subagente monitor (guardia contra deriva y descontrol).
• examples/keep-ci-green.md: un bucle completo desarrollado, desde el objetivo hasta el disparador.