Qué es un archivo CLAUDE.md: qué hace y cómo usarlo

Actualizado: 2026-11-03

Un archivo CLAUDE.md es un archivo de texto plano con instrucciones permanentes para Claude Code, el agente de programación de Anthropic. Claude Code lo lee al principio de cada sesión, por lo que no tienes que repetir tu comando de prueba o las reglas del proyecto cada vez.

Está escrito en markdown y no ejecuta nada por sí mismo, por lo que abrirlo para leerlo es seguro. Editarlo es diferente: el agente actuará según lo que cambies.

Qué contiene

No hay un formato obligatorio. Las líneas más útiles son cosas que el agente no puede deducir leyendo tu código:

Comandos: cómo compilar y probar, para que pueda comprobar su propio trabajo
Reglas que sigue tu proyecto: por ejemplo, dónde deben ubicarse los textos visibles para el usuario
Advertencias: una carpeta que no debe tocar o un error que sigue repitiendo

Uno pequeño se ve así:

# CLAUDE.md

## Comandos
- Test: npm test (ejecuta esto antes de terminar)

## Reglas
- No edites archivos en /generated
- Mantén el texto visible para el usuario en src/i18n

La documentación de memoria de Anthropic sugiere mantenerse por debajo de las 200 líneas, ya que los archivos más largos consumen más atención del agente y se siguen de forma menos fiable.

Dónde se ubica

Archivo	Utilizado para
`CLAUDE.md` en la carpeta principal del proyecto	Instrucciones para el proyecto, normalmente compartidas a través de git
`CLAUDE.md` en una subcarpeta	Instrucciones leídas cuando el agente trabaja en esa carpeta
`~/.claude/CLAUDE.md`	Tus preferencias personales en todos los proyectos
`CLAUDE.local.md`	Tus notas privadas para un proyecto. Manténlo fuera de git

También se cargan los archivos que están en las carpetas superiores a donde inicias Claude Code. Se combinan en lugar de reemplazarse entre sí, por lo que las contradicciones pueden confundir al agente.

Cómo crear uno

En Claude Code, ejecuta /init. Analiza tu proyecto y redacta un archivo con los comandos de compilación y las convenciones que encuentra. Luego añade lo que no pudo descubrir.

No necesitas uno el primer día. Un buen momento para empezar es cuando corriges el mismo error dos veces. Añade una línea y la siguiente sesión ya lo sabrá.

Lo que no puede hacer

Claude Code trata el archivo como una guía, no como una regla estricta, por lo que normalmente sigue una instrucción pero no está obligado a ello. Si algo nunca debe suceder, Anthropic recomienda un gancho (hook), que la herramienta aplica cada vez. Añadir "IMPORTANTE" a una línea rara vez soluciona el problema.

No pongas contraseñas ni claves de API en él. Los archivos de proyecto normalmente se confirman (commit) junto con el código, por lo que cualquiera que pueda ver el proyecto puede leerlos.

CLAUDE.md y AGENTS.md

AGENTS.md realiza una función similar para otras herramientas como Codex, y Claude Code también puede leer uno que ya esté en tu proyecto. Nuestra guía sobre los archivos .md que crean los agentes de programación explica los otros que puedes ver.

Leerlo en tu móvil

Al abrirse en una aplicación de texto plano, el archivo muestra los símbolos brutos # y **. Para leerlo con formato en Android:

Envíalo a tu móvil. Claude Code suele ejecutarse en un ordenador, así que utiliza Google Drive, un archivo adjunto de correo electrónico o un cable USB.
Toca el archivo y elige MD Reader, o usa Abrir archivo en la aplicación.

Disponible en Google Play

Los encabezados, las tablas y los bloques de código aparecen con formato, y Índice te permite saltar entre secciones. Las etiquetas como <example>, que son comunes en los archivos de instrucciones, se muestran tal como están escritas en lugar de desaparecer. Para Drive, consulta cómo abrir archivos .md desde Google Drive.

MD Reader no se conecta a Claude Code ni se sincroniza con tu ordenador, por lo que lo que estás leyendo es una copia. Vuelve a enviarlo después de que cambie. Puedes tocar Editar y modificar la copia, pero Claude Code no verá eso hasta que devuelvas el archivo a tu ordenador.