CLAUDE.md es un archivo markdown que Claude Code carga automáticamente al inicio de cada sesión; no se ejecuta como una configuración, sino que simplemente se inserta en el prompt como texto.
El principal error técnico que cometen casi todos: dividir el archivo en @imports, pensando que esto ahorra contexto. En realidad, las importaciones se cargan por completo de inmediato; solo las reglas con ámbito de ruta en .claude/rules/ realmente ahorran contexto.
Referencia de tamaño: hasta 200 líneas para el CLAUDE.md del proyecto, hasta 30 líneas para el ~/.claude/CLAUDE.md personal; los modelos mantienen de forma fiable en la memoria aproximadamente 150-200 instrucciones simultáneamente, y el prompt del sistema de Claude Code ya ocupa unas 50 de ellas.
CLAUDE.md, AGENTS.md y Cursor Rules no son intercambiables: Claude Code solo lee CLAUDE.md, Cursor lee .cursor/rules/ y AGENTS.md, y AGENTS.md como estándar abierto se encuentra actualmente en más de 60.000 repositorios.
El artículo incluye un ejemplo de trabajo de CLAUDE.md para un proyecto Spring Boot, un análisis de errores comunes y dos errores documentados de los que la mayoría de las guías no hablan.
CLAUDE.md es un archivo markdown normal que Claude Code carga automáticamente al inicio de cada sesión, dando al modelo lo que se puede llamar una memoria persistente del proyecto: comandos, arquitectura, convenciones, todo aquello que el modelo no puede deducir del propio código (documentación oficial de Claude Code). Formularía la esencia del archivo de la manera más sencilla posible: CLAUDE.md no hace a Claude más inteligente, sino que hace que Claude deje de olvidar.
Esto no es una hipérbole. Personalmente me encontré en una situación en la que, durante una semana, tuve que repetir la misma observación sobre el patrón arquitectónico del proyecto en cada sesión, y tan pronto como esa línea se trasladó a CLAUDE.md, la necesidad de repetirla desapareció (una experiencia similar se describe en el análisis de maketocreate.com en el ejemplo de un proyecto Laravel con el patrón "repositorio en lugar de Eloquent en los controladores").
Diferencia con README.md: README está escrito para personas que abren el repositorio por primera vez; es el escaparate del proyecto. CLAUDE.md está escrito para el modelo, que ya "sabe" cómo se ve el código típico y solo necesita aquello que distingue a su proyecto de las suposiciones predeterminadas.
Diferencia con AGENTS.md: AGENTS.md es un estándar abierto multiplataforma que es leído por Codex, Cursor, Copilot, Gemini CLI y otros. Claude Code no lo lee de forma nativa, solo CLAUDE.md (TECHSY, verificado en un repositorio real). Más detalles sobre esto en la sección de comparación a continuación.
Diferencia con Cursor Rules: Cursor Rules es un formato específico para Cursor (.cursor/rules/*.mdc), con su propio sistema de frontmatter YAML y modos de activación. Es un sistema paralelo, no compatible con CLAUDE.md: si colocas CLAUDE.md en un proyecto de Cursor, Cursor simplemente lo ignorará.
¿Cómo utiliza Claude CLAUDE.md?
Claude Code busca archivos CLAUDE.md en la jerarquía de directorios y los carga con un comportamiento diferente según el nivel:
Global (~/.claude/CLAUDE.md) — configuraciones personales que se aplican en cada proyecto en tu máquina.
Raíz del proyecto (./CLAUDE.md) — el archivo principal que se commitea en git y funciona para todo el equipo.
CLAUDE.md anidados en subdirectorios — se cargan no inmediatamente, sino solo cuando Claude realmente accede a los archivos en el subdirectorio correspondiente. Este es un diseño intencional: un monorepo con 50 subdirectorios no inflará el contexto con instrucciones que no son necesarias en este momento (Serenities AI).
Cuando las instrucciones de diferentes niveles entran en conflicto, se aplica una regla simple: una instrucción más específica anula una más general. Si la política de la organización dice "4 espacios para la indentación" y el CLAUDE.md del proyecto dice "2 espacios", para este proyecto prevalece la instrucción del proyecto (Serenities AI). Vale la pena tener en cuenta esta regla también cuando decidas en qué nivel escribir algo: algo verdaderamente común para todos tus proyectos es mejor colocarlo inmediatamente en el archivo global en lugar de duplicarlo en cada proyecto.
¿Cómo carga Claude Code CLAUDE.md técnicamente: imports vs rules vs compaction
Esta es la sección por la que me senté a escribir este artículo, porque casi todas las guías que revisé antes de escribir dan el consejo "mantén el archivo corto", pero ninguna explica adecuadamente por qué algunas técnicas de reducción de contexto funcionan y otras solo parecen funcionar.
@imports se cargan de forma anticipada (eagerly). Si divides un CLAUDE.md de 500 líneas en cinco importaciones de 100 líneas cada una, obtendrás un conjunto de archivos más fácil de mantener, pero el contexto que realmente se carga en el modelo seguirá siendo el mismo volumen de 500 líneas. La importación se expande por completo en el momento de inicio de la sesión, como si hubieras insertado el contenido del archivo directamente (Claude Certification Guide). Esta es la trampa en la que casi caigo: parecía lógico que dividir en archivos redujera la carga, pero en realidad solo reduce el caos en tu editor.
`.claude/rules/*.md` con frontmatter `paths:` se cargan bajo demanda (on-demand). A diferencia de las importaciones, los archivos de reglas en .claude/rules/ se cargan solo cuando Claude realmente trabaja con un archivo que coincide con el patrón glob especificado. Este es el único mecanismo en este sistema que realmente, y no condicionalmente, reduce el contexto (documentación oficial). Si tu objetivo es reducir el volumen de contexto, no solo poner orden en los archivos, necesitas reglas, no imports.
Compactación de sesión. El CLAUDE.md raíz sobrevive a /compact — después de comprimir el historial de la conversación, Claude lo lee nuevamente del disco y lo reinyecta en la sesión. Pero los CLAUDE.md anidados y las reglas con ámbito de ruta no se restauran automáticamente después de la compactación; se vuelven a cargar solo cuando Claude accede al subdirectorio o archivo correspondiente la próxima vez (documentación oficial).
Recorte incorporado. A partir de Claude Code v2.1.206, hay un comando /doctor que analiza tu CLAUDE.md commiteado y sugiere qué eliminar: todo lo que el modelo puede deducir directamente del código (estructura de carpetas, lista de dependencias, resumen de arquitectura) — para eliminar; los obstáculos, las justificaciones de las decisiones y las convenciones no estándar que el código no muestra por sí solo — para conservar (documentación oficial). Considero este criterio — "¿se puede deducir del código?" — la mejor prueba práctica para cualquier línea en tu archivo, y volveré a él más adelante en la sección de mejores prácticas.
¿Qué debe estar obligatoriamente en CLAUDE.md?
Abordo esta lista no como un conjunto arbitrario de categorías, sino a través de un criterio que ya mencioné anteriormente: aquí va solo aquello que el modelo no puede deducir de forma fiable por sí mismo del código. Si la arquitectura se puede entender en un 90% simplemente abriendo tres archivos, no vale la pena describirla. Pero hay categorías donde, sin una instrucción explícita, el modelo casi siempre adivina incorrectamente o gasta pasos en aclaraciones, y estas son las que componen esta lista según mi experiencia práctica.
Pila tecnológica — lenguaje, framework, versiones que no siempre son claramente visibles desde package.json o pom.xml. Esto es especialmente cierto en períodos de transición: si el proyecto está parcialmente en Java 17, parcialmente ya en 21, o utiliza Spring Boot 3.x con módulos separados en una versión anterior, el modelo no lo adivinará, y la aplicación incorrecta de la API de una versión más nueva provocará un error de compilación que deberá corregirse manualmente.
Arquitectura — cómo están organizadas las capas de la aplicación, a dónde debe ir el nuevo código. Sin este punto, he visto regularmente que el modelo coloca la lógica de negocio directamente en el controlador, porque es el camino más fácil para que funcione; técnicamente el código funciona, pero rompe la estructura de capas aceptada en el proyecto.
Reglas de nomenclatura — convenciones que difieren de las predeterminadas para el lenguaje o framework. El modelo por defecto seguirá los estándares generalmente aceptados de Java o Spring; si tu equipo tiene su propia desviación (por ejemplo, el sufijo Dto en lugar de Request/Response), debes decirlo directamente; no adivinará este acuerdo por sí solo.
Comandos de compilación — los comandos reales de tu proyecto (make build, ./gradlew build), en lugar de suposiciones generales. Sin esto, el modelo a menudo propone un comando genérico como mvn install, incluso si tu proyecto ha estado usando Gradle durante mucho tiempo, y pierdes tiempo en una corrección banal.
Pruebas — qué framework, cómo ejecutarlas, si es necesario escribir pruebas antes o después de una característica. Este es el punto que más influye en si el modelo verifica su propio trabajo antes de decir "listo", o simplemente entrega el código sin verificar.
Restricciones — directorios o archivos que Claude no debe tocar sin permiso explícito. Destacaría esto por separado como el único punto de la lista que no funciona para la calidad del código, sino para la seguridad: sin una prohibición explícita, el modelo puede modificar un archivo de migración que ya se ha aplicado en producción, simplemente porque es la solución técnicamente "más fácil" para la tarea.
Definición de Hecho (Definition of Done) — cuándo se considera completada una tarea: las pruebas pasaron, el linter está limpio, la documentación está actualizada. Sin este punto, el límite entre "el código está escrito" y "la tarea está completada" se vuelve difuso, y es aquí donde más a menudo surge una brecha de expectativas entre lo que produjo el modelo y lo que realmente se necesitaba entregar.
¿Qué nunca se debe escribir en CLAUDE.md?
Este, en mi opinión, es el apartado más importante de todo el artículo, y precisamente donde la mayoría de los competidores se limitan a palabras generales. Explico deliberadamente no solo "qué no escribir", sino qué se rompe específicamente cuando lo escribes, porque "innecesario" suena como un consejo de gusto, pero en realidad detrás de cada punto hay un mecanismo de daño específico.
Grandes fragmentos de código. CLAUDE.md no es el lugar para ejemplos de implementación; haz referencia a un archivo específico, no insertes el contenido. El problema no es solo el volumen: el código insertado se vuelve obsoleto más rápido que la descripción textual. La descripción de la arquitectura "el servicio no accede directamente al repositorio de otro módulo" sigue siendo válida después de un año. Un ejemplo de código insertado que ha sido refactorizado hace mucho tiempo inducirá activamente al modelo a error: se basará en el ejemplo, no en cómo se ve el código realmente hoy.
Documentación de la API. Cambia con más frecuencia que CLAUDE.md y se vuelve obsoleta rápidamente; un enlace a la documentación real vive más que una copia. Aquí el problema es peor que simplemente "se volverá obsoleto": una copia obsoleta de la documentación de la API en CLAUDE.md es activamente perjudicial, porque el modelo confía en ella tanto como en el resto del archivo. Con confianza ofrecerá un endpoint que ya no existe, o un campo que fue renombrado hace dos sprints, y obtendrás no un error de compilación, sino un error lógico silencioso que es fácil de pasar por alto en la revisión.
README. Duplicar README en CLAUDE.md significa doble mantenimiento del mismo contenido; tarde o temprano divergirán. He visto en mi propia experiencia que el equipo actualiza README con cada lanzamiento, porque los nuevos desarrolladores lo miran, pero olvidan la copia en CLAUDE.md, simplemente porque es un archivo que se abre con menos frecuencia a la vista, aunque se lea más a menudo por el modelo.
Changelog. El historial de cambios no afecta a cómo escribir código nuevo hoy; es lastre que consume contexto en cada sesión. Aquí el argumento es puramente económico: cada línea sobre lo que sucedió en febrero compite por la atención del modelo con una línea sobre cómo escribir código ahora, y el modelo no puede ponderar automáticamente "esto es historia" contra "esta es una regla actual"; simplemente lee todo el archivo como contexto equivalente.
Instrucciones de un solo uso. "Hoy actualiza la dependencia X" es una tarea para el chat, no para un archivo que se carga constantemente. Si esta instrucción no se elimina después de su ejecución, continuará cargándose en cada sesión posterior e incluso puede confundir al modelo cuando la tarea ya está completada y el archivo todavía dice "actualiza X"; el modelo intentará hacerlo de nuevo o gastará un paso en aclarar si ya se hizo.
Cosas obvias. "Escribe código limpio", "añade comentarios donde sea necesario" — no le dan al modelo nada que no haga ya por defecto, y simplemente ocupan líneas del límite de 150-200 instrucciones, sobre el que escribí anteriormente. Este es el tipo de lastre más costoso de todos los enumerados: no solo es inútil, sino que desplaza el espacio que podría ocupar una línea con un efecto real, por ejemplo, la misma regla de nomenclatura DTO que el modelo realmente no pudo adivinar por sí solo.
Estructura óptima de CLAUDE.md
Según los resultados de lo que he visto en archivos de producción funcionales y en las recomendaciones de la comunidad, la estructura óptima se ve así:
Resumen del proyecto
Arquitectura
Convenciones de codificación
Estructura de directorios
Comandos
Pruebas
Seguridad
Definición de Hecho
Comportamiento del agente
Referencias útiles
El orden aquí no es aleatorio: primero, el contexto en el que el modelo debe entender qué proyecto es en general (overview, architecture), luego, las reglas según las cuales escribir código (conventions, structure), luego, cómo verificar su propio trabajo (commands, testing, security, DoD), y finalmente, instrucciones de comportamiento y referencias a materiales adicionales.
Mejores prácticas para escribir CLAUDE.md
Haz el archivo corto — específicamente. Referencia: hasta 200 líneas para el CLAUDE.md del proyecto, hasta 30 líneas para el ~/.claude/CLAUDE.md personal. Esta no es una cifra arbitraria; los modelos de vanguardia siguen de forma fiable unas 150-200 instrucciones simultáneamente, y el prompt del sistema de Claude Code ya ocupa unas 50 de ellas (HumanLayer, a través de maketocreate.com). Es decir, cada línea adicional en tu archivo es una competencia real por la atención del modelo con otras instrucciones, no un bono gratuito.
Utiliza reglas absolutas. "Intenta usar named exports" es peor que "Usa named exports, no default exports"; el modelo sigue mejor una instrucción clara y unívoca que un deseo suave.
Evita contradicciones — y entiende cómo el sistema resuelve el conflicto si surge. Ya lo escribí arriba, pero lo repito aquí deliberadamente: una instrucción más específica anula una más general. Conocer esta regla significa que puedes colocar conscientemente una excepción en un nivel inferior (por ejemplo, en el CLAUDE.md de un subdirectorio específico), en lugar de intentar mantener una única regla gigante y coherente para todo el proyecto.
Separa las instrucciones generales y locales. Preferencias personales generales (formato de diff favorito, zona horaria) — en el archivo global. Convenciones del equipo — en el del proyecto, bajo git.
Actualiza el archivo regularmente. Un CLAUDE.md que no se ha editado en tres meses en un proyecto en desarrollo activo es casi seguro un archivo con comandos obsoletos.
No guardes el historial del proyecto. "Antes usábamos Redux, ahora hemos pasado a Zustand" — interesante para una persona, inútil para el modelo, que solo necesita el estado actual.
Haz referencia a la documentación en lugar de copiar. Una línea con un enlace vive más que un párrafo copiado que nadie sincronizará manualmente.
Añade los comandos reales del proyecto. No "ejecuta las pruebas", sino literalmente ./gradlew test o npm run test:unit — el modelo no debe adivinar.
La prueba principal para cualquier línea: ¿se puede deducir del código? Si es así, es un candidato a ser eliminado. Precisamente esta lógica la utiliza el /doctor incorporado, y te recomiendo aplicarla conscientemente incluso antes de que la escritura se convierta en un archivo de 300 líneas que habrá que recortar a posteriori.
Ejemplo de CLAUDE.md bueno
# Project overview
API backend para un sistema de reserva de salas. Spring Boot 3.5, Java 21, PostgreSQL.
# Architecture
Arquitectura en capas: controller → service → repository.
DTO para datos de entrada/salida, la entidad no sale de la capa de servicio.
La lógica de negocio solo está en el servicio, los controladores son delgados.
# Coding conventions
- Parámetros con nombre en constructores a través de Lombok @RequiredArgsConstructor
- Excepciones: personalizadas, no comprobadas, heredan de ApiException
- DTO a través de record, no class
- Fechas: solo java.time, nunca java.util.Date
# Directory structure
src/main/java/com/company/booking/
controller/ — Controladores REST, solo delegación al servicio
service/ — Lógica de negocio
repository/ — Spring Data JPA
dto/ — Clases record para la API
entity/ — Entidades JPA
config/ — Configuración de Spring
# Commands
Build: ./gradlew build
Run tests: ./gradlew test
Run integration tests: ./gradlew integrationTest (requiere Docker para Testcontainers)
Local run: ./gradlew bootRun --args='--spring.profiles.active=local'
# Testing
JUnit 5 + Mockito para unitario, Testcontainers + PostgreSQL para integración.
Cada nuevo método de servicio con lógica de negocio: al menos una prueba unitaria.
No simular lo que se puede probar a través de Testcontainers.
# Security
Nunca registrar contraseñas, tokens, datos personales de clientes.
Todos los endpoints bajo /admin/**: solo rol ADMIN, verificación a nivel de @PreAuthorize.
# Definition of Done
- Las pruebas pasaron (./gradlew test)
- No hay nuevas advertencias de Checkstyle
- DTO documentados con Javadoc, si es API pública
# Agent behaviour
Antes de una refactorización importante: primero el plan, sin modificar archivos.
No elimines pruebas existentes sin permiso explícito, incluso si "parecen innecesarias".
# Useful references
Decisiones arquitectónicas: docs/adr/
Descripción del modelo de dominio: docs/domain-model.md
Tenga en cuenta: aquí no hay ningún fragmento de código real, no hay copia de README, no hay changelog. Cada sección proporciona al modelo algo que no podría deducir de forma fiable por sí mismo del código: por eso el archivo funciona.
Ejemplo de CLAUDE.md malo
# Sobre el proyecto
Este es nuestro maravilloso proyecto, que comenzamos a desarrollar en 2023.
Inicialmente usamos Spring Boot 2, luego cambiamos a 3.
En febrero de 2025, reescribimos el módulo de pagos (ver PR #482).
En abril añadimos Kafka, y en junio lo eliminamos porque no funcionó.
# Estilo de código
Escribe código limpio y legible. Sigue las mejores prácticas.
Los comentarios deben ser significativos.
# Ejemplo de controlador
```java
@RestController
@RequestMapping("/api/v1/bookings")
public class BookingController {
// ... 150 líneas de implementación del controlador ...
}
```
# Documentación de la API
GET /api/v1/bookings — devuelve una lista de reservas
Parámetros: page, size, sort
Respuesta: { "content": [...], "totalElements": 42, ... }
[... 40 endpoints más con descripción completa de campos ...]
# Changelog
- v1.2.0: se añadió filtrado por fecha
- v1.1.0: se corrigió un error con las zonas horarias
- v1.0.0: primer lanzamiento
Esta es casi una colección de antipatrones de manual: historia del proyecto en lugar del estado actual, consejos obvios como "escribe código limpio", código de implementación insertado en lugar de un enlace al archivo, copia completa de la documentación de la API que garantizadamente diferirá del código real en el primer sprint, y un changelog que no afecta ninguna decisión sobre código nuevo. Un archivo de este tamaño y contenido consumirá contexto en cada sesión, dando al modelo una señal mínima útil.
CLAUDE.md para Spring Boot
Para proyectos Java/Spring, destacaría en un bloque separado la pila específica del ecosistema:
Maven o Gradle — y los comandos específicos para compilar/probar tu variante, no ambos "por si acaso".
Versión de Spring Boot y los starters clave que se utilizan realmente (web, data-jpa, security, actuator).
Spring AI, si el proyecto trabaja con él — vale la pena mencionar por separado qué proveedor (Ollama, OpenAI, Anthropic) se utiliza por defecto en el perfil de desarrollo.
Docker — comandos para levantar la infraestructura localmente (docker-compose up -d), no solo una mención de que se usa Docker.
PostgreSQL — versión, si se utilizan tipos específicos de Postgres (jsonb, arrays) que pueden no tener un análogo directo en otras bases de datos.
Flyway — regla de numeración de migraciones, si se puede editar una migración ya aplicada (casi siempre — no).
Testcontainers — qué contenedores específicos se utilizan para pruebas de integración, para que Claude no sugiera simular lo que ya se prueba a través de una base de datos real.
CLAUDE.md para monorepositorio
Para un monorepositorio con varios paquetes en un solo repositorio ("root", "frontend/", "backend/", "shared/") funciona precisamente el mecanismo de CLAUDE.md anidados descrito en la sección sobre carga técnica: el archivo raíz lleva lo común a todo el repositorio (convenciones generales, comandos de CI), y cada subdirectorio — su propio CLAUDE.md con lo específico para él.
Consejo práctico: no dupliques en un subdirectorio lo que ya está en el archivo raíz — el CLAUDE.md anidado complementa el raíz, no lo reemplaza por completo. Y recuerda la regla de prioridad: si el archivo raíz dice una cosa, y frontend/CLAUDE.md — otra, específicamente para el código frontend, para trabajar dentro de frontend/ prevalecerá la instrucción más específica.
CLAUDE.md para microservicios
Aquí la tarea es fundamentalmente diferente a la de un monorepositorio. En un monorepositorio, la pregunta es "¿dónde guardar los archivos anidados dentro de un solo repositorio?". En una arquitectura de microservicios, cada servicio vive en su propio repositorio con su propio CLAUDE.md — y la pregunta real no es sobre anidamiento, sino sobre la sincronización de convenciones comunes entre repositorios que no están físicamente vinculados por un solo árbol de directorios.
Dos enfoques prácticos que he visto: el primero — mantener las convenciones comunes (estilo de commits, enfoque de logging, reglas de seguridad comunes) en un repositorio interno separado y conectarlo a través de @import en cada servicio (recuerda — la importación se despliega por completo, así que mantén este archivo común compacto). El segundo — aceptar que una pequeña duplicación de varias líneas clave en cada CLAUDE.md de servicio es más barata que la infraestructura para la sincronización, especialmente si hay pocos servicios y no cambian cada semana.
CLAUDE.md vs AGENTS.md
Parámetro
CLAUDE.md
AGENTS.md
Quién lee
Solo Claude Code
Codex, Cursor, Copilot, Gemini CLI, Windsurf y otros
Quién controla el estándar
Anthropic
Agentic AI Foundation (Linux Foundation)
Modelo de memoria
Multinivel: global / proyecto / anidado + reglas con path-scoping
Más simple: archivo en la raíz, override por profundidad de directorio
Difusión
Específico para Claude Code
Más de 60.000 repositorios públicos a mediados de 2026
El hecho clave que más a menudo se confunde: Claude Code no lee AGENTS.md de forma nativa, y otras herramientas (Cursor, Copilot, Gemini CLI) no leen CLAUDE.md — esto está confirmado por una prueba directa en un repositorio vivo: colocar CLAUDE.md en un proyecto de Cursor, y Cursor lo ignora simplemente (TECHSY). Si tu equipo utiliza más de una herramienta de IA, el enfoque más práctico es mantener AGENTS.md como el archivo base inter-herramientas y CLAUDE.md por separado para lo que es específico para Claude Code (estructura anidada, reglas con path-scoped).
CLAUDE.md vs Reglas de Cursor
Parámetro
CLAUDE.md
Reglas de Cursor
Formato
Uno o varios archivos .md
Archivos .mdc en .cursor/rules/ con YAML frontmatter
Modos de activación
Siempre al entrar en el ámbito (global/proyecto/anidado)
Cuatro modos: Aplicar Siempre, Aplicar Inteligentemente, Aplicar a Archivos Específicos, y el legado .cursorrules
Path-scoping
A través de .claude/rules/ separados con frontmatter de paths:
Integrado en el propio formato a través del campo globs
Prioridad en caso de conflicto
Por profundidad de directorio (lo más específico anula lo más general)
Equipo → Proyecto → Usuario, la fuente anterior gana
Siendo objetivos, el sistema de activación de reglas en Cursor está más estructurado "de fábrica" — cuatro modos explícitos frente a un modelo más simple de Claude Code. Pero la jerarquía más profunda de Claude Code (global/proyecto/anidado + reglas) ofrece más flexibilidad para grandes monorepos. Si tu equipo trabaja exclusivamente en Cursor, no intentaría replicar artificialmente el sistema de Claude Code — simplemente utiliza las capacidades nativas de los archivos .mdc.
CLAUDE.md vs Instrucciones de Codex
Aquí hay que aclarar de inmediato una imprecisión en el propio nombre de la comparación: en OpenAI Codex no existe un formato propio separado "Instrucciones de Codex" — Codex CLI lee el mismo AGENTS.md abierto que utilizan otras herramientas (The Prompt Shelf). Es decir, la comparación "CLAUDE.md vs Codex" en la práctica es el mismo caso que "CLAUDE.md vs AGENTS.md" más arriba, con una diferencia: Codex CLI tiene un comando de diagnóstico útil --print-instructions, que muestra qué contenido de AGENTS.md fusionado se carga realmente en la sesión actual — útil cuando se sospecha que algún archivo se está recortando o omitiendo.
Conclusión práctica: si tu equipo utiliza tanto Claude Code como Codex, prepárate para mantener dos archivos — CLAUDE.md para una herramienta, AGENTS.md para la otra — y saca lo verdaderamente común en un formato que se pueda importar o copiar en ambos sin discrepancias.
Errores comunes de los desarrolladores
La mayoría de los puntos de esta sección no son simplemente "malas prácticas", sino una cadena específica de causa y efecto que he observado tanto en mis propios proyectos como en descripciones de la comunidad. Describo cada uno de manera que no solo se vea "qué está mal", sino qué es lo que causa exactamente a continuación.
Archivo de 1000 líneas. Un error clásico: intentar describir un proyecto de forma exhaustiva en lugar de darle al modelo solo lo que no puede deducir por sí mismo. La consecuencia es directa y ya he explicado el mecanismo anteriormente: el modelo mantiene de forma fiable en su atención aproximadamente 150-200 instrucciones a la vez, y el prompt del sistema de Claude Code ya ocupa unas 50 de ellas. Un archivo de 1000 líneas no es "más contexto sobre el proyecto", es un presupuesto de atención desbordado, donde la regla importante sobre la Definición de Hecho se pierde entre cientos de afirmaciones obvias, y el modelo de hecho comienza a ignorar parte de las instrucciones no por mala intención, sino porque físicamente no puede mantenerlas todas con el mismo peso.
Instrucciones contradictorias. Ocurre especialmente a menudo entre un archivo global y uno de proyecto, cuando los hábitos personales contradicen las convenciones del equipo. La consecuencia aquí no es que "el modelo se confunde" de forma abstracta: dado que rige la regla de especificidad (el proyecto anula lo global), el modelo de hecho siempre ejecutará la regla del proyecto, y su hábito personal del archivo global simplemente será ignorado silenciosamente cada vez. Si no conoce esta regla, parecerá que Claude "olvida" su configuración, cuando en realidad aplica correctamente la prioridad, simplemente usted no se dio cuenta de que la línea global nunca tuvo la oportunidad de funcionar en este proyecto.
Comandos obsoletos. Un archivo que nadie ha actualizado después de pasar de npm a pnpm o de cambiar el pipeline de CI. La consecuencia es concreta: el modelo ejecutará exactamente el comando que está escrito en el archivo, recibirá un error de "comando no encontrado" o un conflicto de archivos de bloqueo, y dedicará un paso a averiguar por sí mismo qué salió mal, en lugar de ejecutar inmediatamente el comando correcto. Es una pequeñez que consume tiempo de forma imperceptible en cada sesión hasta que alguien actualiza una línea.
Falta de arquitectura. Un modelo sin una descripción de las capas de la aplicación tiende a crear nuevos archivos no donde se acepta en el proyecto. La razón es simple: sin una regla explícita, el modelo se orienta por el camino más fácil para una tarea específica, y no por el acuerdo arquitectónico del equipo: técnicamente, el código funcionará, incluso si la lógica de negocio termina directamente en el controlador en lugar de en la capa de servicio, y obtendrá un código técnicamente correcto pero arquitectónicamente incorrecto que deberá ser trasladado a revisión.
Mezcla de documentación e instrucciones. Cuando CLAUDE.md intenta ser al mismo tiempo un README, una guía de API y un archivo de instrucciones, cumple mal las tres funciones a la vez. La razón es la misma que ya expliqué en la sección "qué nunca se debe escribir": la documentación y las guías cambian con una frecuencia diferente a las instrucciones para el modelo, y tarde o temprano divergen de la realidad; solo que aquí la consecuencia es más amplia, ya que el archivo pierde el enfoque para tres audiencias diferentes (nuevos desarrolladores, quienes buscan la API y el propio modelo), sin satisfacer completamente a ninguna de ellas.
Bug documentado: las reglas de nivel de usuario con frontmatter paths: en ~/.claude/rules/ a principios de 2026 no se cargan, incluso si el archivo coincide con el patrón; este es un bug confirmado (issue de GitHub #21858). Consecuencia práctica: si escribió una regla personal con ámbito de ruta a nivel de su perfil y no funciona silenciosamente, parecerá exactamente un error en su patrón glob, y puede pasar horas buscando un error donde en realidad hay un bug en la propia herramienta. Una solución alternativa es trasladar las reglas con ámbito de ruta al nivel del proyecto, no al perfil personal.
Los encabezados de los archivos importados no se reducen automáticamente. Si el archivo principal tiene \# Code conventions, y el archivo importado comienza con su propio \# Heading, el resultado no es un subapartado, sino un hermano del mismo nivel de encabezado. La consecuencia es imperceptible, pero real: la estructura del archivo, que parece lógica en su editor (la importación está supuestamente "anidada" en una sección), en realidad se expande en el modelo como dos encabezados independientes del mismo nivel: esto confunde la jerarquía de importancia de las instrucciones, cuando esperaba que la anidación en sí misma señalara algo al modelo. El issue de GitHub al respecto se cerró como "no planeado", por lo que no se debe esperar una corrección; preste atención a los niveles de encabezado manualmente (HackerNoon).
Los patrones glob que comienzan con { o * deben entrecomillarse en el frontmatter YAML: sin comillas, esto no es una limitación de Claude Code, sino un requisito estándar de la sintaxis YAML que sorprende regularmente a los desarrolladores (Medium, Frontend Master). La consecuencia aquí es la más grave de toda la lista: no es un error de comportamiento silencioso, sino un error de sintaxis de análisis: todo el archivo de reglas puede no cargarse en absoluto, y perderá no una regla, sino todo el conjunto de reglas con ámbito de ruta de ese archivo hasta que encuentre y corrija las comillas.
Preguntas frecuentes
¿Se pueden tener varios CLAUDE.md?
Sí, e incluso diría que para cualquier proyecto más grande que un solo servicio, no es una opción, sino la norma. Yo suelo tener tres niveles en funcionamiento simultáneamente: uno global con configuraciones personales, uno de proyecto bajo git para todo el equipo, y varios anidados en subdirectorios con la especificidad de un módulo concreto. No compiten: cada nivel complementa uno más general según la regla de especificidad que ya he explicado anteriormente: una instrucción más local anula una más general donde se cruzan.
¿Dónde es mejor guardar el archivo?
Aquí sigo una simple división por propósito. Siempre coloco el CLAUDE.md del proyecto en la raíz del repositorio y lo confirmo en git; de lo contrario, todo el equipo trabaja con instrucciones diferentes para el mismo modelo, lo que anula el sentido del archivo. El archivo personal (~/.claude/CLAUDE.md), por el contrario, está fuera del repositorio, porque son mis hábitos de trabajo personales que no deben imponerse a otros miembros del equipo.
¿Cuál es el tamaño óptimo?
La referencia que sigo es hasta 200 líneas para un archivo de proyecto y hasta 30 líneas para uno global personal. No es una cifra arbitraria para marcar una casilla: ya he explicado en la sección sobre mejores prácticas que los modelos mantienen de forma fiable en foco aproximadamente 150-200 instrucciones a la vez, y el prompt del sistema del propio Claude Code ya ocupa unas 50 de ellas. Es decir, superar este límite no es un problema estético, sino una pérdida directa de eficiencia: parte de sus instrucciones simplemente dejarán de funcionar de forma fiable.
¿Se puede usar Markdown?
Sí, este es su formato de archivo nativo, y recomendaría no descuidar la estructura: los encabezados y las listas no solo "se ven bonitos", sino que ayudan a agrupar instrucciones relacionadas en bloques lógicos, lo que facilita la lectura tanto para mí al revisar el archivo como para el modelo al procesar el contexto.
¿Funciona CLAUDE.md en subdirectorios?
Sí, y es aquí donde considero que la memoria del modelo de Claude Code es más fuerte que las alternativas más sencillas. Un CLAUDE.md anidado no se carga inmediatamente al inicio de la sesión, sino bajo demanda: solo cuando Claude accede realmente a los archivos en el subdirectorio correspondiente. Para los monorepos con los que trabajo regularmente, esto significa que las instrucciones específicas para el módulo frontend no ocupan contexto cuando Claude trabaja exclusivamente con código backend.
¿Es necesario guardarlo en Git?
El archivo de proyecto, definitivamente sí, insisto en esto en cada equipo con el que trabajo: si CLAUDE.md no está en git, cada desarrollador acumula su propia versión de instrucciones que diverge gradualmente, y usted pierde el principal valor del archivo: la consistencia. En cambio, los archivos de anulación personales siempre los añado a .gitignore: son específicos de mi entorno de trabajo, no del proyecto.
¿En qué se diferencia de README?
Formulo esta diferencia por la audiencia, no por el formato. README se escribe para una persona que abre el repositorio por primera vez y no sabe nada sobre el proyecto: es un escaparate. CLAUDE.md se escribe para el modelo, que ya conoce los patrones de desarrollo generales y solo necesita aquello en lo que su proyecto se diferencia de las suposiciones por defecto. Cuando intenté alguna vez combinar ambas funciones en un solo archivo, ambas audiencias sufrieron a la vez; escribí sobre esto con más detalle en la sección sobre errores comunes anteriormente.
¿Se puede usar junto con AGENTS.md?
Sí, y en mi práctica esto es más una regla que una excepción: rara vez un equipo hoy en día se basa exclusivamente en una sola herramienta de IA. Claude Code solo lee CLAUDE.md, mientras que Cursor, Copilot o Gemini CLI se orientan principalmente a AGENTS.md. Si su equipo es mixto, yo recomendaría inmediatamente prever el soporte para ambos archivos, en lugar de intentar que una herramienta lea el formato de otra: simplemente no funcionará.
¿Realmente @import reduce el contexto?
No, y esta es precisamente la intuición errónea que yo mismo tuve antes de comprender el mecanismo con más detalle. Las importaciones se cargan completamente al inicio de la sesión: dividir el archivo en varias partes importadas facilita que usted mantenga el código, pero no reduce el volumen que realmente va al modelo. Si el objetivo es precisamente ahorrar contexto, y no la comodidad de edición, solo funcionan las reglas con ámbito de ruta en .claude/rules/, que he analizado en detalle en la sección sobre carga técnica de archivos anteriormente.
¿Qué sucede con CLAUDE.md después de /compact?
El archivo raíz se reinyecta desde el disco; esto lo he comprobado personalmente y el comportamiento es estable. Sin embargo, los CLAUDE.md y las reglas anidadas no se restauran automáticamente después de la compactación: se vuelven a cargar solo cuando Claude accede la próxima vez al subdirectorio o archivo correspondiente. Si espera que una instrucción anidada se "recuerde" durante toda la sesión después de la compactación, esta es una suposición peligrosa: es mejor considerar que se carga solo cuando es necesario.
¿Cuál es la versión mínima de Claude Code necesaria para el recorte /doctor?
v2.1.206 o posterior. Le recomiendo que verifique su versión actual antes de confiar en este comando en la descripción de las mejores prácticas anteriores: en versiones más antiguas, el comando simplemente no existe, y obtendrá un error en lugar de una sugerencia para recortar el archivo.
Conclusiones
Si tuviera que extraer una sola idea de este artículo, elegiría esta: CLAUDE.md no es documentación ni configuración, sino texto que compite cada vez por la atención limitada del modelo con todo lo demás cargado en el contexto. Cada línea adicional no es un seguro gratuito "por si acaso", sino un precio real que el modelo paga en cada sesión.
Mi consejo práctico, con el que abordo cada nuevo CLAUDE.md: no intente escribir el archivo perfecto de inmediato. Comience con lo mínimo básico: stack, comandos, convenciones clave, y agregue una línea cada vez que Claude cometa un error que una regla clara podría haber evitado. Y antes de agregar una nueva línea, aplique la misma prueba que subyace a /doctor: ¿se puede deducir del código? Si es así, no lo escriba, el modelo se las arreglará solo.
