invincible04/awesome-loop-engineering

Ingeniería de Bucles

Ayuda al usuario a reemplazar a sí mismo como la cosa que indica a un agente de codificación. El entregable es un sistema pequeño que descubre trabajo, lo entrega a un hacedor, verifica el resultado con un verificador separado, escribe lo que se ha hecho, decide qué sigue, y se repite hasta que se cumple un objetivo, luego se detiene por una razón honesta.

Tu trabajo en esta habilidad no es escribir el bucle de una sola vez. Es entrevistar, diseñar el contrato, luego andamiar para que terminen con un bucle que realmente puedan ejecutar y en el que confíen.

Qué es y qué no es un bucle

Un bucle no es un cron job. Un cron job se repite a ciegas. Un bucle descubre trabajo, lo verifica con un verificador separado, persiste el estado, decide qué sigue y se detiene por una razón. Si lo que estás construyendo no puede detenerse por sí solo, es un error, no un bucle.

Construye las condiciones de parada primero. Son lo que permite al usuario alejarse.

Paso 0: decide si un bucle es siquiera la herramienta adecuada

Antes de diseñar nada, aplica esta prueba. Un bucle solo vale la pena cuando ambas son ciertas:

1. Hay un criterio de éxito claro y verificable por máquina (una prueba pasa, un build está en verde, un esquema valida, una rúbrica devuelve PASS).
2. Alcanzarlo implica prueba y error tediosos que el usuario haría manualmente, turno tras turno.

Si el usuario no puede indicar cómo sabría una máquina que el trabajo está hecho, detente y dilo. Un bucle sin una condición de finalización verificable no converge; se agita y quema tokens. Ayúdales a encontrar un proxy verificable primero, o recomienda que sigan indicando manualmente. No construyas un bucle para evitar entender el trabajo.

Buenos candidatos para un bucle: arreglar CI fallido, triar una bandeja de incidencias, actualizaciones de dependencias contra un conjunto de pruebas sólido, ajuste de rendimiento con un benchmark, caza de pruebas inestables, builds de documentación que deben mantenerse en verde. Malos candidatos: diseño abierto, cualquier cosa donde "bueno" sea cuestión de gusto sin proxy, tareas únicas.

Paso 1: entrevista al usuario (llena el contrato del bucle)

Haz estas preguntas. Lidera con la pregunta de verificación: es la que decide si el bucle es viable. No preguntes las once a la vez; pregunta en pequeños lotes, e infiere lo que puedas de forma segura del repositorio.

1. Objetivo. ¿Cuál es el trabajo recurrente que sigues haciendo manualmente? ¿Qué debería hacer el bucle que sea cierto?
2. Condición de finalización (pregunta primero, pregunta fuerte). ¿Cómo sabría una máquina que está hecho, sin que un humano mire? Nombra el comando o verificación exactos.
3. Disparador. ¿Qué inicia una ejecución: un horario (cada N minutos/nocturno) o un evento (push, nueva incidencia, webhook, fallo de CI)?
4. Descubrimiento/entrada. ¿Cómo elige una ejecución en qué trabajar? (leer estado de CI, consultar el rastreador de incidencias, leer un fix_plan.md, escanear alertas)
5. Espacio de trabajo. ¿Dónde actúa y qué está estrictamente prohibido? (un worktree de git o sandbox; nunca hacer force-push, tocar secretos, cambiar dependencias, golpear producción)
6. Contexto. ¿Qué debe leer cada ejecución para no re-derivar el proyecto desde cero? (un SKILL.md / AGENTS.md, la especificación, el archivo de memoria)
7. Delegación. ¿Qué agente hace el trabajo (el hacedor) y cuál separado lo verifica (el verificador)? No deben ser la misma llamada.
8. Verificación. ¿Qué puertas deben pasar para que "hecho" sea verdadero? (pruebas unitarias, lint, tipos, una rúbrica LLM-como-juez que devuelva PASS/FAIL con evidencia)
9. Memoria/estado. ¿Dónde se almacena el progreso para que una ejecución pueda reanudarse después de un reinicio? (un archivo markdown, un rastreador de incidencias, un state.json en disco)
10. Presupuesto. Los límites duros: iteraciones máximas, tiempo de ejecución máximo, tokens máximos y un tope de dólar si una credencial puede gastar dinero.
11. Traspaso. ¿Cuándo escala a un humano en lugar de continuar? (ambiguo, alto riesgo, o el mismo fallo dos veces sin nueva evidencia)

Registra las respuestas en templates/loop-contract.template.md. Si el usuario no puede responder a #2 con una verificación concreta, regresa al Paso 0.

Paso 2: escribe el contrato del bucle

Llena la plantilla en un loop-contract.md real en el repositorio del usuario. Este es el artefacto de diseño a partir del cual se construye y revisa el bucle. Mantenlo breve y concreto. Cada campo debe nombrar un comando, una ruta o un número, no una sensación.

Paso 3: elige la forma más pequeña que se ajuste a la herramienta

Mapea el contrato al agente del usuario. Elige el mecanismo más simple que lo satisfaga; no recurras a orquestación multi-agente cuando un /goal sea suficiente. Consulta reference/tool-mapping.md para detalles específicos.

• Claude Code: /goal para la condición de parada verificada, sub-agentes en .claude/agents/ para la separación hacedor/verificador, hooks o una tarea programada para el disparador, claude -p ... --output-format json para ejecuciones sin cabeza.
• Codex: la pestaña Automations para el disparador, codex exec --json para ejecuciones sin cabeza, codex exec resume --last para continuar, sub-agentes para el verificador.
• Greenfield / desde cero: un bucle bash estilo Ralph, while :; do cat PROMPT.md | agent; done, con una tarea por turno y un fix_plan.md. Mejor cuando aún no hay base de código que romper; combínalo con una puerta y un presupuesto para que pueda detenerse. Ver reference/ralph.md.

Paso 4: andamia los archivos

Genera artefactos concretos y ejecutables (adapta los nombres al stack del usuario):

• La indicación del hacedor con las reglas no negociables incorporadas (ver leyes abajo).
• El verificador: ya sea una puerta de shell (el comando exacto de prueba/lint) o una indicación de verificador que devuelva PASS/FAIL más evidencia y pueda ESCALATE. Comienza desde reference/verifier-rubric.md.
• El archivo de memoria (fix_plan.md o state.json) que una ejecución lee primero y escribe al final.
• El ejecutor: el bucle while, línea de cron, Acción de GitHub o automatización que lo dispara, incluyendo la puerta ("si el build ya está verde, no hagas nada") y el tope de presupuesto.

Paso 5: endurece antes de dejarlo correr

Guía al usuario a través de reference/hardening-checklist.md antes de la primera ejecución no supervisada. Siempre haz una prueba en seco con un presupuesto ajustado y una credencial en sandbox antes de escalar.

Las cuatro condiciones de parada honestas

Cada bucle debe ser capaz de detenerse por exactamente una de estas, y decir cuál:

• meta alcanzada: el verificador separado confirma la condición de finalización.
• presupuesto agotado: se superó un tope de iteración, token, tiempo o dólar.
• estancado: el mismo fallo dos veces sin nueva evidencia (deja de forcejear).
• necesita un humano: alto riesgo o ambiguo, por lo que escala. Esto es un estado de éxito, no un fallo.

Las leyes no negociables

Incorpora las reglas 1–5 en las instrucciones de cada hacedor. Las reglas 6–7 no se pueden incorporar en un hacedor — son responsabilidad del ingeniero, así que asegúrate de que el usuario las mantenga.

1. El hacedor nunca califica su propio trabajo. Un verificador separado decide "hecho". El modelo que escribió el código es demasiado generoso calificando su propia tarea.
2. Nunca debilites o elimines una prueba, ni limites una verificación, para que pase. Arregla la causa. Si la prueba está mal, escala; no la edites en silencio.
3. Un bucle que no puede detenerse es un error. Cablea las cuatro condiciones de parada antes de la primera ejecución.
4. La memoria vive en disco, no en el contexto. Léela primero cada turno, escríbela al final. El agente olvida entre ejecuciones; el repositorio no.
5. Arregla solo la causa; no amplíes el alcance. El cambio más pequeño que pueda ser correcto.
6. La verificación sigue siendo responsabilidad del ingeniero. "Hecho" es una afirmación, no una prueba. El verificador es el activo que el usuario posee; el hacedor es un producto básico que mejora gratuitamente con cada versión del modelo.
7. La flota escala a la tasa de revisión del usuario, no al número de carriles de la herramienta. El humano es el cuello de botella en serie. Normalmente, el número correcto de agentes paralelos es un solo dígito bajo.

Lo que el bucle nunca hace por ti

Dilo claramente al usuario para que mantenga el trabajo correcto:

• Verificación. Un bucle ejecutándose sin supervisión también es un bucle cometiendo errores sin supervisión. El verificador separado hace que "hecho" signifique algo; no lo hace seguro.
• Comprensión. Cuanto más rápido entrega el bucle, más rápido crece la deuda de comprensión. Programa tiempo para leer lo que construyó.
• Intención. Por qué importa este trabajo y qué significa "bueno" tiene que venir de un humano. El bucle no sabe la diferencia entre usarlo para avanzar más rápido en el trabajo que entiendes y usarlo para evitar entenderlo. Tú sí.

Construye el bucle. Pero constrúyelo como alguien que pretende seguir siendo el ingeniero, no solo la persona que presiona el botón de inicio.

Lecturas adicionales (opcional)

Si el usuario quiere la teoría detrás de estos pasos en profundidad — la anatomía del bucle y el contrato de 11 partes, /goal vs /loop, la memoria, la economía de tokens y el impuesto de orquestación, y los riesgos — remítelos al manual Awesome Loop Engineering: https://github.com/invincible04/awesome-loop-engineering (legible en línea en https://invincible04.github.io/awesome-loop-engineering/).