🚨 ¡Nueva review! 🔇 Los mejores cascos con ANC del mercado: los Sony WH-1000XM4 . ¡Échale un ojo! 👀

Logo GatoBobo

Lo que sí funciona en CLAUDE.md y lo que ya no hace tanta falta

Hay muchos consejos sobre CLAUDE.md que circulan por internet. La mayoría son de 2024. Esto es lo que importa ahora.

Escrito por domin el 24 de junio de 2026
#claude #claude-code #ia #herramientas #productividad #2026

De qué va esto del CLAUDE.md

CLAUDE.md es el archivo que Claude Code lee al arrancar cada sesión. Define el contexto del proyecto, las reglas de trabajo y el comportamiento esperado. Si está bien hecho evita tener que explicar lo mismo una y otra vez, por la contra mal hecho, ocupa contexto sin aportar nada y consumiendo tokens inútilmente.

Circulan muchos artículos con consejos sobre CLAUDE.md, la mayoría escritos en 2024 cuando los modelos y las ventanas de contexto eran distintos. Algunos de esos consejos siguen siendo válidos pero otros han quedado obsoletos. Y hay cosas nuevas que en 2024 no existían o no importaban.

Lo que ya no es tan importante

Antes de entrar en lo que sí funciona, vamos a acabar con dos consejos que se leen de forma habitual pero que por la evolución de los modelos ya no son así:

Hay que mantener CLAUDE.md por debajo de 200 líneas. Este consejo tenía sentido cuando las ventanas de contexto eran pequeñas y cada token importaba. Los modelos actuales trabajan con contextos de 200.000 tokens o más. Un CLAUDE.md de 400 líneas bien estructurado no supone ningún problema. Lo que importa no es la longitud, sino la utilidad de cada línea.

Optimiza las primeras 30 líneas porque Claude presta más atención al principio. Hay una base real en esto, pero los modelos de 2026 siguen instrucciones distribuidas por todo el contexto con bastante fiabilidad. No hace falta meter todo al principio sacrificando la claridad del documento.

Lo que sí funciona

Separar reglas de preferencias

Cuando todo tiene el mismo peso, nada tiene peso. Distinguir explícitamente qué es obligatorio y qué es una preferencia ayuda a que Claude Code priorice correctamente cuando tiene que tomar decisiones.

# Reglas estrictas
- Nunca modificar archivos fuera de src/
- Nunca instalar dependencias sin confirmación
- Siempre usar TypeScript estricto

# Preferencias
- Nombres de variables concisos
- Composición sobre herencia
- Componentes pequeños y enfocados

La diferencia entre una regla y una preferencia es que la regla no se negocia. Si no lo dejas claro, Claude Code puede tratarlas igual.

Sección de antipatrones

La mayoría de los CLAUDE.md solo describen lo que Claude Code debería hacer. Los más efectivos también definen lo que no debe hacer nunca.

# Antipatrones
- No crear archivos de documentación que nadie pidió
- No refactorizar código que no tiene relación con la tarea
- No añadir comentarios que explican lo que hace el código (los nombres ya lo hacen)
- No usar `any` en TypeScript sin permiso explícito
- No instalar librerías nuevas para resolver algo que ya existe en el proyecto

Esto reduce la tendencia del modelo a hacer cosas razonables pero que nadie pidió.

CLAUDE.md recursivos por directorio

Claude Code lee los archivos CLAUDE.md desde la raíz del proyecto hasta el directorio en el que está trabajando, acumulando instrucciones de lo general a lo específico. Esto permite dar instrucciones distintas a distintas partes del proyecto.

/CLAUDE.md              → reglas globales del proyecto
/src/CLAUDE.md          → convenciones del código frontend
/src/api/CLAUDE.md      → reglas específicas para la capa de API
/scripts/CLAUDE.md      → instrucciones para scripts de mantenimiento

En un proyecto con partes muy distintas (frontend, API, scripts, infraestructura), esto evita tener un CLAUDE.md raíz que intente cubrirlo todo y acabe siendo difícil de mantener.

Imports con @ para documentación extensa

En lugar de meter todo en un solo archivo, se puede referenciar documentación externa con la sintaxis @ruta/archivo:

Para el sistema de diseño consulta @docs/design-system.md

Al crear nuevos componentes, sigue las convenciones de @docs/component-conventions.md

Para migraciones de base de datos, lee primero @docs/database-rules.md

Claude Code carga ese archivo solo cuando es relevante para la tarea. Útil para documentación técnica extensa que no aplica a todas las tareas y no tiene sentido cargar siempre.

Lo que es nuevo y sí importa en 2026

Documentar los hooks activos

Claude Code permite configurar hooks que se ejecutan automáticamente: formatear al guardar, lanzar el linter después de cada edición, verificar el build al cerrar la sesión.

Si tienes hooks configurados y no los documentas en CLAUDE.md, Claude puede intentar hacer manualmente lo que ya hace el hook, duplicando trabajo o creando conflictos.

# Hooks activos
- PostToolUse (Write/Edit): Prettier formatea el archivo automáticamente
- PostToolUse (Write/Edit): ESLint corrige el archivo automáticamente
- Stop: se ejecuta `npm run build` al cerrar la sesión

No hace falta pedir formato ni lint manualmente, los hooks lo hacen.

Documentar los MCP servers disponibles

Si el proyecto tiene MCP servers configurados, Claude necesita saber que existen y para qué sirven. Sin esa documentación, puede intentar hacer cosas a mano que ya tiene disponibles como herramienta.

# MCP servers disponibles
- GitHub MCP: para leer issues, PRs y comentarios de revisión
- Base de datos MCP: acceso directo a la BD de desarrollo (solo lectura)
- Playwright MCP: para abrir el navegador y verificar cambios visualmente

Úsalos cuando corresponda en lugar de intentar hacer lo mismo por otros medios.

Documentar las skills del proyecto

Claude Code tiene un sistema de skills que encapsulan flujos de trabajo completos. Si el proyecto tiene skills definidas, documentarlas en CLAUDE.md evita que Claude improvise flujos que ya están estandarizados.

# Skills disponibles
- /new-post <slug>: crea un nuevo post con el scaffold correcto
- /optimize-images: convierte imágenes a WebP y redimensiona
- /deploy: construye y despliega en producción

Usa estas skills en lugar de ejecutar los pasos manualmente.

Escribir el motivo detrás de cada regla

Las instrucciones sin contexto son frágiles. Si Claude no entiende la razón detrás de una regla, puede saltársela cuando la situación parece una excepción razonable.

❌ Sin contexto

"No usar floats en CSS." Claude lo sigue hasta que encuentra un caso donde parece razonable y lo ignora.

✅ Con contexto

"No usar floats en CSS — el proyecto usa un sistema de grid propio que entra en conflicto con floats." Claude entiende el motivo y lo respeta en todos los casos.

No hace falta escribir un tochaco por cada regla. Una frase de contexto es suficiente.

Separar bien qué va en CLAUDE.md y qué en memoria

En 2026, Claude Code tiene un sistema de memoria persistente separado del CLAUDE.md del proyecto. La distinción importa y mezclarlos hace que el archivo del proyecto acabe con instrucciones que no tienen nada que ver con él.

CLAUDE.md del proyecto
  • Contexto del repositorio: arquitectura, convenciones, comandos de build
  • Reglas que aplican a este proyecto en concreto
  • Antipatrones específicos de este código
  • Documentación de hooks, MCPs y skills del proyecto
Memoria del usuario (/memory)
  • Preferencias personales de estilo de respuesta
  • Instrucciones que quieres en todos tus proyectos
  • Cosas que quieres que Claude recuerde sobre ti como usuario
  • Reglas de comportamiento general que no dependen del repo

En resumen

✅ Sigue funcionando

Separar reglas de preferencias. Sección de antipatrones. CLAUDE.md recursivos por directorio. Imports con @ para documentación extensa.

📉 Ya no es crítico

El límite de 200 líneas. Meter todo en las primeras 30 líneas. Obsesionarse con el tamaño del archivo.

🆕 Nuevo en 2026

Documentar hooks activos. Documentar MCP servers disponibles. Documentar skills del proyecto. Escribir el motivo detrás de cada regla.

🗂️ Separar bien

CLAUDE.md del proyecto es para el contexto del repo. La memoria del usuario es para preferencias personales. No mezclarlos.

EA, a vibercodear, nos beermos en los bares! 🍻