English

Haz que tu archivo de reglas sea un mapa, no una biblioteca

Tu archivo de reglas siempre activo está volviendo más tonto a tu agente.

El instinto es enseñarle al agente todo de entrada: convenciones de código, pasos de despliegue, el esquema, la guía de estilo, cada trampa que hayas encontrado. Así el archivo de reglas (un CLAUDE.md, un system prompt, un .cursorrules) crece y crece. Pero todo lo que hay en ese archivo se carga en cada turno, lo necesite o no la tarea. Pasado cierto tamaño deja de ayudar y empieza a estorbar.

Cada línea es un impuesto por turno

Un archivo de reglas siempre activo se antepone al contexto en cada solicitud. Eso tiene dos costos:

• Costo de tokens — pagas esos tokens en cada turno, y le quitan espacio a la tarea real y al código que el agente necesita leer.
• Costo de señal — este es el que la gente pasa por alto. Cuando el archivo está lleno de detalle irrelevante para la tarea actual, las pocas reglas que sí importan se diluyen. El modelo tiene que encontrar la señal entre tu ruido, y las instrucciones enterradas en un muro de texto se siguen con menos fiabilidad.

Un archivo de reglas de 2000 líneas no hace más inteligente al agente. Hace que las 20 líneas importantes sean más difíciles de ver.

Un mapa apunta; una biblioteca acumula

Replantea el archivo como un mapa del código, no como una biblioteca de todo sobre él. Un mapa es corto. Dice dónde están las cosas y cómo encontrar más, y confía en que el agente irá a buscar el detalle cuando una tarea de verdad lo pida.

# CLAUDE.md (el mapa)

## Reglas durables (siempre ciertas, mantenlas ajustadas)
- Corre `make test` antes de cada commit; el umbral de cobertura es 98%.
- Nunca hagas commit a `main`; crea una rama primero.
- Los errores de la API devuelven la forma `Problem` en `src/errors.ts`.

## Cargar bajo demanda (punteros, no contenidos)
- Pasos de despliegue: ver `docs/DEPLOY.md`
- Modelo de datos y migraciones: ver `docs/schema.md`
- Guía de estilo del frontend: ver `docs/style.md`

Las reglas durables — el puñado de cosas ciertas en cada tarea — se quedan en la capa siempre activa. Todo lo demás se convierte en un puntero que el agente sigue solo cuando el trabajo lo toca. Las funciones de divulgación progresiva (skills, docs referenciados, archivos cargados por herramientas) existen precisamente para que el detalle viva fuera del camino caliente.

Divide por "siempre vs. a veces"

Clasifica cada regla candidata en uno de dos buckets:

Si una regla solo importa cuando tocas el código de pagos, no debería gravar cada turno no relacionado. Muévela junto al código de pagos o a un doc que el mapa referencie.

Movidas avanzadas

• Presupuesta la capa siempre activa. Ponle un tope duro de líneas. Cuando esté llena, agregar una regla significa sacar otra a un doc bajo demanda, no hacer crecer el archivo.
• Pon los docs donde está el trabajo. Una nota sobre un módulo vive mejor en el directorio de ese módulo, cargada cuando el agente lee esa zona, no globalmente.
• Poda con periodicidad. Las reglas se pudren. Una convención que abandonaste hace seis meses sigue costando tokens y diluyendo la señal hasta que alguien la borre.
• Escribe punteros, no resúmenes. "Ver docs/schema.md" gana a un resumen inline a medias que se desvía del esquema real.

Recursos

• Anthropic — Gestionar la memoria de Claude (CLAUDE.md)
• Anthropic — Agent Skills y divulgación progresiva
• Anthropic Engineering — Ingeniería de contexto efectiva para agentes de IA
• "Lost in the Middle": cómo la longitud del contexto degrada la recuperación (Liu et al.)