English

Puntúa tu CLAUDE.md como un linter

Tu CLAUDE.md está gravando cada uno de tus prompts.

Un archivo de instrucciones como CLAUDE.md, AGENTS.md o un prompt de sistema no es documentación gratis. Se antepone al contexto en cada turno de cada conversación. Cada regla contradictoria, cada lugar común vago, cada instrucción duplicada la vuelve a leer el modelo en cada mensaje que envías. Eso significa que el exceso no solo es desordenado: infla el costo en tokens y, peor aún, degrada la capacidad del modelo para seguir las reglas que sí importan. Trata el archivo como código y pásale un linter.

Por qué el archivo grava cada turno

El contexto no es memoria persistente; el archivo de instrucciones completo se reenvía con cada solicitud. Así que un CLAUDE.md de 4.000 tokens te cuesta 4.000 tokens en el turno uno y en el turno cincuenta por igual. Dos modos de fallo lo empeoran más de lo que sugiere el conteo bruto de tokens:

• Contradicciones — "siempre escribe tests primero" tres secciones arriba de "muévete rápido, omite tests en spikes" obliga al modelo a adivinar qué regla gana, y adivina de forma inconsistente.
• Lugares comunes — "escribe código limpio y mantenible" consume tokens y no dirige nada, porque no tiene un significado operativo sobre el que el modelo pueda actuar.

La atención del modelo es finita. El relleno diluye la señal de las reglas que te importan.

El mecanismo: puntúalo sobre 100

Pasa una rúbrica sobre el archivo, a mano o con un script rápido, empezando en un 100 perfecto y restando:

Inicio:                      100
- cada par contradictorio:   -10   (dos reglas que no pueden cumplirse a la vez)
- cada clúster redundante:   -5    (la misma instrucción dicha N veces)
- cada lugar común:          -3    (sin significado operativo verificable)
- sobredimensionado (> ~2k):  -10   (todo el archivo se reenvía cada turno)

Incluso puedes hacer que el modelo audite sus propias instrucciones: pega el archivo y pregunta "encuentra cada par de reglas que se contradigan, cada clúster que repita la misma instrucción y cada línea sin significado verificable". Luego recorta lo que perdió puntos. Conserva las reglas específicas, sin conflicto y dichas una sola vez.

Antes y después

Un archivo de reglas magro significa prompts más baratos y mejor adherencia en cada turno.

Movidas avanzadas

• Automatiza la auditoría en CI. Un script pequeño (o una pasada programada del modelo) puede marcar el archivo cuando supera un presupuesto de tokens o cuando dos reglas chocan, antes de que el exceso se acumule.
• Prefiere reglas verificables. "Corre pytest antes de decir que terminaste" supera a "prueba con cuidado" porque el modelo puede verificar que hizo lo indicado.
• Empuja el detalle a archivos referenciados. Mantén el CLAUDE.md con las reglas siempre relevantes y enlaza a docs por área que el modelo carga solo cuando las necesita (divulgación progresiva).
• Vuelve a puntuar tras cada edición. Los archivos de instrucciones se pudren igual que el código; un lint trimestral evita que el impuesto vuelva a colarse.

Recursos

• Documentación de Anthropic — Manage Claude's memory (CLAUDE.md)
• Anthropic — Claude Code best practices
• Anthropic — Effective context engineering for AI agents
• AGENTS.md — un formato abierto y simple para instrucciones de agentes