Contenido detallado
🧭 Por qué un agente se pierde después de horas
Un agente que trabaja durante minutos suele hacerlo bien. Después de horas, aparece el problema: la conversación se llena, el sistema compacta (resume) lo anterior y se pierden detalles importantes. El agente empieza a repetir "voy a terminar y hacer el commit" sin terminar, o vuelve a abrir un elemento que ya estaba hecho. Esto es contexto degradado, y no es falta de inteligencia: es falta de memoria fuera de la conversación.
🌱 ¿Nuevo aquí?
La compactación ocurre cuando el agente resume la conversación anterior para que quepa más contenido. El resumen es útil, pero olvida detalles. Contexto degradado sucede cuando, tras varias compactaciones, el agente ya no recuerda bien lo que acordó.
🔥 Señales de que el contexto se ha degradado
Repetir la misma frase de cierre sin cerrar; reabrir un elemento ya completado; olvidar una regla acordada al principio; dar vueltas sin producir nada nuevo. Si ves esto, la sesión ya ha pasado su límite.
✓ La solución
Sacar la memoria de la conversación y ponerla en archivos: el objetivo con una prueba de que está listo, el estado actual, el plan y las notas. Después de cada compactación, el agente vuelve a leer los archivos y retoma el rumbo. Eso es lo que organiza el kit execucao-longa .
Por qué aprender
Porque la ejecución larga solo funciona si el rumbo está en archivos y no en la cabeza del agente. Entender por qué se pierde permite saber qué protecciones preparar en los próximos temas.
Conceptos clave
📁 La carpeta longrun/ (nuevo-longrun.sh y los 7 archivos)
El kit crea una carpeta propia para cada trabajo largo. Ejecutas tools/novo-longrun.sh <projeto> <slug> y crea longrun/<data>-<slug>/ con siete archivos. Cada uno tiene una función y, juntos, forman la memoria que sobrevive a la compactación.
🌱 ¿Nuevo aquí?
O slug es un nombre corto del trabajo, sin espacios (p. ej., limpar-docs). O canal es un archivo donde el agente solo añade notas: hechos, aprendizajes y trampas que la compactación suele borrar.
Los 7 archivos creados por novo-longrun.sh
longrun/2026-10-12-meu-projeto/ ├── goal.md # el resultado + la prueba de que está listo ├── plan.md # los pasos ├── state.md # dónde estoy ahora ├── progress.md # lo que ya se ha hecho ├── failures.md # lo que salió mal ├── decisions.md # lo que se decidió └── canal.md # notas sobre lo que se pierde en la compactación
🔎 Regla de oro
Después de cada compactación o reanudación, el agente vuelve a leer en este orden: goal, state, plan, canal. Durante el trabajo, registra pronto en canal y hace commit en cada punto de control.
Por qué aprender
Porque es la carpeta la que transforma «un agente que se pierde» en «un agente que retoma el trabajo por su cuenta». Quien tiene el rumbo por escrito nunca empieza desde cero.
Conceptos clave
🎯 goal.md nivel 3: comando → salida
O goal.md indica el resultado en una frase y, lo más importante, cómo demostrar que está listo. Cada criterio es un par comando → salida esperada. En el nivel 3, los criterios abarcan función (hace lo que debía), regresión (no rompió lo que ya funcionaba) y límite (no se pudo cumplir haciendo trampa).
🌱 ¿Nuevo aquí?
Un hacer trampa es cumplir el criterio sin hacer el trabajo de verdad, por ejemplo, borrar las pruebas que fallan para obtener «0 fallos». La regresión y el límite sirven para cerrar esa puerta.
Ejemplo de prueba de que está listo, nivel 3
# goal.md Resultado: todas las páginas del sitio pasan el validador. Prueba de que está listo (nivel 3): 1. función npm test → 0 fallos 2. regresión ls tests/ | wc -l → siguen siendo ≥ 48 pruebas 3. límite git diff --stat tests/ → vacío (tests/ intacto)
⚠️ Por qué «0 fallos» no basta
Un agente apresurado puede borrar la prueba que falla. Por eso, el ejemplo exige 0 fallos e al menos 48 pruebas e la carpeta tests/ intacta. Tres pruebas juntas, ningún atajo.
Por qué aprender
Porque el agente solo se detiene cuando la prueba pasa. Si la prueba es débil, «termina» antes de tiempo y mal; si es sólida, trabaja hasta acertar de verdad.
Conceptos clave
▶️ Ejecutar /goal en Codex y Claude Code
Con el goal.md listo, inicias el trabajo con el comando /goal, que existe tanto en el Codex como en el Claude Code. Indicas el objetivo y el agente empieza a trabajar hasta que la prueba pase. El mismo kit sirve para ambos ejecutores, como la identidad portátil del módulo 5.1.
🌱 ¿Nuevo aquí?
O /goal es un comando que fija un objetivo y mantiene al agente intentándolo hasta cumplirlo, en vez de detenerse con la primera respuesta.
🔎 Atención en Claude Code
Allí, la prueba debe aparecer en la salida de la conversación. El evaluador de /goal solo lee la conversación; no abrirá tus archivos. Así que haz que el agente ejecute el comando de la prueba y muestre el resultado.
✓ Mientras se ejecuta
Acompaña sin interrumpir. Vuelve a leer el canal de vez en cuando. Intervén solo ante las señales del siguiente tema.
Por qué aprender
Porque /goal es el botón de «ir y volver más tarde». Sin él, tendrías que empujar al agente en cada paso.
Conceptos clave
🛑 Cuándo detenerse y llamar a una persona
Un trabajo largo no significa trabajar sin ti. Hay tres señales de que es hora de detener al agente y actuar: tres ciclos sin avances medibles; el agente repite «voy a terminar y hacer commit» sin terminar o vuelve a abrir un elemento ya hecho (el contexto se degradó); y la 3.ª compactación.
🌱 ¿Nuevo aquí?
Un ciclo sin avances medibles es una ronda en la que no mejora ningún número de la prueba (los mismos tests fallan, el mismo recuento). Handoff es el resumen de traspaso que la siguiente sesión lee para continuar.
1. Sin avances
3 ciclos seguidos sin que mejore ninguna medición.
2. El contexto se degradó
Repite el cierre sin cerrar o vuelve a abrir un elemento ya hecho.
3. 3.ª compactación
Guarda el handoff, abre una sesión nueva y ejecuta /prime.
⚠️ Llama también a una persona cuando
haya crédito o una API implicados, una acción irreversible o externa, falte una credencial o se trate de una decisión de negocio. Esto se relaciona con las barreras del módulo de Reglas y Ganchos: el agente no decide por sí solo qué es costoso o irreversible.
Por qué aprender
Porque saber detenerse es parte del método. El error costoso es dejar que el agente dé vueltas en falso durante horas.
Conceptos clave
🤖 Modo headless: loop-longrun.sh con límites
En el modo headless nadie está mirando la pantalla. El script tools/loop-longrun.sh <pasta> repite ciclos, cada uno con un codex exec con un límite de tiempo. La prueba decide si se continúa. El bucle se detiene solo al concluir, al estancarse o al alcanzar un límite.
🌱 ¿Nuevo aquí?
Headless es ejecutar en segundo plano, sin ventana ni interacción. Límite es un máximo (de tiempo, de memoria) que detiene el proceso antes de que dañe la máquina.
El bucle del modo headless
tools/loop-longrun.sh longrun/2026-10-12-meu-projeto │ ├── cada ciclo = un codex exec con límite de tiempo ├── quien decide continuar es el prueba, no el agente └── se detiene solo: completado · estancamiento · límite
🔥 Límites siempre
Tiempo de espera en cada ciclo, memoria limitada con systemd-run --user --scope -p MemoryMax= e salida breve de las herramientas. Sin límite, un bucle olvidado puede bloquear el ordenador.
Por qué aprender
Porque es lo que permite dormir mientras el agente trabaja, con seguridad. Los límites son el cinturón de seguridad.
Conceptos clave
🛠️ PRÁCTICO: tu primer longrun + medir-sessao.py
Es hora de ponerse manos a la obra. Elige un trabajo pequeño y verificable (algo que un comando pueda demostrar que terminó) y ejecuta el ciclo completo. Al final, tools/medir-sessao.py muestra la duración, las compactaciones, los tokens y la caché de la sesión, para que veas cuánto costó el trabajo.
🌱 ¿Nuevo aquí?
O .jsonl es el archivo de registro de la sesión que guardan Claude Code y Codex. medir-sessao.py lee ese registro y devuelve los números.
Paso a paso del primer longrun
# 1. crear la carpeta del trabajo tools/novo-longrun.sh meu-projeto limpar-docs # 2. abrir y completar el goal.md (resultado + prueba de nivel 3) longrun/<data>-limpar-docs/goal.md # 3. iniciar /goal en Codex o Claude Code /goal longrun/<data>-limpar-docs/goal.md # 4. hacer seguimiento: volver a leer goal → state → plan → canal después de compactar # 5. al final, medir la sesión (duración, compactaciones, tokens, caché) tools/medir-sessao.py <sessao>.jsonl
✓ Comprueba al final
La prueba de goal.md pasó, el canal tiene notas útiles y tienes los números de la sesión. Si se detuvo antes, consulta en failures.md qué lo bloqueó y ajusta la prueba.
🔗 Guía y área
Guía completa: inematds.github.io/execucao-longa/guia. Área con materiales: eventos.inema.pro/execucao-longa.
Por qué aprender
Porque la ejecución prolongada se aprende haciéndola una vez. El primer longrun pequeño enseña más que leerlo todo dos veces.
Conceptos clave
🎉 Llegaste al final
Fin de la Ruta 5 — y del curso:
Completaste las 5 rutas. Ahora elige un dominio, construye tu OS y ejecuta /os-coach audit para puntuarlo frente a tu objetivo.