Cuántos tokens cuesta CLAUDE.md y qué tamaño darle

CLAUDE.md es un archivo Markdown de instrucciones permanentes que Claude Code carga al iniciar la sesión. No forma parte del prompt de sistema: llega como mensaje de usuario a continuación y sirve de guía, no de configuración obligatoria.

El modelo no conserva nada entre peticiones. Claude Code reenvía el prompt de sistema, el contexto del proyecto y los mensajes y resultados anteriores. Un solo encargo que lee cinco archivos y ejecuta pruebas genera varias peticiones, todas con CLAUDE.md completo.

Cada línea tiene coste en cada petición: reducido mientras funciona la caché y superior al precio de entrada normal cuando se reconstruye. Mantén el archivo corto y coloca lo que no se necesita siempre en recursos que se carguen cuando haga falta.

Qué archivos se cargan y cuándo

Claude Code concatena los archivos de memoria encontrados. A septiembre de 2026, su documentación enumera:

• →Política administrada: un CLAUDE.md de toda la organización, desplegado por TI, que no se puede excluir.
• →Usuario: ~/.claude/CLAUDE.md y reglas de ~/.claude/rules/, para todos tus proyectos.
• →Proyecto: ./CLAUDE.md o ./.claude/CLAUDE.md, más las reglas sin campo paths, compartidas con el control de versiones.
• →Local: ./CLAUDE.local.md, notas personales del proyecto que se añaden a .gitignore.
• →Memoria automática: las primeras 200 líneas o 25 KB del índice MEMORY.md; sus archivos temáticos se leen cuando hacen falta.

Los archivos del directorio de trabajo y sus padres se cargan al arrancar. Los CLAUDE.md de subdirectorios y las reglas con paths se cargan cuando Claude lee archivos afectados. Una importación @path/to/file trae el contenido al inicio, hasta cuatro niveles: dividir el texto en importaciones ordena, pero no ahorra tokens.

Por qué la caché no lo hace gratuito

La caché compara el comienzo de cada petición con lo procesado hace poco y cobra menos por la parte idéntica. Claude Code coloca primero las instrucciones y herramientas estables, luego los archivos del proyecto y después la conversación. En un turno normal, CLAUDE.md se lee de la caché.

A precios públicos de Anthropic de septiembre de 2026, una lectura cuesta una décima parte de la entrada normal en la mayoría de modelos, o menos en algunos recientes. Escribir cuesta 1,25 veces con duración de cinco minutos y el doble con una hora. CLAUDE.md se vuelve a escribir, por ejemplo:

• →Tras una pausa mayor que la duración de la caché: una hora en la conversación principal de una suscripción incluida, cinco minutos por defecto con API.
• →Al cambiar de modelo o, en la mayoría, de nivel de esfuerzo.
• →Si cambian definiciones de herramientas situadas antes del archivo, como un servidor MCP cargado por adelantado.
• →En cada subagente salvo Explore y Plan integrados, que abre contexto y caché propios con cinco minutos por defecto.
• →Al iniciar desde otro directorio o worktree, pues la caché queda vinculada en la práctica al directorio.

La caché reduce el precio, no el tamaño. El archivo ocupa ventana en cada petición y deja menos espacio antes de la compactación. Las reglas demasiado largas también se siguen peor. En una suscripción no hay factura por token, pero el mismo contexto consume límite del plan.

Cómo ver lo que cuesta el tuyo

Abre una sesión nueva y comprueba qué ocupa la ventana antes de escribir:

$/context

/memory lista los archivos de memoria y puede abrirlos en el editor. Desde Claude Code v2.1.251, /usage añade Prompt cache (main), con la proporción de lecturas y los fallos. Si los fallos crecen, el prefijo que incluye la memoria se reescribe con frecuencia.

Qué debe contener

La prueba de Anthropic para cada línea es si quitarla haría que Claude cometiera errores. Lo que supera la prueba suele ser breve:

• →Comandos de compilación, pruebas y análisis que Claude no puede adivinar.
• →Reglas de estilo distintas de las habituales y que el formateador no impone.
• →Convenciones del repositorio sobre ramas, commits y solicitudes de cambio.
• →Decisiones de arquitectura específicas del proyecto.
• →Particularidades del entorno, como servicios o variables necesarios.
• →Problemas poco evidentes que ya causaron errores.

Redacta instrucciones comprobables: «Ejecuta npm test antes de confirmar cambios» dice más que «prueba tus cambios». La documentación recomienda menos de 200 líneas por archivo.

Qué mover y adónde

Un CLAUDE.md inflado suele contener información útil colocada demasiado pronto. Hay destinos más baratos:

• →Estructuras de carpetas, dependencias y descripciones de archivos que el código ya revela: elimínalas.
• →Referencias extensas: déjalas en su archivo y menciona la ruta sin @, para que Claude las abra solo cuando corresponda.
• →Procedimientos de varios pasos: conviértelos en skills; al comienzo solo se carga su descripción corta.
• →Reglas para una zona del proyecto: .claude/rules/ con paths o un CLAUDE.md en ese subdirectorio.
• →Acciones obligatorias tras editar, como formatear: un hook. No ocupa contexto salvo que devuelva salida y su ejecución es automática.

Cómo recortarlo

Desde v2.1.206, /doctor propone recortes para un CLAUDE.md versionado. Sugiere quitar lo que puede deducir del código y mover instrucciones siempre cargadas a archivos o skills que se abren cuando hacen falta.

$/doctor

Después, revisa manualmente:

• →Elimina una regla que Claude ya sigue sin ayuda y comprueba si cambia su comportamiento.
• →Pasa notas para mantenedores a comentarios HTML de bloque; Claude Code retira <!-- ... --> antes de enviar el texto.
• →Resuelve instrucciones contradictorias: se pagan ambas y Claude puede seguir cualquiera.
• →En un monorrepositorio, excluye archivos de otros equipos con claudeMdExcludes.
• →Para subagentes propios que no lo necesitan, usa omitClaudeMd: true desde v2.1.271.

AGENTS.md en Codex CLI

Codex CLI lee AGENTS.md. Según su documentación de septiembre de 2026, prepara una cadena de instrucciones al arrancar:

• →Global: en ~/.codex o CODEX_HOME, usa AGENTS.override.md si existe y, si no, AGENTS.md.
• →Proyecto: desde la raíz hasta el directorio actual, toma como máximo un archivo por nivel: override, AGENTS.md o un nombre alternativo configurado.
• →Los une desde la raíz, omite los vacíos y se detiene al alcanzar project_doc_max_bytes, 32 KiB por defecto.

La cadena entra en el primer turno y viaja en los posteriores. Codex recomienda acortar AGENTS.md y anidar reglas por directorio para conservar los límites de uso. A septiembre de 2026, su tabla de créditos valora la entrada cacheada a una décima parte sin recargo separado por escritura. Puedes inspeccionar lo que ve el modelo:

$codex debug prompt-input

Un archivo puede servir a ambos agentes. Desde v2.1.277, Claude Code lee AGENTS.md si no hay CLAUDE.md ni CLAUDE.local.md en el directorio o sus padres. Si los hay, @AGENTS.md en CLAUDE.md lo importa explícitamente. Claude Code no lee AGENTS.override.md.

Coste fijo y coste variable

Acortar instrucciones reduce el coste fijo. El resto depende de cada tarea: archivos leídos, salidas de comandos e historial. Indicar el archivo concreto y abrir una sesión por tarea limita esa parte.

Para ponerle un techo, capsul usa Claude Code o Codex CLI con la sesión ya iniciada, envía lo que pide la tarea bajo el presupuesto de tokens que fijas e informa de lo que dejó fuera. Los resultados medidos están en la página del banco de pruebas.