CLAUDE.md explicado: enséñale tu proyecto a Claude Code una sola vez

Cada sesión nueva de Claude Code empieza con la cabeza vacía. Le dices que use pnpm, no npm. Le dices dónde están las pruebas. Le dices que no toque la carpeta generada. Mañana le vuelves a decir todo eso.

Es un archivo de texto plano en Markdown. Claude Code lo lee al inicio de cada sesión, así que lo que contiene ya se sabe antes de tu primer prompt. Esta guía te muestra dónde va el archivo, cómo escribir uno que Claude siga y qué dejar fuera.

Qué es CLAUDE.md y qué no es

Cada sesión de Claude Code comienza con una ventana de contexto nueva. Dos mecanismos llevan el conocimiento de una sesión a la siguiente:

Ambos se cargan como contexto. Esa palabra importa: Claude lee CLAUDE.md e intenta seguirlo, pero no es una configuración que se imponga por la fuerza. Una línea vaga o contradictoria puede ignorarse. Volvemos a eso en la sección de solución de problemas, porque define cómo debes escribir el archivo.

Dónde va el archivo

Hay cuatro lugares y se apilan. Claude los carga del alcance más amplio al más específico, así que lo que está más cerca de tu proyecto se lee al final.

Los dos que usarás son el archivo de proyecto y el de usuario.

• Archivo de proyecto. Pon CLAUDE.md en la raíz de tu proyecto, o en una carpeta .claude en la raíz. Súbelo al repositorio, para que todos los que trabajan en el proyecto reciban las mismas instrucciones. Escribe lo que es cierto para cualquiera: comandos de compilación, convenciones, estructura del proyecto.
• Archivo de usuario. ~/.claude/CLAUDE.md te acompaña a todos los proyectos. Úsalo para hábitos personales, como la forma en que prefieres que se redacten las explicaciones.
• Archivo local. CLAUDE.local.md es para notas tuyas y específicas de un proyecto, como la URL de un entorno de pruebas. Agrégalo a tu .gitignore para que no se suba.

Claude también busca en la carpeta desde la que lo abriste y en todas las carpetas superiores. Si empiezas en foo/bar/, carga foo/bar/CLAUDE.md y foo/CLAUDE.md. Los archivos de carpetas más abajo se cargan después, bajo demanda, la primera vez que Claude lee o edita un archivo de esa subcarpeta.

Empieza con /init

No tienes que escribir la primera versión a mano. Dentro de una sesión, ejecuta:

> /initAnalizando tu código base...Se creó CLAUDE.md con los comandos de compilación, las instrucciones de pruebas y las convenciones que encontró.

Claude Code lee tu proyecto y escribe un CLAUDE.md con los comandos de compilación y pruebas y las convenciones que descubre. Si ya existe un CLAUDE.md, /init sugiere mejoras en lugar de sobrescribirlo. Toma el resultado como un primer borrador. Tu trabajo es agregar lo que Claude no pudo averiguar por su cuenta.

Para confirmar que el archivo se cargó, ejecuta /context en una sesión y busca en Memory files.

Qué debe ir en el archivo

Una buena prueba, antes de escribir cualquier línea, tiene dos preguntas:

Si las dos respuestas son sí, deja la línea fuera. Lo que queda es información que nunca estuvo en el código, o que cuesta tiempo real volver a descubrir:

Agrega una línea cuando Claude cometa el mismo error por segunda vez, cuando una revisión de código detecte algo que debió saber, o cuando escribas la misma corrección que escribiste la sesión pasada. Esa es la señal de que el dato pertenece al archivo.

Un ejemplo que vale la pena copiar

Aquí tienes un archivo de proyecto corto. Fíjate en que cada línea es algo que podrías verificar, y en lo poco que describe la arquitectura.

# Project notes

## Commands
- Install: pnpm install (never npm or yarn)
- Dev server: pnpm dev (port 3000)
- Tests: pnpm test -- --run, run before every commit
- Typecheck: pnpm typecheck, must pass before a pull request

## Conventions
- 2-space indentation, double quotes
- API handlers live in src/api/handlers/
- Do not edit anything in src/gen/, it is generated by pnpm codegen

## Gotchas
- Integration tests need a local Redis: docker compose up redis
- Dates are stored in UTC, formatted only in the UI layer

Son 15 líneas, y cada una se gana su lugar.

Cómo escribir líneas que Claude sí siga

Como CLAUDE.md es contexto y no configuración, la forma de redactar una línea decide si se sigue. Escribe instrucciones lo bastante concretas como para poder verificarlas.

Luego mantén el archivo en forma:

• Corto. Apunta a menos de 200 líneas por archivo. Los archivos más largos gastan más contexto y Claude los sigue con menos confiabilidad.
• Ordenado. Agrupa las líneas relacionadas bajo encabezados y viñetas de Markdown. Claude sigue mejor la estructura que los párrafos densos.
• Coherente. Si dos líneas se contradicen, Claude puede elegir una al azar. Lee tus archivos de vez en cuando, incluidos los de las subcarpetas, y borra lo que esté desactualizado.

Para que Claude revise tus archivos de instrucciones en busca de líneas desactualizadas o en conflicto, ejecuta /doctor prompt-audit. Informa los hallazgos y propone ediciones, y no cambia nada hasta que se lo pidas. Requiere Claude Code 2.1.283 o posterior.

Importar otros archivos

CLAUDE.md puede traer otros archivos con una @ antes de la ruta. El archivo importado se carga junto con el CLAUDE.md que lo menciona.

See @README for the project overview and @package.json for the npm commands.

# Additional instructions
- git workflow: @docs/git-instructions.md

Las rutas relativas se resuelven desde el archivo que contiene la importación. Las importaciones pueden importar otros archivos, hasta cuatro niveles de profundidad. La @ solo se lee fuera de los fragmentos de código, así que envuelve una ruta entre acentos graves si quieres mencionarla sin importarla.

Las importaciones sirven para organizar, pero no reducen el contexto: los archivos importados se cargan completos. Para instrucciones personales que quieres en varias copias del mismo repositorio, importa un archivo de tu carpeta personal, como @~/.claude/my-project-instructions.md. La primera vez que un proyecto importa un archivo de fuera del directorio de trabajo, Claude Code te pide aprobación.

Cuando un archivo se hace demasiado largo

En algún momento el archivo crece más de lo que necesita cada sesión. Tienes cuatro herramientas, cada una para un trabajo distinto.

Reglas con alcance para ciertos archivos

Pon un archivo Markdown por tema en .claude/rules/, como testing.md o api-design.md. Para que una regla aplique solo a ciertos archivos, agrega un campo paths al inicio:

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input
- Use the standard error response format

Una regla sin paths se carga en cada sesión. Una con alcance se carga cuando Claude lee o edita un archivo que coincide, lo que mantiene las instrucciones fuera del camino el resto del tiempo.

Si un bloque de CLAUDE.md es un procedimiento de varios pasos, como preparar un lanzamiento, mejor pásalo a una habilidad. Las habilidades se cargan solo cuando se usan.

Memoria automática: las notas que Claude guarda para sí mismo

Además del archivo que escribes tú, Claude Code puede guardar notas por su cuenta. La memoria automática viene activada de forma predeterminada en las sesiones locales. Mientras trabaja, Claude guarda cuatro tipos de notas: sobre ti (rol y preferencias), retroalimentación (correcciones y enfoques que confirmaste), el proyecto (decisiones y fechas límite que no se ven en el código) y referencias (dónde encontrar cosas fuera del proyecto).

No guarda lo que puede leer del código ni lo que ya dice tu CLAUDE.md. Verás mensajes como "Saved 2 memories" en la sesión. Las notas son Markdown plano en ~/.claude/projects/, y las primeras 200 líneas o 25 KB del archivo índice se cargan al inicio de cada sesión.

Ejecuta /memory para ver todos los archivos de instrucciones y la carpeta de memoria automática, abrir cualquiera en tu editor y activar o desactivar la memoria automática. Si le dices a Claude "usa siempre pnpm, no npm", lo guarda en la memoria automática. Para que vaya a CLAUDE.md, dilo: "agrega esto a CLAUDE.md".

Dentro de Claude Tutorial

Escribir lo que de otro modo repetirías

Convertir la misma corrección en una instrucción permanente es un hábito que rinde en cualquier tipo de trabajo con Claude, no solo en el código, y es uno que la app enseña paso a paso.

Muy pronto

Descárgalo en elApp Store

DISPONIBLE ENGoogle Play

Cuando Claude no lo sigue

Revisa estos puntos en orden. Resuelven la mayoría de los casos.

Vale la pena conocer dos casos más. Después de un /compact, el CLAUDE.md de la raíz de tu proyecto se vuelve a leer del disco, así que sobrevive. Una instrucción que diste solo en la conversación no sobrevive, así que pásala al archivo. Y cuando un CLAUDE.md de una subcarpeta es muy largo (más de unos 40,000 caracteres en una ventana de contexto más pequeña), Claude recibe solo el inicio, así que mantenlos cortos.

Preguntas frecuentes

¿Dónde pongo CLAUDE.md?

En la raíz de tu proyecto (./CLAUDE.md) o en ./.claude/CLAUDE.md. Pon las preferencias personales para todos los proyectos en ~/.claude/CLAUDE.md. Usa ./CLAUDE.local.md, agregado a .gitignore, para notas privadas de un solo proyecto.

¿Qué tan largo debe ser un CLAUDE.md?

Apunta a menos de 200 líneas. Si te pasas, Claude Code muestra una advertencia al iniciar y en /status. Mueve las partes de un área a reglas con alcance y recorta lo que Claude puede leer del código.

¿CLAUDE.md es lo mismo que un mensaje del sistema?

No. CLAUDE.md se entrega como un mensaje posterior al mensaje del sistema. Claude intenta seguirlo, pero no hay garantía de cumplimiento estricto. Para instrucciones que deben cumplirse siempre, usa un hook o una regla de permisos.

¿Debo subir CLAUDE.md a git?

Sí para el archivo de proyecto, para que todo el equipo lo comparta y mejore con cada corrección. No para CLAUDE.local.md, que es personal.

¿Claude lee el CLAUDE.md de las subcarpetas?

Sí, bajo demanda. Carga el archivo de una subcarpeta la primera vez que Claude lee o edita un archivo de esa carpeta, y muestra una línea Loaded con la ruta.

¿Cuál es la diferencia entre CLAUDE.md y una habilidad?

CLAUDE.md es para datos necesarios en cada sesión. Una habilidad es un procedimiento o guía que se carga solo cuando se invoca o es relevante, así que no ocupa espacio el resto del tiempo.

Tu lista de verificación de CLAUDE.md

Sigue leyendo

• Claude Code para principiantes: instala, inicia sesión y haz tu primera tarea si todavía no has iniciado una sesión.
• Buenas prácticas de Claude Code: hábitos que dan mejores resultados para prompts, verificaciones y manejo del contexto.
• Modos de permisos de Claude Code y modo plan, explicados para decidir qué puede hacer Claude sin preguntar.
• Proyectos de Claude: contexto que permanece para la misma idea en la app de Claude: instrucciones permanentes guardadas con un proyecto.