Lo más costoso de trabajar con un agente es volver a explicar el contexto. Cada mañana vuelves a explicar las decisiones de ayer, pegas el último mensaje de commit, restableces qué error bloquea el despliegue. Multiplica por cada sesión y el costo oculto es de horas por semana, no minutos.
STATE.md elimina ese impuesto. Un archivo, actualizado al final de cada sesión, cargado al inicio de la siguiente. La disciplina: antes de cerrar una sesión, dedica tres minutos a actualizar el archivo. Mañana, esos tres minutos te ahorrarán veinte.
STATE.md contiene tres cosas, nada más.
Decisiones: lo que se acordó y por qué. Sin el porqué, tu yo futuro reabrirá la decisión. "Triggers de Postgres en lugar de cron para el resumen diario: los triggers son transaccionales, cron compite con la ruta de escritura."
En curso: lo que está a medio hacer, lo suficientemente específico como para delegar. "Migración 014 escrita en /migrations/014_add_subscription_columns.sql pero no aplicada. Debe ejecutarse antes de que el manejador de webhook se active."
Bloqueadores: lo que impide el avance, incluyendo lo que intentaste. "Firma de webhook de Stripe fallando en el entorno de prueba. Intenté el parser de cuerpo raw, sigue dando 400. Siguiente: verificar la variable de entorno en la vista previa de Vercel."
Límitalo a 60-80 líneas. Cuando algo se resuelva, elimínalo. Cuando algo se envíe, archívalo.
La disciplina de actualización. Agrega un hook de Stop para recordártelo:
{
"hooks": {
"Stop": [
{
"command": "echo 'Before you close: update STATE.md with decisions, in-flight, and blockers from this session.'"
}
]
}
}El recordatorio por sí solo no es suficiente; el hábito debe ser automático. El camino más rápido: hazlo durante cinco sesiones consecutivas. Para la sexta sesión, te sentirás mal cerrando sin actualizar. La incomodidad es la señal de que el hábito se ha formado.
MEMORY.md es el índice para todo lo duradero. Cada entrada es una línea que apunta a un archivo separado. Cuatro tipos:
user_*: hechos duraderos sobre ti: zona horaria, contexto profesional, preferencias. user_location.md
feedback_*: reglas aprendidas de errores, con un campo de confianza. Empieza en 0.3, sube a 0.5 cuando el patrón se repite, promociona a CLAUDE.md en 0.9+. feedback_public_endpoints_need_rate_limits.md
project_*: estado y decisiones fechadas para un proyecto. Archiva cuando se envíe. project_stripe_integration_2026_05.md
reference_*: tablas de búsqueda para personas, herramientas, APIs. reference_neon_db_config.md
Mantén cada línea de índice por debajo de 200 caracteres y el índice por debajo de 200 líneas. Más allá de eso, las entradas se truncan y Claude no puede verlas.
STATE.md es para ahora. MEMORY.md es para siempre. La regla general: si lo dirías en un standup, va en STATE.md. Si lo escribirías en una wiki o un documento de incorporación, va en un archivo de memoria. Los standups son transitorios; las wikis son duraderas.
Cuando un proyecto se envía y STATE.md todavía contiene cinco líneas al respecto, mueve esas líneas a un archivo de memoria project_* fechado y bórralas. El proyecto no dejó de importar; dejó de ser actual. Esa distinción mantiene STATE.md útil.
Escribe estado, no un diario. Una entrada de diario: "Trabajé en la integración de Stripe. Fue complicado." Una entrada de estado: "Endpoint de webhook en app/api/webhooks/stripe/route.ts. La verificación de firma funciona localmente, falla en la vista previa de Vercel (formato de cuerpo raw incorrecto). Siguiente: verificar la configuración del middleware rawBody." Uno le da a la próxima sesión un punto de partida; el otro le da una memoria.
Dos anti-patrones más: entradas en curso sin una acción concreta que una nueva sesión pueda ejecutar, y entradas duplicadas para el mismo tema en varias sesiones. Fusiona los duplicados: un tema, una entrada, solo el estado actual.
Una buena actualización de sesión es de nueve a doce líneas: una decisión con su justificación, un elemento en curso con el siguiente paso, un bloqueador con lo que intentaste.
Escalando más allá de 50 archivos de memoria: la capa de resumen. Cada línea de puntero de MEMORY.md cuesta aproximadamente 100-150 tokens. Con 200 líneas, eso son 20-30K tokens de puros punteros. La solución: STRATEGY-DIGEST.md, un resumen de 2-3 oraciones de cada documento principal más un campo "Usar cuando:":
## q2-positioning.md
Q2 positioning targets AI enablement in mid-market sales orgs.
Use when: discussing target customer, pricing, or lead qualification.Claude lee el resumen (aproximadamente 3K tokens) y carga un documento completo solo cuando es relevante. Con 25 documentos de estrategia, eso son 3K tokens en lugar de 50K. El campo "Usar cuando:" es el mecanismo de enrutamiento: escríbelo como una condición de activación específica, no como una descripción del archivo.
STATE.md captura el estado actual (decisiones, en curso, bloqueadores) en menos de 80 líneas; actualízalo al final de la sesión y archiva el historial rápidamente. MEMORY.md indexa el conocimiento duradero en cuatro tipos (usuario, feedback, proyecto, referencia), limitado a 200 líneas. Comienza esta noche con tres líneas: una decisión, un elemento en curso, un bloqueador. Tres líneas son mejores que cero mientras se forma el hábito.