Codex CLI: tareas de horas sin perder contexto (2026)

TL;DR: Codex CLI puede trabajar de forma autónoma durante horas, pero el problema no es que el modelo sea torpe, sino que se queda sin memoria de trabajo y empieza a divagar. La solución no es un megaprompt, sino memoria de proyecto duradera: un spec congelado, un plan dividido en hitos verificables y un registro de estado en archivos que el agente relee. En esta guía verás el patrón exacto que OpenAI usó para una ejecución de 25 horas y cómo aplicarlo a tu repo (sirve igual para Claude Code o Gemini CLI).

El problema: por qué tu agente se pierde a la hora de empezar

Llevo meses dejando agentes de coding corriendo tareas que antes partía en diez sesiones. Y el patrón de fallo siempre es el mismo: las primeras dos horas van de maravilla, y luego el agente empieza a reescribir cosas que ya funcionaban, a olvidar una restricción que diste al principio o a "terminar" algo que no cumple lo que pediste.

No es un problema de inteligencia del modelo. Es de gestión de contexto. Cada turno de Codex incluye todo el historial de la conversación en el prompt, así que la ventana crece con cada llamada a herramienta. En tareas de horas, eso significa cientos de iteraciones modelo-herramienta hasta que la información importante (el objetivo, las restricciones, la definición de "hecho") queda enterrada o se descarta al comprimir el contexto.

Si quieres entender la mecánica de fondo, ya analicé por qué los agentes long-horizon se pierden en tareas largas. Aquí vamos a lo práctico: cómo estructurar el trabajo para que el límite de contexto deje de ser tu cuello de botella.

¿Qué es la memoria de proyecto duradera?

La memoria de proyecto duradera es la técnica de escribir el objetivo, el plan, las restricciones y el estado en archivos de texto que el agente puede releer en cualquier momento, en lugar de confiar en que lo recuerde de la conversación.

Es la diferencia entre darle instrucciones de palabra a alguien que va a trabajar 8 horas, o dejarle una pizarra con el objetivo, una lista de tareas con casillas y un cuaderno donde apunta decisiones. La pizarra no se borra cuando se llena la cabeza. En la ejecución de 25 horas que documentó OpenAI con GPT-5.3-Codex, la conclusión fue literal: "la técnica más importante fue la memoria de proyecto duradera". Eso evita la deriva y mantiene una definición estable de "hecho".

El stack de archivos: 4 piezas que evitan la deriva

El patrón que recomienda OpenAI se apoya en cuatro archivos con responsabilidades separadas. No es teoría, es lo que mantuvo coherente una ejecución de un día entero.

Archivo	Para qué sirve	Por qué importa
spec.md	Congela el objetivo, restricciones y entregables	Evita que el agente "construya algo impresionante pero equivocado"
plan.md	Hitos pequeños con criterios de aceptación y comandos de validación	Convierte trabajo abierto en checkpoints que se completan y verifican
implement.md	Runbook: cómo debe operar el agente paso a paso	Estandariza el comportamiento entre milestones
status.md	Log vivo de estado y decisiones	Mantiene la ejecución inspeccionable sin tener que parar

La clave está en separar el "qué" del "cómo" y del "dónde voy". Es el mismo principio de separación de responsabilidades en arquitectura de software, aplicado a la memoria de un agente.

Implementación paso a paso

1. Escribe el spec antes de tocar nada

El error número uno es lanzar un prompt largo y rezar. El spec congela el target para que el agente no improvise el alcance. Cuatro secciones bastan.

Define objetivos, no-objetivos, restricciones duras y la condición de "hecho":

# spec.md

## Objetivos
- API REST que exponga búsqueda semántica sobre el catálogo de productos.

## No-objetivos
- No tocar el sistema de autenticación existente.
- No migrar la base de datos.

## Restricciones duras
- Python 3.12 + FastAPI. Latencia p95 < 300 ms.
- Sin dependencias nuevas fuera de las ya declaradas en pyproject.toml.

## Hecho cuando
- `pytest` pasa en verde y `ruff check` no reporta errores.
- El endpoint /search devuelve 10 resultados ordenados por relevancia.

2. Divide en hitos verificables

Aquí está el corazón del patrón. Cada hito debe ser lo bastante pequeño para completarse en un solo ciclo del agente y, sobre todo, tener un comando de validación que diga objetivamente si está hecho.

Cada milestone lleva su criterio de aceptación y su comando de validación:

# plan.md

## Milestone 1: esquema de embeddings
- [ ] Crear modelo Pydantic para el documento indexado.
- Validación: `pytest tests/test_schema.py`
- Regla stop-and-fix: si falla, repara antes de pasar al M2.

## Milestone 2: endpoint /search
- [ ] Implementar búsqueda top-k contra el vector store.
- Validación: `pytest tests/test_search.py && ruff check`
- Decisión: usamos cosine similarity, NO dot product (ya decidido, no re-evaluar).

Fíjate en dos detalles que marcan la diferencia en producción. La regla "stop-and-fix": si la validación falla, el agente repara antes de avanzar, en vez de acumular deuda. Y las notas de decisión: anotar lo que ya está decidido evita que el agente oscile y re-discuta lo mismo tres horas después.

3. Dale el runbook en AGENTS.md

El comportamiento operativo va en el archivo que tu CLI lee al arrancar cada sesión: AGENTS.md para Codex, CLAUDE.md para Claude Code. Aquí le dices que escriba las cosas, no que las recuerde.

Una instrucción que funciona: ordena al agente actualizar el estado tras cada hito:

# AGENTS.md

## Flujo de trabajo obligatorio
1. Lee spec.md y plan.md antes de cada milestone.
2. Tras completar un milestone, ejecuta su comando de validación.
3. Actualiza status.md con: qué hiciste, qué validaste, qué decidiste.
4. Si una validación falla, NO avances: repara y vuelve a validar.

Mantén este archivo corto y operativo. Según estudios sobre AGENTS.md, las secciones de "arquitectura" genéricas no cambian el comportamiento del agente y solo gastan tokens; lo que sirve son comandos, restricciones y patrones no obvios. Si quieres exprimir esto, mira los patrones de system prompts que mejoran tu CLAUDE.md.

4. Lanza con goal mode y verificación continua

Desde mayo de 2026, el modo /goal de Codex dejó de ser experimento. Le das un objetivo medible y sigue trabajando hasta cumplirlo, incluso a lo largo de horas, con la opción de pausar y retomar.

# Arranca Codex en modo objetivo apuntando al spec
codex
# Dentro de la sesión:
/goal Implementa todos los milestones de plan.md. Trata spec.md como
la especificación completa. Valida cada hito antes de avanzar.

La verificación continua (tests, lint, typecheck, build tras cada milestone) es lo que mantiene la ejecución honesta. Sin ella, el agente cree que avanza aunque esté rompiendo cosas.

Caso real: del megaprompt al flujo con evidencia

En escenarios reales, este patrón cambia cómo delegas. Antes partías una refactorización grande en sesiones de 30 minutos porque el agente se perdía. Con memoria de proyecto, lanzas la tarea entera y revisas en los checkpoints.

Jason Liu lo lleva un paso más allá con lo que llama un "vault": un repositorio Git separado del código, donde el agente guarda contexto rodante (personas, decisiones, hilos abiertos, estado de proyectos) que de otro modo se perdería entre sesiones. La idea es la misma que ya vimos en cómo dar memoria a tu agente sin inflar el contexto: no guardas todo el historial, guardas hechos y decisiones.

¿Cuándo usar esto en producción? Cuando la tarea dura más de lo que cabe en una ventana de contexto cómoda, cuando vas a delegar y desconectar, o cuando varios agentes (o tú a ratos) tocan el mismo trabajo. Para un fix de 15 minutos, montar cuatro archivos es sobreingeniería.

En Producción

Aquí es donde el tutorial se separa de la realidad. Tres cosas que aprendí dejando esto correr de verdad.

El coste de los threads largos no es gratis. Las conversaciones largas se benefician del prompt caching, pero si revisitas un thread horas después, probablemente ya no esté en caché y pagas más que en un thread corto y fresco. La compaction (disponible en la Responses API) ayuda a estirar la ventana efectiva comprimiendo el historial, pero comprimir también puede tirar contexto que importaba. Por eso la memoria vive en archivos: sobrevive a la compaction. Para un proyecto personal, hablamos de un consumo realista de entre 10 y 50 € al mes en API si lo usas a diario, no de cifras de FAANG.

El plan debe caber en un ciclo. Si un milestone es demasiado grande, el agente lo empieza, se queda sin contexto a mitad y lo deja a medias sin validar. Hitos pequeños con un comando de validación claro son tu mejor seguro contra la deriva. Esto conecta con la importancia de elegir bien el modelo según tu repo: en tareas largas, un modelo con buena coherencia a largo horizonte rinde más que uno "más listo" pero que pierde foco.

La evidencia es el control de calidad. Exigir que cada hito deje artefactos (tests verdes, un diff, una nota en status.md) es lo que te permite revisar al final sin reconstruir todo desde cero. Sin evidencia, delegar horas de trabajo es un acto de fe.

Errores comunes y depuración

Error: el agente "termina" pero no cumple el spec. Causa: la condición de "hecho" era ambigua. Solución: define "hecho" con comandos ejecutables, no con prosa ("pytest pasa", no "que funcione bien").
Error: reescribe código que ya funcionaba. Causa: perdió el contexto de qué milestones estaban cerrados. Solución: obliga a releer status.md al inicio de cada ciclo y marca los hitos completados.
Error: oscila entre dos soluciones cada pocas horas. Causa: no hay registro de decisiones. Solución: añade notas de decisión en plan.md marcadas como "ya decidido, no re-evaluar".
Error: el coste se dispara en una tarea larga. Causa: threads revisitados fuera de caché. Solución: para workstreams largos, mantén la continuidad; para consultas sueltas, abre un thread corto nuevo.

Preguntas frecuentes

¿Esto solo funciona con Codex CLI?

No. El principio (preservar contexto en archivos y dividir en hitos verificables) es transferible a Claude Code o Gemini CLI. Lo que cambia es la herramienta y el nombre del archivo de instrucciones (AGENTS.md o CLAUDE.md), no la técnica. Codex añade el modo /goal y compaction nativa, pero el patrón de memoria de proyecto es agnóstico.

¿Cuántos archivos necesito de verdad?

Para empezar, dos: un spec con el objetivo y un plan con hitos y validaciones. El runbook (AGENTS.md) y el log de estado los añades cuando la tarea pasa de una hora o varias sesiones. No montes los cuatro para un cambio pequeño.

¿La compaction no resuelve esto sola?

La compaction estira la ventana de contexto comprimiendo el historial, pero comprimir es lossy: puede descartar la restricción o decisión que necesitabas. Los archivos de memoria son la red de seguridad porque el agente los relee íntegros cuando hace falta, sin depender de qué sobrevivió a la compresión.

Lo que te llevas

Hemos visto que hacer que Codex aguante tareas de horas no va de prompts más largos ni de modelos más potentes, sino de darle una memoria de proyecto que no se borra. Congelar el objetivo en un spec, partir el trabajo en hitos con comandos de validación y dejar que el agente actualice su propio estado convierte la delegación de horas en algo revisable y barato en errores. La verificación continua es lo que mantiene todo honesto: si no se puede validar, no está hecho.

El siguiente paso natural es orquestar varios de estos agentes en paralelo sin que se pisen, que es donde entran los git worktrees y la evidencia obligatoria. Lo cubriré pronto. ¿Has dejado un agente corriendo una tarea larga y has visto cómo se pierde? Cuéntame qué patrón te funciona en los comentarios o en Twitter @sergiomarquezp_.