Cómo evitar la amnesia del agente en Claude Code entre sesiones
DominicodeCómo evitar la amnesia del agente entre sesiones con Claude Code
Tiempo estimado de lectura: 5 min
Ideas clave
- Externalizar el estado del agente al repositorio (archivos versionados) para persistencia entre sesiones.
- Usar un archivo TASK_STATE.md como fuente de verdad y exigir su lectura al iniciar cada sesión.
- Dividir el trabajo por módulos y actualizar TASK_STATE.md antes de cada commit para evitar pérdida de contexto.
- Mantener ventanas de contexto pequeñas cargando sólo archivos relevantes del módulo más TASK_STATE.md.
- Medir retoma y reducción de rework para validar la efectividad del sistema.
Tabla de contenidos
- Cómo evitar la amnesia del agente entre sesiones con Claude Code
- Ideas clave
- Tabla de contenidos
- Introducción
- Resumen rápido (lectores con prisa)
- Sistema de tareas en disco
- Componentes del sistema de estado
- Ejemplo práctico: TASK_STATE.md (plantilla)
- Prompt de recuperación
- Cómo evita esto la contaminación de contexto
- Flujo operativo recomendado
- Decisiones de cuándo aplicar esto
- Medir si funciona
- Límites y advertencias
- Dominicode Labs
- FAQ
Introducción
Saber exactamente cómo evitar la amnesia del agente entre sesiones es lo que separa las automatizaciones frágiles de las que realmente escalan. Si cierras una terminal con Claude Code a mitad de tarea, la siguiente sesión no recordará decisiones, bugs ni el alcance ya cubierto. Esa falta de persistencia —junto a la contaminación de contexto dentro de sesiones largas— exige una solución estructural: externalizar el estado del agente en el repositorio.
Resumen rápido (lectores con prisa)
Externaliza el estado del agente en archivos versionados (ej. TASK_STATE.md). Lee TASK_STATE.md al iniciar cada sesión y actualízalo antes de cada commit. Divide el trabajo por módulos para mantener la ventana de contexto pequeña y evitar contaminación. Usa commits atómicos y especifica tareas en /tasks para handoffs confiables.
Cómo evitar la amnesia del agente entre sesiones: sistema de tareas en disco
La estrategia que funciona en entornos productivos es simple y técnica: tratar el árbol de archivos como la memoria persistente del agente. En vez de confiar en la memoria efímera de la sesión, haces que Claude escriba su estado, incidencias y decisiones en archivos versionados antes de cada commit. Al abrir una nueva sesión, el agente lee ese archivo y retoma exactamente donde quedó.
Referencias útiles: la documentación de Claude Code y la página de Claude explican las capacidades de ejecución y acceso a repositorio que hacen esto posible.
Componentes del sistema de estado
- TASK_STATE.md — memoria de trabajo (temporal, versionada)
- /tasks/*.md — specs atómicas por tarea (entradas para subagentes)
- CLAUDE.md — contrato del proyecto (stack, convenciones, patrones prohibidos)
Estructura mínima recomendada
/CLAUDE.md /TASK_STATE.md /tasks/ auth-migration.md billing-refactor.md
Ejemplo práctico: TASK_STATE.md (plantilla)
## Estado actual - Tarea: Migración AuthService → AuthV2 - Fase: 2/4 - Último commit: a3f92c1 ## Módulos completados - [x] UserModel - [x] AuthService - [ ] AuthController ## Bugs identificados - UserService.getById no valida usuarios inactivos (línea 47) - Token refresh: edge-case con cambio de email ## Notas de diseño - Mantener compatibilidad token-legacy 30 días - No migrar OAuth hasta fase 3
Prompt de recuperación (instrucción inicial)
Al iniciar una nueva sesión, la primera instrucción debe ser innegociable:
Lee TASK_STATE.md antes de ejecutar cualquier acción. Retoma desde la fase indicada y no repitas trabajo ya marcado como completado.
Ese prompt convierte el archivo en la “fuente de verdad” para el agente.
Cómo evita esto la contaminación de contexto
La contaminación ocurre cuando una sesión larga excede la ventana de tokens y el modelo comienza a “olvidar” detalles previos. La solución práctica es dividir la tarea en sesiones acotadas por módulo:
- Cada sesión se centra en un módulo concreto.
- Solo se cargan en contexto los archivos del módulo, las firmas de interfaces adyacentes y TASK_STATE.md.
- Los bugs se registran inmediatamente en TASK_STATE.md antes de pasar al siguiente módulo.
Así mantienes la ventana de contexto pequeña y relevante, y cualquier hallazgo se persiste en disco aunque el modelo lo “olvide” en memoria volátil.
Flujo operativo recomendado (paso a paso)
- Preparación: crea CLAUDE.md y una spec por tarea en /tasks.
- Inicio: abre sesión y ejecuta prompt de recuperación para leer TASK_STATE.md.
- Trabajo por módulo: el agente modifica archivos permitidos, añade tests y actualiza TASK_STATE.md antes del commit.
- Commit atómico: cada checkpoint importante tiene commit con mensaje estructurado.
- Handoff: si otro desarrollador o sesión retoma, lee TASK_STATE.md y continúa.
- Cierre: cuando la tarea se completa, merge y eliminación de TASK_STATE.md.
Regla clave: actualizar TASK_STATE.md antes de cada commit. Si la terminal cae, el estado queda preservado hasta el último punto sincronizado.
Decisiones de cuándo aplicar esto
Implementa este sistema cuando:
- La tarea requiere múltiples sesiones o días.
- Debes auditar y modificar más de 5–6 archivos interconectados.
- Necesitas handoffs confiables entre sesiones o personas.
No lo uses para cambios triviales que se completan en una sesión corta; el overhead no compensa.
Medir si funciona
Indicadores prácticos:
- Tiempo medio de retoma (desde abrir sesión hasta reanudar trabajo) < 5 minutos.
- % de tareas que requieren rework por amnesia o contexto < 5%.
- Reducción en reverts por decisiones olvidadas.
- Número de bugs registrados en TASK_STATE.md vs. bugs no documentados detectados tras merge (debe bajar).
Límites y advertencias
Esto no convierte a Claude en un “ingeniero permanente”. Externalizar estado aumenta resiliencia, pero no suple la necesidad de especificaciones claras. Si la spec es ambigua, el agente persistirá ambigüedades más rápido. Tampoco es sustituto de revisiones humanas en handoffs críticos (auth, infra, contratos externos).
Dominicode Labs
Para equipos que aplican automatización y agentes en flujos de trabajo, una continuación natural es explorar prácticas y experimentos en Dominicode Labs. Allí se documentan plantillas y patrones aplicables a sistemas de estado basados en repositorio.
FAQ
- ¿Qué es TASK_STATE.md y para qué sirve?
- ¿Cómo se usa TASK_STATE.md al inicio de una sesión?
- ¿Qué información debe contener TASK_STATE.md?
- ¿Por qué dividir el trabajo por módulos?
- ¿Cuándo no es apropiado este sistema?
- ¿Qué hacer si la spec es ambigua?
¿Qué es TASK_STATE.md y para qué sirve?
TASK_STATE.md es un archivo versionado que actúa como memoria de trabajo del agente: registra el estado de la tarea, módulos completados, bugs y notas de diseño. Sirve como fuente de verdad para retomar trabajo entre sesiones.
¿Cómo se usa TASK_STATE.md al inicio de una sesión?
La primera instrucción al iniciar una sesión debe ser leer TASK_STATE.md antes de ejecutar cualquier acción. El agente debe retomar desde la fase indicada y evitar repetir trabajo ya marcado como completado.
¿Qué información debe contener TASK_STATE.md?
Debe incluir estado actual (tarea, fase, último commit), módulos completados, bugs identificados y notas de diseño relevantes. El ejemplo en el artículo muestra una plantilla con secciones claras para cada aspecto.
¿Por qué dividir el trabajo por módulos?
Dividir por módulos mantiene la ventana de contexto pequeña y relevante, reduce la contaminación de contexto y facilita la persistencia de hallazgos en disco aunque el agente pierda memoria en la sesión.
¿Cuándo no es apropiado este sistema?
No es apropiado para cambios triviales que se completan en una sola sesión; el overhead de mantener TASK_STATE.md y specs por tarea puede no compensar en esos casos.
¿Qué hacer si la spec es ambigua?
Externalizar ambigüedades amplifica problemas: el agente persistirá decisiones ambiguas. La medida correcta es clarificar la spec durante el proceso y registrar las decisiones en TASK_STATE.md, además de mantener revisiones humanas en handoffs críticos.