El sistema de contexto que evita que Claude se pierda

Trabaja con un agente más de unos días y chocas con el mismo muro: olvida cada decisión que tomaste, y una función nueva rompe otras tres. Estuve arreglando ese mismo dolor una y otra vez, hasta que me di cuenta de que la solución ya estaba en mi repo, medio construida sin querer. Aquí está la versión real, sacada de mis propios proyectos, y los dos archivos que de verdad me faltaban.

Por qué se pierde

Un agente no tiene memoria entre sesiones. Cada chat nuevo empieza de cero. Le explicas el proyecto, toma decisiones razonables, avanza. Mañana abres otro chat y ya no recuerda nada: ni el stack, ni por qué elegiste esa librería, ni qué no había que tocar. Así que vuelves a explicar, él vuelve a adivinar, y poco a poco el código empieza a contradecirse. No es que la IA sea tonta. Es que le pides que recuerde algo que nunca guardaste en ningún sitio.

La idea: archivos que viajan con el repo

La solución no es un prompt más largo. Es un conjunto de archivos que el agente lee antes de hacer nada, y que viven en el repo para siempre. Otro día, otro agente, otra persona del equipo: todos arrancan con el mismo contexto. Así se ve el mío, más o menos:

mi-proyecto/
├── CLAUDE.md                  # qué es el proyecto y qué NO es
├── .claude/
│   ├── agent-trust-policy.md  # reglas: lo que el agente nunca debe hacer
│   └── settings.json          # hooks que bloquean comandos peligrosos
├── design.md                  # tokens de diseño (colores, tipografía)
├── code-standards.md          # convenciones de código (el que me faltaba)
└── docs/
    ├── arquitectura.md        # stack, límites e invariantes
    └── specs/
        └── 01-login.md        # una unidad a la vez

• CLAUDE.md — qué es el producto, para quién, y qué está deliberadamente fuera de alcance. Lo primero que lee el agente.
• agent-trust-policy.md — las reglas de comportamiento: lo que el agente nunca debe hacer (borrar fuera de su zona, tocar secretos, hacer push a main sin pasar por PR).
• design.md — los tokens de diseño, para que no invente colores ni tipografías.
• arquitectura.md — el stack, los límites entre capas y los invariantes que el código nunca rompe.
• docs/specs/ — una spec por unidad de trabajo. La pieza que de verdad cambia las cosas.

El bucle: una unidad a la vez

Aquí está el cambio de mentalidad. No le pides al agente "construye el dashboard". Escribes una spec pequeña, con un objetivo, las decisiones, qué no tocar, y una checklist de qué tiene que ser verdad para darla por terminada:

# Spec: login con email

## Objetivo
Un usuario puede registrarse e iniciar sesión con email. Nada más.

## Decisiones
- Auth con Clerk (ya instalado).
- No tocar el navbar ni el sidebar.

## Implementación
- Crear /login y /registro con los componentes de Clerk.
- Proteger todas las rutas salvo /login y /registro.

## Checklist (verificar antes de cerrar)
- [ ] Rutas protegidas por defecto
- [ ] Sin colores hardcodeados (usar los tokens de design.md)
- [ ] npm run build pasa

Luego le pasas la spec en un solo prompt. El agente lee el contexto, lee la spec, y construye contra un sistema en vez de adivinar:

Lee CLAUDE.md, code-standards.md y docs/specs/01-login.md.
Marca la spec 01 como "en progreso" en el progress tracker.
Impleméntala exactamente como está escrita, sin salirte del alcance.

Revisas el resultado contra la checklist. Si pasa, cierras la unidad y haces push. Si algo está mal, escribes un prompt correctivo concreto, arreglas esa cosa, y sigues. Una unidad limpia cada vez, en lugar de un agente corriendo suelto durante una hora y dejándote un montón que desenredar.

El archivo que casi todos saltan: el estado

Este es el que más trabajo hace y el que más gente olvida. Un archivo de estado que se actualiza en cada paso, y que reconstruye todo el contexto en un solo prompt cuando vuelves mañana, la semana que viene, o dentro de seis meses:

# Estado del proyecto

**Fase actual:** auth
**En progreso:** login con email (spec 01)
**Completado:** layout base, tema oscuro
**Decisiones:** Clerk para auth; Postgres solo para metadatos
**Siguiente:** dashboard del usuario

Esto es exactamente lo que resuelve la falta de memoria. El agente lo lee, entiende dónde está el proyecto, y retoma justo donde lo dejaste. No te tienes que volver a explicar.

Los dos archivos que me faltaban

Yo ya tenía la mitad de esto antes de ver el video: las reglas del agente, el contexto del proyecto, el estado. Lo que el video me hizo ver fueron dos huecos.

El primero, code-standards.md. Sin él, el patrón que el agente usa en la función 16 no se parece al de la función 5. Cuatro líneas evitan semanas de deriva:

# Convenciones de código

- TypeScript en modo estricto. Nada de `any`.
- `use client` solo cuando el componente necesita interactividad.
- Nada de clases de color crudas de Tailwind: usar los tokens.
- Un componente por archivo. Nombres en inglés.

El segundo, separar los invariantes en arquitectura.md: las reglas que el sistema nunca viola. Cosas como "los handlers de petición no corren trabajo de IA largo, eso va en tareas de fondo" o "la autorización se valida en cada mutación". El agente las trata como límites, no como sugerencias.

Cuándo importa (y cuándo es exagerado)

Para arreglar un archivo, esto sobra: abre el chat y hazlo. Pero para algo que vas a mantener durante semanas, con un agente entrando y saliendo, es la diferencia entre avanzar y pelear contra tu propio código en la tercera semana. El trabajo de escribir estos archivos es real, y por eso la gente lo salta para sentirse productiva ya. El tiempo que ahorras saltándolo es el mismo que pierdes después depurando salidas que ya no tienen sentido.

Lo que de verdad pasa aquí

El sistema no es un producto ni un prompt mágico. Es que el pensamiento se queda contigo y el agente recibe un contrato escrito en vez de adivinar. Los archivos son baratos. La claridad es lo caro, y es la parte que la IA todavía no hace por ti.

Ahora prueba esto

En tu próximo proyecto, antes de pedirle nada al agente:

• Escribe un CLAUDE.md. Tres frases de qué es y una lista de qué NO es.
• Escribe una spec para la primera función, con su checklist.
• Crea un archivo de estado y pídele al agente que lo actualice en cada paso.
• Añade code-standards.md en cuanto el agente invente su segundo patrón distinto.