Cómo evitar que tu agente de IA olvide lo que estás construyendo

Si has trabajado varios días seguidos con un asistente de IA para programar, seguro que te ha pasado. El primer día todo fluye: crea la estructura, escribe tests y documenta lo que hace. Al día siguiente abres una sesión nueva y el agente no recuerda nada del proyecto. Tienes que explicarle de nuevo la arquitectura y las decisiones tomadas. Para el tercer día, estás releyendo transcripciones enormes solo para reconstruir qué se acordó antes.

El problema no es solo el límite de contexto. Es más simple: estamos guardando el estado del proyecto en el lugar equivocado.

El problema de usar el chat como memoria

Las conversaciones con IA funcionan bien para colaborar en el momento. Pero no sirven como base de datos del proyecto.

Esto genera varios problemas concretos:

• Las decisiones se pierden entre mensajes antiguos y es difícil recuperarlas.
• No existe una única versión oficial de qué se está construyendo.
• Cada sesión nueva empieza desde cero, sin importar cuántas conversaciones previas existan.
• Diferentes agentes pueden tomar decisiones contradictorias sin que nadie lo note.

El verdadero límite de estos asistentes no está en escribir código, sino en mantener coherencia a lo largo del tiempo.

Una solución sencilla: guardar el estado en archivos

La alternativa es tratar el estado del proyecto como tratamos el código: guardarlo en archivos versionados dentro del repositorio.

No hace falta un wiki ni una herramienta externa. Basta con archivos Markdown estructurados que incluyan metadatos básicos.

Un ejemplo podría tener esta forma:

# Decisión de arquitectura

Lifecycle: active
Role: spec
Project: payment-service
Updated: 2024-01-15

Related:
- implements: charter-payment-api
- pairs-with: implementation-log-payment-core

## Resumen

Usamos la API directa de Stripe en lugar de una librería wrapper porque...

## Decisiones clave

- Claves de idempotencia en todas las operaciones
- Procesamiento asíncrono de webhooks con backoff exponencial
- Los datos PII nunca se almacenan localmente

## Preguntas abiertas

- ¿Deberíamos cachear el estado de rate limiting?

El formato es intencionalmente simple. Solo necesita un título, algunos metadatos y el contenido real.

Qué puedes hacer con esta estructura

Con una herramienta CLI básica puedes crear registros, archivados, moverlos, listar todo el proyecto con filtros o validar que las relaciones entre archivos sean correctas. También genera un índice automáticamente.

Lo importante no es el formato en sí, sino que el agente de IA pueda consultar el estado del proyecto en lugar de buscar entre mensajes antiguos.

En lugar de pedirle que lea el chat, le das comandos claros:

docs list --project=payment-service --role=spec
docs check

Y puede modificar el estado a través de comandos estructurados, no editando archivos directamente. Esto evita errores y mantiene la coherencia.

El patrón que realmente funciona

Cuando el agente empieza una sesión nueva, en lugar de perder todo el contexto, puede ejecutar un comando para ver qué está activo, qué ya se completó y qué decisiones se tomaron ayer. No necesita reconstruir la historia desde cero.

El chat anterior deja de ser relevante. El estado real vive en el repositorio, donde corresponde.

Cuándo te interesa este enfoque

Este patrón es útil si trabajas con herramientas de programación asistida por IA durante varios días, si gestionas flujos de agentes que necesitan retomar el trabajo sin transferir todo el contexto, o si colaboras en equipo y necesitas claridad sobre qué está decidido y qué sigue abierto.

No reemplaza a Git ni a los tests. Es una capa adicional que mantiene la coherencia del proyecto a lo largo del tiempo.

Lo más importante: es aburrido y por eso funciona

No estás creando una base de datos nueva ni una herramienta especializada. Estás usando Markdown, Git y la línea de comandos, que ya conoces, para resolver un problema que antes resolvías mal.

Los casos límite se manejan con validaciones automáticas. Si algo se rompe, el sistema lo detecta. Si hay contradicciones, el índice las revela.

Al final, la diferencia está entre un agente que "más o menos funciona" y uno que realmente entiende el proyecto y lo lleva a producción.