--- title: "CLAUDE.md en Claude Code: el archivo que convierte a la Inteligencia Artificial en un “miembro” del equipo" description: "La fiebre de los asistentes de programación ha llenado el mercado de promesas, pero hay una diferencia práctica que separa a un chatbot “que sugiere código” de un agente que realmente ayuda: la capaci..." url: https://revistacloud.com/claude-md/ date: 2026-03-04 modified: 2026-02-27 author: "Antonio" image: https://revistacloud.com/wp-content/uploads/2026/02/claude-md-terminal.jpg categories: ["Guías y recursos"] tags: ["Claude", "claude code", "Inteligencia Artificial"] type: post lang: es --- # CLAUDE.md en Claude Code: el archivo que convierte a la Inteligencia Artificial en un “miembro” del equipo La fiebre de los asistentes de programación ha llenado el mercado de promesas, pero hay una diferencia práctica que separa a un chatbot “que sugiere código” de un agente que realmente ayuda: **la capacidad de trabajar con un repositorio completo de forma consistente**. Ahí es donde entra Claude Code, la herramienta agéntica de Anthropic diseñada para leer una base de código, editar archivos y ejecutar comandos dentro del flujo habitual de desarrollo. En ese enfoque, un archivo Markdown aparentemente banal se vuelve central: **CLAUDE.md**. No es una plantilla decorativa ni un README alternativo. Es, en esencia, el documento que define **cómo debe comportarse Claude Code en un proyecto**, qué reglas debe seguir y qué significa “terminado”. Bien planteado, reduce malentendidos, acelera iteraciones y evita que el agente “improvise” decisiones que no debería tomar. ## Qué es CLAUDE.md y por qué importa Claude Code trabaja con una idea clave: el contexto no puede depender solo de lo que se le diga en una conversación. Los proyectos reales tienen convenciones, comandos recurrentes, decisiones arquitectónicas y requisitos de validación que no conviene repetir en cada sesión. Por eso, Anthropic distingue dos formas de memoria persistente: - **Auto memory**: notas que Claude guarda automáticamente sobre patrones del proyecto, comandos clave o preferencias. - **CLAUDE.md**: archivos Markdown que escribe y mantiene el usuario (o el equipo) con instrucciones, reglas y preferencias que el agente debe seguir. Ese reparto define el papel de CLAUDE.md: **lo normativo**. Es decir, el “manual de operación” del repo: qué se hace, cómo se hace y qué no se toca. ## Dónde se coloca y qué niveles de memoria existen Uno de los puntos más útiles del diseño es la **jerarquía de memoria**, que permite separar instrucciones según su alcance: - **Política gestionada (organización)**: reglas corporativas administradas por IT/DevOps (estándares, compliance, seguridad). - **Memoria de proyecto**: `./CLAUDE.md` o `./.claude/CLAUDE.md` (compartida en el repositorio). - **Reglas modulares de proyecto**: `./.claude/rules/*.md` (por temas: estilo, testing, seguridad, API…). - **Memoria de usuario**: `~/.claude/CLAUDE.md` (preferencias personales para todos los proyectos). - **Memoria local del proyecto**: `./CLAUDE.local.md` (preferencias privadas de ese repo, pensada para no versionarse). - **Auto memory**: directorio por proyecto en `~/.claude/projects//memory/`. La pieza que suele ahorrar más dolores de cabeza en equipos es **CLAUDE.local.md**, porque se añade automáticamente a `.gitignore`. Eso permite guardar, por ejemplo, URLs de sandbox o datos de prueba locales sin “contaminar” el repositorio con información personal o no compartible. ## Cómo “lee” Claude Code esos archivos Claude Code carga memorias de forma **recursiva**: - Los **CLAUDE.md por encima del directorio de trabajo** se cargan completos al iniciar. - Los **CLAUDE.md en subdirectorios** se cargan *bajo demanda*, cuando Claude entra a trabajar en esos árboles. - Si hay conflicto, **las instrucciones más específicas tienen prioridad** sobre las más generales. Este comportamiento es muy útil en repositorios grandes: se puede tener un CLAUDE.md general en la raíz y, además, reglas específicas para `frontend/`, `infra/` o `src/api/` sin que todo se mezcle indiscriminadamente. ## Imports: reutilizar documentación sin duplicar “verdad” Claude Code permite que CLAUDE.md importe otros archivos usando sintaxis **`@path/to/import`**. La idea es obvia, pero potente: en lugar de copiar comandos o convenciones en varios sitios, se pueden importar fuentes ya existentes (README, package.json, documentos internos, guías de Git, etc.). Hay matices importantes: - Se permiten rutas relativas y absolutas; las rutas relativas se resuelven **respecto al archivo** que contiene la importación. - Si Claude Code detecta **importaciones externas** (fuera del proyecto), muestra un **diálogo de aprobación** la primera vez por seguridad. - Las importaciones **no se evalúan** dentro de bloques de código Markdown para evitar colisiones. - Los imports pueden ser recursivos, con un límite de profundidad. Además, el comando **`/memory`** permite ver qué memorias se están cargando y editar archivos de memoria desde el propio entorno interactivo. ## Auto memory y MEMORY.md: el cuaderno de notas del agente A diferencia de CLAUDE.md, auto memory es “lo que Claude aprende” mientras trabaja. Se guarda en un directorio por proyecto (`~/.claude/projects//memory/`) con un archivo de entrada llamado `MEMORY.md` y posibles ficheros temáticos (por ejemplo, `debugging.md` o `api-conventions.md`). Aquí hay una regla de funcionamiento crítica: **solo se cargan automáticamente las primeras 200 líneas de `MEMORY.md`** al inicio de cada sesión. El resto no entra por defecto, y Claude está instruido para mantener ese índice conciso y mover detalles a ficheros temáticos que leerá bajo demanda. Auto memory se puede activar o desactivar desde **`/memory`**, y también mediante configuración (`~/.claude/settings.json` o `.claude/settings.json`) o una variable de entorno pensada para escenarios gestionados o CI. ## `.claude/rules`: cuando el proyecto necesita reglas por temas (y por rutas) Para equipos o repositorios complejos, Anthropic propone reglas modulares en `.claude/rules/*.md`. En vez de meterlo todo en un solo CLAUDE.md, se pueden separar directrices por tema: estilo, testing, seguridad, APIs, etc. Además, estas reglas pueden ser **condicionales por ruta**, usando frontmatter YAML con un campo `paths`. Eso permite, por ejemplo, exigir validación de entrada y documentación OpenAPI solo para `src/api/**`, sin imponerlo a todo el repositorio. ## Cómo se refina un buen CLAUDE.md Un CLAUDE.md efectivo rara vez nace perfecto. Se construye como un buen runbook: con iteraciones basadas en uso real. En Claude Code, el punto de arranque suele ser el comando **`/init`**, que genera un primer borrador a partir de la estructura del proyecto. A partir de ahí, la mejora suele seguir un patrón bastante estable: 1. **Concretar comandos y flujos**: build, test, lint, cómo levantar entorno, cómo reproducir bugs. 2. **Definir criterios verificables**: qué tests deben pasar, qué endpoint debe responder, qué salida se considera correcta. 3. **Bloquear decisiones sensibles**: lo que no se debe tocar (estructura, dependencias prohibidas, patrones obligatorios). 4. **Modularizar cuando crece**: mover reglas a `.claude/rules/` y usar imports para no duplicar documentación. 5. **Separar lo privado**: todo lo local y personal a `CLAUDE.local.md`, nunca al repositorio. El objetivo no es escribir un ensayo. Es reducir ambigüedad. Un agente rinde más cuando no tiene que interpretar “qué quería decir” el humano. ## Plantilla breve (orientativa) # CLAUDE.md — Guía del proyecto## Contexto - Qué es este repositorio y para qué sirve (2–3 líneas).## Estructura - Carpeta A: … - Carpeta B: … - Archivos clave: …## Comandos - Instalar: … - Desarrollo: … - Tests: … - Lint/Formato: … - Build/Release: …## Convenciones - Naming, estilo, patrones. - Dependencias permitidas/prohibidas. - Qué NO cambiar.## Definición de “hecho” - Debe pasar: tests, lint, build. - Criterios funcionales verificables. --- ## Preguntas frecuentes **¿Qué es exactamente CLAUDE.md en Claude Code?** Un archivo Markdown con instrucciones persistentes (reglas, convenciones y flujos) que Claude Code carga para trabajar de forma consistente en un proyecto. **¿En qué se diferencia de auto memory (MEMORY.md)?** CLAUDE.md lo escribe el usuario/equipo (normas). Auto memory lo escribe Claude (notas aprendidas) y solo carga automáticamente las primeras 200 líneas de `MEMORY.md`. **¿Para qué sirven `.claude/rules` y las reglas por rutas?** Para dividir directrices por temas y aplicar reglas solo a partes concretas del repositorio mediante patrones de ruta. **¿Cuál es la forma más rápida de empezar?** Usar `/init` para generar un borrador y refinarlo con comandos reales, criterios verificables y reglas que eviten ambigüedad. Referencia: [Volver a programar](https://carrero.es/volver-a-programar-despues-decadas-claude-code/) y [¿Qué es Claude.md?](https://administraciondesistemas.com/claude-md-manual-operaciones/)