CLAUDE.md Mejores Prácticas: cómo configurar Claude correctamente

En resumen:

• 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 se inserta en el contexto como texto, por lo que es una sugerencia para el modelo, no una regla estricta.
• El principal error técnico es dividir el archivo en @imports para ahorrar contexto. Las importaciones se cargan completas de inmediato. Solo las reglas con ámbito de ruta (path-scoped rules) en .claude/rules/ realmente ahorran contexto.
• La referencia de tamaño es de hasta 200 líneas para el CLAUDE.md del proyecto. No es un límite estricto: la densidad de instrucciones útiles es más importante que el número de líneas.
• Desde la versión 2.1.277, Claude Code también lee AGENTS.md, pero por defecto solo cuando no hay CLAUDE.md en el proyecto. Cursor tiene su propio sistema .cursor/rules/.
• Cuando CLAUDE.md se queda corto: reglas, habilidades (skills), ganchos (hooks) y permisos: qué poner dónde.
• El artículo incluye un ejemplo de trabajo para Spring Boot, errores comunes y una forma sencilla de comprobar si un archivo afecta realmente al resultado.

Contenido

• ¿Qué es CLAUDE.md y para qué sirve?
• ¿Cómo utiliza Claude CLAUDE.md?
• ¿Cómo carga técnicamente Claude Code CLAUDE.md: imports vs. rules vs. compaction
• ¿Qué debe incluir obligatoriamente CLAUDE.md?
• ¿Qué nunca debes escribir en CLAUDE.md?
• Estructura óptima de CLAUDE.md
• Mejores prácticas para escribir CLAUDE.md
• CLAUDE.md vs. rules vs. skills vs. hooks: qué poner dónde
• Ejemplo de un buen CLAUDE.md
• Ejemplo de un mal CLAUDE.md
• CLAUDE.md para Spring Boot
• CLAUDE.md para monorepos
• CLAUDE.md para microservicios
• CLAUDE.md vs. AGENTS.md
• CLAUDE.md vs. Cursor Rules
• CLAUDE.md vs. Codex Instructions
• Errores comunes de los desarrolladores
• Preguntas frecuentes
• Conclusiones

¿Qué es CLAUDE.md y para qué sirve?

CLAUDE.md es un archivo markdown normal que Claude Code carga automáticamente al inicio de cada sesión, proporcionando al modelo lo que se puede llamar una memoria persistente del proyecto: comandos, arquitectura, convenciones, todo aquello que el modelo no puede deducir del código en sí (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 evita que Claude olvide.

Esto no es una hipérbole. Personalmente me he encontrado 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 la vitrina 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 tu proyecto de las suposiciones predeterminadas.

Diferencia con AGENTS.md: AGENTS.md es un estándar abierto multiplataforma que leen Codex, Cursor, Copilot, Gemini CLI, OpenCode y otros. Claude Code, desde la versión 2.1.277, también lo lee, pero por defecto solo como una opción de respaldo, cuando no hay CLAUDE.md en el proyecto. Detalles y modos en la sección de comparació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, incompatible con CLAUDE.md: si pones CLAUDE.md en un proyecto de Cursor, Cursor simplemente lo ignorará.

¿Cómo utiliza Claude CLAUDE.md?

Claude Code busca CLAUDE.md según la jerarquía de directorios, y el comportamiento depende del nivel:

• Global (~/.claude/CLAUDE.md) — configuración personal para todos los proyectos en tu máquina.
• Raíz del proyecto (./CLAUDE.md o ./.claude/CLAUDE.md) — el archivo principal, se commitea en git y funciona para todo el equipo.
• Local (./CLAUDE.local.md) — tus notas personales para este proyecto (URL local, cuentas de prueba). Añádelo a .gitignore.
• CLAUDE.md anidados en subdirectorios — se cargan solo cuando Claude lee archivos de ese subdirectorio. Un monorepo con 50 módulos no infla el contexto con lo que no es necesario en ese momento.
• Managed policy — un archivo que el administrador distribuye a todas las máquinas de la organización. No es relevante para un desarrollador individual, pero en empresas es importante saber que este nivel existe.

Independientemente de estos archivos, funciona la memoria automática (auto memory) — notas que Claude mantiene por sí mismo en ~/.claude/projects/<proyecto>/memory/MEMORY.md. Al inicio se cargan las primeras 200 líneas o 25 KB. Puedes verlas y editarlas a través de /memory. Tú escribes CLAUDE.md, Claude escribe MEMORY.md.

Todos los archivos encontrados entran juntos en el contexto. Cuando las instrucciones se contradicen, generalmente prevalece la más específica (el proyecto es más fuerte que el archivo global), pero esto no está garantizado: el modelo ve ambas versiones. Por lo tanto, la regla es simple: no dejes contradicciones, y marca explícitamente la excepción en el nivel inferior.

¿Cómo carga técnicamente Claude Code CLAUDE.md: imports vs. rules vs. compaction

Casi todas las guías dicen "mantén el archivo corto", pero no explican qué técnicas de reducción funcionan realmente y cuáles solo lo parecen. La diferencia radica en el mecanismo de carga.

@imports se cargan inmediatamente y en su totalidad. Divide un CLAUDE.md de 500 líneas en cinco importaciones de 100 líneas cada una, y obtendrás archivos más manejables, pero la misma cantidad de contexto. La importación se expande al inicio de la sesión, como si el contenido se hubiera insertado directamente. La anidación es de hasta 5 niveles. Dentro de `código` y bloques de código, @ruta no se procesa, por lo que puedes mencionar la ruta sin importar el archivo.

Las reglas en .claude/rules/*.md se comportan de manera diferente:

⚠️ Las reglas personales en ~/.claude/rules/ con paths: no funcionaron durante mucho tiempo (issue #21858, cerrado en marzo de 2026), y los informes posteriores muestran que el problema reaparece. Las reglas con ámbito de ruta (path-scoped rules) funcionan de manera fiable a nivel de proyecto. Después de los cambios, verifica a través de /memory que el archivo se cargó correctamente.

Qué sobrevive a /compact:

Conclusión práctica: una instrucción dada solo en el chat puede desaparecer después de la compactación. Si una regla es importante, su lugar está en un archivo.

Los comentarios HTML no cuestan contexto. Los comentarios de bloque <!-- ... --> se eliminan antes de la carga. Útil para notas a colegas: "por qué está esta regla aquí".

Recorte integrado. Desde la v2.1.206, el comando /doctor (alias /checkup) analiza el CLAUDE.md commiteado y sugiere eliminar lo que el modelo puede deducir del código: estructura de carpetas, lista de dependencias, resumen general. Deja los obstáculos, las justificaciones de las decisiones y las convenciones no estándar. También encuentra duplicados entre CLAUDE.md y CLAUDE.local.md y sugiere mover parte de las instrucciones a skills o CLAUDE.md anidados. El criterio "¿se puede deducir esto del código?" es la mejor prueba para cualquier línea.

¿Qué debe incluir obligatoriamente CLAUDE.md?

El mismo criterio: solo aquello que el modelo no deducirá con certeza del código. Estas son las categorías donde, sin una instrucción explícita, a menudo adivina incorrectamente:

• Pila y versiones — especialmente en el período de transición (parte de los módulos en Java 17, parte en 21). De lo contrario, el modelo aplicará la API de una versión más reciente y la compilación fallará.
• Arquitectura — hacia dónde va el nuevo código. Sin esto, la lógica de negocio termina regularmente en el controlador: funciona, pero rompe las capas.
• Reglas de nomenclatura no estándar — por ejemplo, el sufijo Dto en lugar de Request/Response. El modelo conoce los valores predeterminados de Java, pero no tus acuerdos.
• Comandos de compilación — literalmente ./gradlew build, no "compila el proyecto". De lo contrario, obtendrás mvn install en un proyecto Gradle.
• Pruebas — framework, comando de ejecución, cuándo escribir pruebas. De esto depende si el modelo verifica su propio trabajo antes de decir "listo".
• Restricciones — qué no tocar sin permiso (por ejemplo, migraciones ya aplicadas). Importante: una prohibición textual es una solicitud, no un candado. Para lo crítico, usa permisos y hooks (ver abajo).
• Definición de Hecho (Definition of Done) — las pruebas pasaron, el linter está limpio, la documentación está actualizada. Sin esto, "el código está escrito" y "la tarea está completada" son cosas diferentes.

¿Qué nunca debes escribir en CLAUDE.md?

Detrás de cada punto hay un mecanismo específico de daño, no una cuestión de "gusto":

• Secretos, claves, contraseñas. CLAUDE.md se commitea en git y entra en el contexto de cada sesión. Las claves deben estar en variables de entorno o en un gestor de secretos, y el acceso a .env es mejor prohibirlo a través de permisos.
• Grandes fragmentos de código. Un ejemplo insertado se vuelve obsoleto más rápido que una descripción. Después de una refactorización, el modelo se basará en el ejemplo antiguo, no en el código real. Haz referencia al archivo.
• Documentación de API. Una copia obsoleta es peor que la ausencia: el modelo ofrecerá con confianza un endpoint que ya no existe. El resultado no será un error de compilación, sino un error lógico silencioso.
• Copia de README. README se actualiza en los lanzamientos porque la gente lo mira. La copia en CLAUDE.md se olvida y los archivos divergen.
• Changelog e historial de decisiones. "Antes era Redux, ahora es Zustand": el modelo no distingue el historial de la regla actual, lee todo como si tuviera el mismo valor.
• Instrucciones de un solo uso. "Actualiza la dependencia X" es una tarea para el chat. Olvidada en el archivo, obligará al modelo a repetir o verificar algo ya hecho.
• Cosas obvias. "Escribe código limpio", "añade comentarios" — el modelo ya lo hace. Estas líneas solo diluyen aquellas que realmente afectan el resultado.

Estructura óptima de CLAUDE.md

Según lo que he visto en archivos de producción funcionales y en las recomendaciones de la comunidad, la estructura óptima se ve así:

1. Resumen del proyecto
2. Arquitectura
3. Convenciones de codificación
4. Estructura de directorios
5. Comandos
6. Pruebas
7. Seguridad
8. Definición de Hecho
9. Comportamiento del agente
10. Referencias útiles

El orden aquí no es casual: primero, el contexto en el que el modelo debe entender qué tipo de proyecto es (overview, architecture), luego, las reglas para escribir código (conventions, structure), luego, cómo verificar su propio trabajo (commands, testing, security, DoD), y finalmente, las instrucciones de comportamiento y referencias a materiales adicionales.

Mejores prácticas para escribir CLAUDE.md

Mantén el archivo corto. La referencia práctica de Anthropic es de hasta 200 líneas por CLAUDE.md, para el ~/.claude/CLAUDE.md personal, unas pocas docenas. No es un límite estricto: cada línea consume contexto en cada sesión, y cuanto más largo es el archivo, menos consistentemente Claude lo ejecuta. La densidad es más importante que la longitud.

Escribe de forma inequívoca. "Usa exportaciones nombradas, no por defecto" es mejor que "intenta usar exportaciones nombradas".

No dejes contradicciones. La excepción para un módulo debe estar en su CLAUDE.md anidado o en una regla con paths:, no en una segunda regla junto a la primera.

Separa los niveles. Las preferencias personales van en ~/.claude/CLAUDE.md, lo personal para el proyecto va en CLAUDE.local.md, las convenciones del equipo van en el CLAUDE.md del proyecto bajo git.

Mantén solo el estado actual. Sin historial, sin comandos obsoletos. Un archivo que no se ha editado en tres meses en un proyecto activo, casi con certeza miente.

Haz referencia, no copies. Una línea con una referencia vive más que un párrafo copiado.

Añade una regla después de un error repetido. No intentes prever todo. El modelo puso la lógica en el controlador dos veces: es un candidato para CLAUDE.md. Un problema hipotético, no.

Prueba principal: ¿se puede deducir esto del código? Si es así, elimínalo. El comando /doctor utiliza esta misma lógica; aplícala antes de que el archivo crezca a 300 líneas.

Cómo verificar que CLAUDE.md realmente funciona

1. Toma 3-5 tareas típicas del proyecto (nuevo endpoint, corrección de error, prueba).
2. Ejecútalas con CLAUDE.md y sin él (renombra temporalmente el archivo).
3. Compara cuántas correcciones tuviste que hacer manualmente y si se respetaron la arquitectura y las convenciones.
4. Las reglas que no cambiaron el resultado, a eliminar.
5. Ejecuta periódicamente /doctor prompt-audit — encuentra contradicciones entre los archivos de instrucciones.

💡 Esto no es una precaución excesiva. Un estudio de ETH Zurich (138 repositorios, 5.694 PR) demostró que los archivos de instrucciones escritos como README empeoran ligeramente el resultado del agente y aumentan el consumo de tokens. Un archivo largo ≠ un archivo útil.

CLAUDE.md vs. rules vs. skills vs. hooks: qué poner dónde

Cuando CLAUDE.md se expande, el problema generalmente no es que sea largo. Simplemente contiene cosas que deberían estar en otro mecanismo:

Diferencia clave: CLAUDE.md, rules y skills son texto que el modelo puede violar. Hooks y permissions son deterministas: se activan independientemente de lo que el modelo "decida". Por lo tanto, la regla "nunca hacer push a main" en CLAUDE.md es un deseo, mientras que deny en permissions es una garantía:

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(git push:*)"
    ]
  }
}

Una regla simple para elegir: si violar la instrucción es una inconveniencia, escríbelo en CLAUDE.md. Si violar la instrucción es un incidente, usa permissions o un hook.

Ejemplo de CLAUDE.md bueno

# Resumen del proyecto
API backend para un sistema de reserva de salas. Spring Boot 4, Java 21, PostgreSQL 17.

# Arquitectura
Arquitectura en capas: controller → service → repository.
La entidad no sale de la capa de servicio; hacia afuera, solo DTOs.
La lógica de negocio reside únicamente en el servicio; los controladores son livianos.

# Convenciones de codificación
- Inyección a través de constructor (@RequiredArgsConstructor), sin @Autowired en campos.
- Excepciones: personalizadas y unchecked, heredan de ApiException.
- DTOs: solo records.
- Fechas: solo java.time, nunca java.util.Date.
- JSON: Jackson 3 (paquete tools.jackson), no com.fasterxml.jackson.

# Comandos
Build: ./gradlew build
Pruebas unitarias: ./gradlew test
Pruebas de integración: ./gradlew integrationTest (requiere Docker para Testcontainers)
Ejecución local: ./gradlew bootRun --args='--spring.profiles.active=local'

# Pruebas
JUnit 5 + Mockito para unitarias, Testcontainers + PostgreSQL para integración.
Cada nuevo método de servicio con lógica de negocio debe tener al menos una prueba unitaria.
No mockear lo que se puede probar a través de Testcontainers.

# Seguridad
Nunca registrar contraseñas, tokens o datos personales de clientes.
Endpoints /admin/**: solo rol ADMIN a través de @PreAuthorize.

# Definición de Hecho (Definition of Done)
- ./gradlew build se completa sin nuevas advertencias de Checkstyle.
- Los DTOs públicos tienen Javadoc.

# Comportamiento del agente
Antes de una refactorización importante: primero el plan, sin modificar archivos.
No eliminar pruebas existentes sin permiso explícito.

# Referencias
Decisiones arquitectónicas: docs/adr/
Modelo de dominio: docs/domain-model.md

<!-- Las reglas para migraciones se encuentran en .claude/rules/migrations.md -->

Aquí no hay código, ni copias de README o changelog, solo aquello que el modelo no deducirá por sí mismo. Presta atención a dos cosas. No hay una sección de *Estructura de directorios*: Claude ve la estructura estándar de un proyecto Spring a partir del código, y son precisamente estos bloques de /doctor los que sugiere eliminar primero. Y la línea sobre Jackson 3 es un ejemplo de instrucción ideal: en Spring Boot 4, el paquete cambió, y sin una pista, el modelo importará por defecto el antiguo com.fasterxml.

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 la 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 bug con zonas horarias
- v1.0.0: primer lanzamiento

Un conjunto completo de antipatrones: historia en lugar del estado actual, consejos vacíos como "escribe código limpio", código insertado en lugar de una referencia, copia de la documentación de la API que diferirá del código en el primer sprint, y un changelog que no afecta ninguna decisión. Un archivo así consume contexto de cada sesión y casi no aporta nada. Compara: "escribe código limpio" → cero efecto; "la entidad no sale de la capa de servicio" → un comportamiento concreto fácil de verificar.

CLAUDE.md para Spring Boot

Para proyectos Java/Spring, vale la pena fijar específicamente lo que es particular de su ecosistema:

• Maven o Gradle: y los comandos exactos de tu variante, no ambos "por si acaso".
• Versión de Spring Boot y starters clave. Especialmente importante ahora: el soporte gratuito de Boot 3.5 finalizó en junio de 2026, y muchos proyectos están en proceso de transición a Boot 4 (Jackson 3, Spring Framework 7). El modelo debe saber en qué versión te encuentras *actualmente*.
• Spring AI: versión (1.x y 2.x difieren significativamente, 2.0 requiere Boot 4) y el proveedor por defecto en el perfil dev (Ollama, OpenAI, Anthropic).
• Docker: comando para levantar la infraestructura (docker compose up -d), no solo "usamos Docker".
• PostgreSQL: versión y tipos específicos (jsonb, arrays, pgvector) que no tienen un análogo directo en otras bases de datos.
• Flyway: numeración de migraciones y prohibición de editar las aplicadas.
• Testcontainers: qué contenedores se utilizan, para que Claude no sugiera mockear lo que se prueba en una base de datos real.

Las reglas para migraciones son un candidato ideal para una regla con ámbito de ruta (path-scoped rule): solo son necesarias cuando Claude accede a la carpeta de migraciones.

# .claude/rules/migrations.md
---
paths:
  - "src/main/resources/db/migration/**"
---
- Nueva migración: nuevo archivo V{N}__descripción_corta.sql, N = último número + 1
- Nunca edites migraciones ya existentes: ¡se han aplicado en producción!
- Para cambios de esquema: nueva migración con ALTER, no edición de la antigua.

Y si un error aquí cuesta un incidente, añade también la prohibición de editar mediante permisos (ver dónde poner qué).

CLAUDE.md para monorepos

Para un monorepo (frontend/, backend/, shared/) funciona el mecanismo de CLAUDE.md anidados: el archivo raíz contiene lo común (convenciones, comandos de CI), y cada subdirectorio solo lo suyo. El archivo anidado *complementa* el raíz, no lo reemplaza, por lo que no dupliques allí lo que ya está arriba.

Dos consejos prácticos:

• Las reglas asociadas a tipos de archivo, no a carpetas (por ejemplo, todos los *.test.ts en cualquier paquete), son más fáciles de mantener como reglas con paths: que dispersas en CLAUDE.md anidados.
• En monorepos grandes, se cargan CLAUDE.md de otros equipos que no necesitas. Puedes excluirlos configurando claudeMdExcludes en .claude/settings.local.json.

CLAUDE.md para microservicios

Aquí la tarea es diferente: cada servicio vive en su propio repositorio, y la cuestión no es la anidación, sino cómo sincronizar las convenciones comunes entre repositorios.

Para 3–5 servicios, elegiría la duplicación: unas pocas líneas son más baratas que la infraestructura. Cuando hay más de una docena de servicios o las convenciones cambian con frecuencia, el plugin. La importación desde la carpeta de inicio es una opción intermedia para reglas personales, pero no para las del equipo.

CLAUDE.md vs AGENTS.md

Durante mucho tiempo, Claude Code fue la excepción y solo leía CLAUDE.md. Desde la versión 2.1.277 (18 de septiembre de 2026), también lee AGENTS.md, pero por defecto solo como opción de respaldo.

⚠️ Importante: si en el directorio de trabajo o en cualquier directorio superior existe CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md, Claude Code por defecto ignora AGENTS.md. No habrá error, simplemente el archivo no entrará en el contexto.

Cuatro modos de "Instrucciones del proyecto"

El modo se cambia con el comando /config → Project instructions:

💡 Este parámetro es personal: en la configuración del proyecto, Claude Code lo ignora, por lo que no se puede commitear. Para que todo el equipo reciba las mismas instrucciones, usa la importación.

Enfoque recomendado para el equipo

Las reglas comunes, en AGENTS.md. En CLAUDE.md, la primera línea es la importación y solo la especificidad de Claude:

# CLAUDE.md
@AGENTS.md

## Solo para Claude Code
- Para cambios en src/billing/, usa el modo plan.
- Antes de commitear, ejecuta ./gradlew build.

La línea @AGENTS.md se commitea junto con el repositorio y funciona para todos, independientemente del modo personal. Si alguien activa claude-md-and-agents-md, AGENTS.md no se duplica.

Cómo verificar qué se cargó

• /memory — muestra los archivos cargados (AGENTS.md se ve allí desde la versión 2.1.280).
• /doctor prompt-audit — encuentra contradicciones entre CLAUDE.md y AGENTS.md.
• Si el elemento Project instructions no está en /config, el soporte para AGENTS.md no está disponible en esta sesión (versión antigua, primera sesión después de una actualización o plugin integrado agents-md desactivado). En ese caso, queda la importación @AGENTS.md.

CLAUDE.md vs Cursor Rules

El sistema de activación en Cursor es más flexible de fábrica: el modo "Apply Intelligently", donde el agente decide por sí mismo según la descripción si la regla es necesaria, es lo más cercano en esencia a los skills en Claude Code, no a las rules. El antiguo archivo .cursorrules está obsoleto; en proyectos nuevos, usa solo .cursor/rules/.

⚠️ Si en un proyecto de Cursor hay un CLAUDE.md grande, Cursor lo carga en cada chat completo. Para equipos mixtos, este es otro argumento para mantener CLAUDE.md corto y lo común en AGENTS.md.

CLAUDE.md vs Codex Instructions

No existe un formato separado de "Codex Instructions": Codex CLI lee el mismo AGENTS.md. Las diferencias están en la mecánica:

• Instrucciones globales: en ~/.codex/AGENTS.md (análogo a ~/.claude/CLAUDE.md).
• AGENTS.override.md: si se encuentra junto a AGENTS.md, Codex lee solo este último. Útil para cambios locales temporales, pero también es una causa frecuente por la que las modificaciones en AGENTS.md "no funcionan".
• Orden: Codex concatena archivos desde la raíz hasta el directorio actual, los más cercanos al trabajo van al final.

La conclusión práctica ha cambiado: antes, para Claude Code y Codex, había que mantener dos archivos separados. Ahora, AGENTS.md es suficiente como única fuente de verdad y un CLAUDE.md corto con @AGENTS.md más la especificidad de Claude (ver arriba). Para verificar en Codex, lo más fácil es añadir un marcador único en AGENTS.md y pedirle al agente que lo repita.

Errores comunes de los desarrolladores

Detrás de cada punto hay una cadena específica de "causa → consecuencia", no una "mala práctica" abstracta.

• Un archivo de 1000 líneas. Intentar describir el proyecto de forma exhaustiva en lugar de proporcionar solo lo que el modelo no deducirá por sí mismo. Cada línea consume contexto en cada sesión, y la regla importante sobre la Definición de Hecho se pierde entre cien afirmaciones obvias. El modelo no la ignora a propósito: simplemente, cuanto más largo es el archivo, menos consistentemente la aplica.
• Instrucciones contradictorias. Lo más frecuente es entre un archivo global y uno del proyecto. El modelo ve ambas versiones simultáneamente y generalmente elige la más específica, pero esto no está garantizado: el comportamiento puede "fluctuar" de una sesión a otra. Parece que Claude "olvida" la configuración, aunque en realidad le han dado dos instrucciones mutuamente excluyentes. Se soluciona con /doctor prompt-audit y una exclusión explícita en un nivel inferior.
• Comandos obsoletos. Cambiaste de npm a pnpm o modificaste la CI, pero no actualizaste el archivo. El modelo ejecutará lo escrito, obtendrá "command not found" y dedicará un paso a aclararlo, en cada sesión, hasta que alguien corrija una línea.
• Falta de arquitectura. Sin una descripción de las capas, el modelo sigue el camino más fácil: el código funcionará, pero la lógica de negocio terminará en el controlador, y tendrás que moverla en la revisión.
• Mezcla de documentación e instrucciones. Un CLAUDE.md que intenta ser un README, una guía de API y un manual de instrucciones a la vez, cumple mal las tres funciones: la documentación cambia con una frecuencia diferente y se desvía de la realidad.
• Tanto CLAUDE.md como AGENTS.md — y la expectativa de que ambos funcionen. Por defecto, Claude Code solo lee CLAUDE.md y omite AGENTS.md silenciosamente. La mitad de las reglas del equipo simplemente no llegan al modelo. Solución: @AGENTS.md como primera línea de CLAUDE.md (ver sección de comparación).
• Prohibiciones solo en texto. "Nunca hagas push a main" en CLAUDE.md es un deseo que el modelo puede incumplir. Para lo crítico, usa permissions.deny o un hook (ver qué poner dónde).
• Reglas importantes solo en el chat. Después de /compact, el historial se comprime y lo dicho en la conversación puede desaparecer. Si repites lo mismo por segunda vez, es una línea para el archivo.
• Reglas personales con ámbito de ruta en ~/.claude/rules/. Las reglas con paths: a nivel de perfil tardaron en cargarse (issue de GitHub #21858, cerrado en marzo de 2026), y los informes posteriores muestran que el problema reaparece. Parece exactamente un error en tu patrón glob: puedes pasar horas buscando en el lugar equivocado. Mantén las reglas con ámbito de ruta a nivel de proyecto y verifica a través de /memory.
• Los encabezados de los archivos importados no se reducen. Si el archivo principal tiene # Code conventions y el importado comienza con su propio # Heading, el modelo obtendrá no un subapartado, sino un encabezado adyacente del mismo nivel. La anidación que ves en el editor no se transmite al modelo; presta atención a los niveles manualmente (HackerNoon).
• Glob sin comillas en YAML-frontmatter. Los patrones que comienzan con * o { deben ir entre comillas; es un requisito de la sintaxis YAML, no de Claude Code. Sin comillas, el frontmatter no se parsea, y puede que no se cargue todo el archivo de reglas, no solo una regla.

Preguntas frecuentes

¿Se puede tener varios CLAUDE.md?

Sí, y para cualquier proyecto más grande que un solo servicio es lo normal. Yo suelo tener tres niveles: global con configuraciones personales, del proyecto bajo git para el equipo y varios anidados en módulos. Se complementan entre sí; lo importante es no dejar contradicciones entre ellos.

¿Dónde es mejor guardar el archivo?

El CLAUDE.md del proyecto, en la raíz del repositorio (o .claude/CLAUDE.md) bajo git. Las configuraciones personales para todos los proyectos, en ~/.claude/CLAUDE.md. Lo personal para un proyecto específico (URLs locales, cuentas de prueba), en CLAUDE.local.md, añadido a .gitignore.

¿Cuál es el tamaño óptimo?

La guía práctica de Anthropic es hasta 200 líneas por archivo; para mi CLAUDE.md global personal, mantengo unas pocas docenas. No es un límite estricto: cada línea consume contexto en cada sesión, y cuanto más largo es el archivo, menos consistentemente Claude lo aplica. Es más importante la densidad de instrucciones útiles que el número de líneas.

¿Se puede usar Markdown?

Sí, es el formato nativo. Los encabezados y las listas agrupan instrucciones relacionadas y facilitan la revisión del archivo. Los comentarios de bloque HTML <!-- --> se eliminan antes de cargarse; son útiles para explicar a los colegas por qué se necesita una regla, sin consumir contexto.

¿Funciona CLAUDE.md en subdirectorios?

Sí. Un CLAUDE.md anidado no se carga al inicio, sino solo cuando Claude lee archivos de ese subdirectorio. En un monorepo, las instrucciones para el frontend no consumen contexto mientras Claude trabaja con el backend.

¿Es necesario guardarlo en Git?

El del proyecto, obligatoriamente: de lo contrario, cada desarrollador acumula su propia versión de las instrucciones, y se pierde el principal valor del archivo: la consistencia. CLAUDE.local.md y las configuraciones personales, por el contrario, van en .gitignore.

¿En qué se diferencia de README?

En la audiencia. README es para una persona que abre el repositorio por primera vez. CLAUDE.md es para el modelo, que ya conoce los patrones generales y solo necesita aquello en lo que tu proyecto se diferencia de las suposiciones predeterminadas. Combinar ambos roles en un solo archivo perjudica a ambos.

¿Claude Code lee el archivo AGENTS.md?

Sí, a partir de la versión 2.1.277 (septiembre de 2026). Por defecto, solo cuando en el proyecto no hay CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md. Para que se carguen ambos, añade @AGENTS.md como primera línea de CLAUDE.md (funciona para todo el equipo) o elige el modo claude-md-and-agents-md en /config → Project instructions (funciona solo para ti).

¿Es cierto que @import reduce el contexto?

No. Las importaciones se expanden completamente al inicio de la sesión; dividir en archivos facilita el mantenimiento, pero no reduce el volumen de contexto. Solo ahorran las reglas en .claude/rules/ con paths:.

¿Qué pasa con CLAUDE.md después de /compact?

El CLAUDE.md raíz, las reglas sin paths: y la memoria automática se recargan. Los CLAUDE.md anidados y las reglas con paths: solo se restauran cuando Claude vuelve a leer los archivos correspondientes. Las instrucciones dadas solo en el chat, después de la compactación, pueden desaparecer.

¿En qué se diferencia CLAUDE.md de MEMORY.md?

CLAUDE.md lo escribes tú: son instrucciones. MEMORY.md (memoria automática) lo lleva el propio Claude: son sus notas de sesiones anteriores; al inicio se cargan las primeras 200 líneas o 25 KB. Puedes ver y corregir ambos a través de /memory.

¿Cuál es la versión mínima de Claude Code necesaria para el "trimming" con /doctor?

v2.1.206 o posterior. En versiones anteriores, el comando no ofrece recortar CLAUDE.md. Alias: /checkup.

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 sesión por la atención del modelo con todo lo demás en el contexto. Y es un consejo para el modelo, no una garantía.

Esto es lo que recomiendo basándome en mi propia experiencia con Claude Code:

• Empieza con lo mínimo. Stack, comandos, arquitectura, algunas convenciones no estándar: 30-50 líneas. No intentes escribir el archivo perfecto de inmediato.
• Añade una línea solo después de un error recurrente. Claude hizo lo mismo mal dos veces: esa es una regla para el archivo. Un problema hipotético, no.
• Antes de cada nueva línea, pregúntate: ¿se puede deducir del código? Si es así, no la escribas. Ejecuta /doctor una vez al mes.
• Mueve lo específico a las reglas con paths:, los procedimientos a las skills. CLAUDE.md solo debe contener lo necesario en cada sesión.
• Cierra lo crítico con permissions y hooks, no con texto. El acceso a .env, el push a main, la producción, no son cosas en las que valga la pena confiar en un deseo en markdown.
• Si en el equipo hay varias herramientas de IA, una única fuente de verdad. Lo común en AGENTS.md, en CLAUDE.md: @AGENTS.md y la especificidad de Claude.
• Verifica, no creas. Ejecuta 3-5 tareas típicas con y sin el archivo. Elimina las reglas que no cambiaron nada.