Workbranch › Guías

Cómo escribir un archivo CLAUDE.md para Claude Code

Cada sesión de Claude Code empieza con el contexto vacío, así que acabas repitiendo los mismos comandos de compilación y las mismas normas de la casa. Un archivo CLAUDE.md lo resuelve. Esta guía explica dónde va, qué debe contener y cómo comprobar que Claude de verdad lo está leyendo.

Actualizado 30 de octubre de 2026

Las ubicaciones y los comandos de abajo se comprobaron con la documentación de Claude Code de Anthropic en octubre de 2026. Si falta algo en tu versión, ejecuta claude update.

Dónde van los archivos CLAUDE.md

Puedes tener varios archivos, cada uno con un alcance distinto. Claude Code los combina todos en lugar de dejar que uno sustituya a otro; los más específicos se leen al final.

Los archivos de la carpeta desde la que inicias Claude y de todas las carpetas superiores se cargan al arrancar. Un CLAUDE.md dentro de una subcarpeta se carga más tarde, cuando Claude lee o edita un archivo de esa subcarpeta.

Crea el archivo con /init

1. Abre una terminal en la carpeta raíz del proyecto e inicia claude.
2. Escribe /init. Claude revisa el código y escribe un CLAUDE.md inicial con los comandos de compilación, las instrucciones de pruebas y las convenciones que encuentra. Si ya existe un CLAUDE.md, sugiere mejoras en lugar de sobrescribirlo.
3. Lee el borrador y borra todo lo obvio o incorrecto.
4. Añade lo que Claude no puede descubrir en el código: decisiones, peculiaridades del entorno, reglas del tipo «nunca hagas X».
5. Haz commit del archivo para que tus compañeros reciban las mismas instrucciones.

Para editarlo más adelante, ejecuta /memory. Muestra las ubicaciones de tus CLAUDE.md y CLAUDE.local.md para los ámbitos de usuario y de proyecto, incluidas las que aún no existen, y abre en tu editor el archivo que elijas. También puedes decir simplemente añade esto a CLAUDE.md.

Qué incluir

Una prueba sencilla: si has tenido que decirle algo a Claude dos veces, va en el archivo. Momentos típicos para añadir una línea: Claude repite un error, una revisión de código detecta algo que debería haber sabido o escribes la misma corrección que en la sesión anterior.

• Comandos: cómo compilar, probar, pasar el linter y ejecutar el proyecto.
• Estructura: dónde está el código clave, por ejemplo los handlers de la API están en src/api/handlers/.
• Convenciones: nombres, formato, reglas de ramas y commits.
• Lecciones aprendidas: cosas que harían tropezar a alguien nuevo en el equipo.

Escribe reglas que se puedan comprobar. Ejecuta npm test antes de hacer commit funciona mejor que prueba tus cambios. Agrupa las líneas con encabezados y viñetas, y elimina las instrucciones que se contradicen, porque Claude podría seguir cualquiera de ellas. Los procedimientos de varios pasos o las reglas que solo importan en una parte del código van mejor en un skill o en una regla limitada a ciertas rutas.

Mantenlo corto y ordenado

• Tamaño: intenta no pasar de 200 líneas por archivo. Los archivos más largos ocupan más contexto y se siguen con menos fiabilidad.
• Importaciones: escribe @README o @docs/git-instructions.md para incluir otro archivo. Las rutas son relativas al CLAUDE.md y las importaciones pueden anidarse hasta cuatro niveles. Los archivos importados siguen ocupando contexto, así que esto ayuda a ordenar, no a reducir el tamaño. La primera vez que un proyecto importa un archivo de fuera de la carpeta, Claude Code te pide que lo apruebes.
• Carpeta de reglas: pon archivos temáticos como testing.md en .claude/rules/. Añade un campo paths al principio (por ejemplo src/api/**/*.ts) y la regla solo se carga cuando Claude trabaja con archivos que coinciden.
• Auditoría: en versiones recientes, /doctor prompt-audit le pide a Claude que busque instrucciones desactualizadas o contradictorias y proponga cambios sin tocar nada hasta que tú lo digas.

CLAUDE.md frente a la memoria automática

Claude Code también guarda sus propias notas, llamadas memoria automática (auto memory). Tú escribes CLAUDE.md; Claude escribe la memoria automática a partir de tus correcciones y preferencias. Se guarda por repositorio en ~/.claude/projects/<project>/memory/, con un índice MEMORY.md cuyas primeras 200 líneas (o 25 KB) se cargan en cada sesión. Se queda en tu equipo y no se comparte por git. Cuando dices recuerda usar siempre pnpm, eso va a la memoria automática; activa o desactiva la función con el interruptor de /memory. Usa CLAUDE.md para todo lo que deba recibir el equipo entero.

Conviene saber

• Claude Code viene con los planes Pro y Max, dentro de la misma suscripción que las apps de Claude; para los miembros de Team y Enterprise hay un artículo de ayuda aparte.
• CLAUDE.md orienta el comportamiento, pero no lo impone. Bloquea comandos o archivos con reglas de permisos en la configuración.
• El CLAUDE.md de la raíz del proyecto se vuelve a leer del disco después de /compact, así que las reglas que guardas ahí sobreviven a las sesiones largas, mientras que las que solo escribiste en el chat pueden perderse. Los archivos de subcarpetas y las reglas por rutas vuelven en cuanto Claude toca de nuevo archivos que coinciden.
• Los archivos de carpetas añadidas con --add-dir no se cargan salvo que definas CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

Si no funciona

• Claude ignora una instrucción. Ejecuta /context y mira en Memory files (archivos de memoria). Si el archivo no aparece, Claude no lo ve: revisa el nombre del archivo y que hayas iniciado Claude en la carpeta correcta.
• Las reglas se cumplen solo a veces. Hazlas más concretas, elimina los conflictos con otros CLAUDE.md o archivos de reglas y acorta el archivo.
• Una importación no se carga. Una ruta con espacios necesita una barra invertida antes de cada espacio, una ruta entre comillas no se importa y una ruta entre comillas invertidas se queda como texto literal. Las importaciones de fuera del proyecto necesitan tu aprobación una sola vez.
• Parece que falta el CLAUDE.md de una subcarpeta. Solo se carga después de que Claude toque un archivo de esa subcarpeta.

Guarda las decisiones y tareas fuera del archivo

CLAUDE.md es para reglas duraderas, no para las tareas pendientes de esta semana. El plugin de Workbranch para Claude Code se encarga de esa parte: ejecuta /workbranch:save y Claude archiva las tareas, decisiones y preguntas abiertas de la sesión en un proyecto de Workbranch, y cuando una sesión empieza en una carpeta vinculada a un proyecto de Workbranch, el plugin muestra lo que sigue pendiente allí. Hay una prueba gratuita de 3 días en app.workbranch.ai.

Fuentes

• How Claude remembers your project (Claude Code Docs, consultado el 30 de octubre de 2026)
• Commands (Claude Code Docs, consultado el 30 de octubre de 2026)
• Use Claude Code with your Pro or Max plan (Centro de ayuda de Claude, consultado el 30 de octubre de 2026)

Preguntas frecuentes