English

Mantén tu archivo de reglas liviano

Tu agente de IA vuelve a leer un archivo en cada mensaje. No una vez por sesión — una vez por solicitud. Si tu CLAUDE.md son 800 líneas de historia, guías de estilo a medio terminar e instrucciones que nadie ha tocado desde marzo, estás pagando el costo en tokens de todo eso, cada vez, sin importar si la tarea actual lo necesita o no.

El archivo es un system prompt, no documentación

Es fácil tratar un archivo de reglas como una página de wiki — un lugar donde volcar cualquier cosa que algún día podría ser útil. Ese es el modelo mental equivocado. La documentación es algo que el lector elige abrir. Un archivo de reglas se antepone a cada prompt sea relevante o no. Se comporta como un system prompt, y los system prompts tienen una curva de costo: cada línea son tokens gastados antes de que el modelo haya leído una sola palabra de la tarea real.

Ese costo se acumula de dos maneras. Primero, literalmente — más tokens por solicitud, en cada solicitud, durante toda la vida del proyecto. Segundo, diluye la señal. Un modelo al que le das 200 líneas enfocadas de "cómo funciona realmente esta base de código" las sigue con más fiabilidad que uno al que le das 800 líneas donde las diez que importan para esta tarea quedan enterradas entre un changelog y un párrafo sobre un paso de compilación en desuso. El exceso no solo cuesta dinero, cuesta obediencia.

Qué sí va, qué no va

Una heurística útil: conserva solo lo que cambia cómo se comporta el agente en la mayoría de las tareas. Empuja todo lo demás a archivos que pueda abrir cuando los necesite.

Deja en el archivo de reglas:

• Convenciones — nombres, estructura de carpetas, patrones que realmente aplicas
• Comandos — cómo compilar, probar, hacer lint, desplegar
• Trampas — lo no obvio que muerde a cada nuevo colaborador (este servicio necesita dos variables de entorno configuradas antes de que pasen las pruebas, este directorio se genera y nunca debe editarse a mano)

Enlaza en lugar de incrustar:

• Referencias completas de API o volcados de esquemas
• Contexto histórico largo ("por qué migramos de X en 2024")
• Guías de estilo más largas que una lista de verificación
• Cualquier cosa específica de una tarea en vez de a nivel de todo el proyecto

El patrón es un archivo raíz corto que enuncia lo esencial y luego apunta a archivos de detalle — docs/testing.md, docs/deploy.md, docs/decisions/ — que el agente abre solo cuando la tarea realmente toca esa área. Obtienes la profundidad cuando se necesita y nada del impuesto cuando no.

Antes y después

Un archivo inflado mezcla todo en un solo muro plano de texto: instrucciones de configuración, una referencia completa de API REST, tres párrafos sobre por qué se reemplazó una biblioteca, reglas de formato y los comandos reales para correr las pruebas — todo con el mismo peso, todo cargado cada vez.

Un archivo liviano, en cambio, se lee como una tabla de contenidos con apenas el detalle suficiente para actuar:

## Commands
- Test: npm test (coverage gate 98%)
- Build: npm run build

## Conventions
- One component per file, PascalCase
- API errors always return {error, code} — see docs/api-errors.md

## Gotchas
- .env.local is required for tests; see docs/setup.md
- Generated files live in /gen — never edit by hand

El mismo ecosistema de información, una factura de tokens radicalmente distinta. La versión liviana le dice al agente exactamente qué cambia su comportamiento ahora mismo y difiere el resto a archivos que puede traer solo cuando la tarea los necesita.

Un presupuesto aproximado: ~200 líneas

Ninguna herramienta impone un límite estricto, pero ~200 líneas es un techo manejable para el archivo raíz. Pasado ese punto casi siempre estás documentando algo específico de una tarea que corresponde a un archivo enlazado en vez del que se carga siempre. Si tu archivo ha crecido más allá de eso, la solución no es recortar adjetivos — es encontrar las secciones que solo importan para un tipo de tarea y sacarlas.

Trucos avanzados

• Actualízalo sobre la marcha. El archivo de reglas no es un artefacto de configuración de una sola vez — cuando el agente aprende algo nuevo sobre la base de código a mitad de sesión (una trampa con la que acaba de toparse, una convención que acaba de confirmar), dile que guarde ese dato de vuelta en el archivo. Eso mantiene el archivo al día sin un paso de mantenimiento aparte, y evita que la siguiente sesión — o el siguiente compañero — vuelva a deducir la misma lección.
• Audita el exceso de tokens periódicamente. Lee el archivo y pregúntate, por cada sección, si cambió la salida del agente en el último mes. Las secciones que no lo hicieron son candidatas a sacarse o eliminarse. La meta no es un archivo corto por sí mismo — es un archivo donde cada línea sigue aportando su peso.

La conclusión

Tu archivo de reglas no es una biblioteca que construyes para la posteridad. Es un pase de abordar — debería decirle al agente exactamente lo que necesita para abordar correctamente, y nada más. Nueva sesión, nuevo compañero, mismo contexto, sin volver a explicar — siempre y cuando lo que está en el archivo se gane su lugar en cada solicitud.