- Archivos CLAUDE.md: instrucciones que usted escribe para dar a Claude contexto persistente
- Auto memory: notas que Claude escribe por sí mismo basadas en sus correcciones y preferencias
- Escribir y organizar archivos CLAUDE.md
- Limitar reglas a tipos de archivo específicos con
.claude/rules/ - Configurar auto memory para que Claude tome notas automáticamente
- Solucionar problemas cuando las instrucciones no se siguen
CLAUDE.md vs auto memory
Claude Code tiene dos sistemas de memoria complementarios. Ambos se cargan al inicio de cada conversación. Claude los trata como contexto, no como configuración forzada. Cuanto más específicas y concisas sean sus instrucciones, más consistentemente Claude las seguirá.| Archivos CLAUDE.md | Auto memory | |
|---|---|---|
| Quién lo escribe | Usted | Claude |
| Qué contiene | Instrucciones y reglas | Aprendizajes y patrones |
| Alcance | Proyecto, usuario u organización | Por worktree |
| Se carga en | Cada sesión | Cada sesión (primeras 200 líneas) |
| Usar para | Estándares de codificación, flujos de trabajo, arquitectura del proyecto | Comandos de compilación, información de depuración, preferencias que Claude descubre |
Archivos CLAUDE.md
Los archivos CLAUDE.md son archivos markdown que dan a Claude instrucciones persistentes para un proyecto, su flujo de trabajo personal o toda su organización. Usted escribe estos archivos en texto plano; Claude los lee al inicio de cada sesión.Elija dónde colocar los archivos CLAUDE.md
Los archivos CLAUDE.md pueden vivir en varios lugares, cada uno con un alcance diferente. Las ubicaciones más específicas tienen prioridad sobre las más amplias.| Alcance | Ubicación | Propósito | Ejemplos de casos de uso | Compartido con |
|---|---|---|---|---|
| Política gestionada | • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md• Linux y WSL: /etc/claude-code/CLAUDE.md• Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Instrucciones de toda la organización gestionadas por TI/DevOps | Estándares de codificación de la empresa, políticas de seguridad, requisitos de cumplimiento | Todos los usuarios de la organización |
| Instrucciones del proyecto | ./CLAUDE.md o ./.claude/CLAUDE.md | Instrucciones compartidas por el equipo para el proyecto | Arquitectura del proyecto, estándares de codificación, flujos de trabajo comunes | Miembros del equipo a través del control de versiones |
| Instrucciones del usuario | ~/.claude/CLAUDE.md | Preferencias personales para todos los proyectos | Preferencias de estilo de código, atajos de herramientas personales | Solo usted (todos los proyectos) |
Configure un CLAUDE.md de proyecto
Un CLAUDE.md de proyecto puede almacenarse en./CLAUDE.md o ./.claude/CLAUDE.md. Cree este archivo y agregue instrucciones que se apliquen a cualquiera que trabaje en el proyecto: comandos de compilación y prueba, estándares de codificación, decisiones arquitectónicas, convenciones de nomenclatura y flujos de trabajo comunes. Estas instrucciones se comparten con su equipo a través del control de versiones, así que enfóquese en estándares a nivel de proyecto en lugar de preferencias personales.
Escriba instrucciones efectivas
Los archivos CLAUDE.md se cargan en la ventana de contexto al inicio de cada sesión, consumiendo tokens junto con su conversación. Debido a que son contexto en lugar de configuración forzada, cómo escribe las instrucciones afecta qué tan confiablemente Claude las sigue. Las instrucciones específicas, concisas y bien estructuradas funcionan mejor. Tamaño: apunte a menos de 200 líneas por archivo CLAUDE.md. Los archivos más largos consumen más contexto y reducen la adherencia. Si sus instrucciones están creciendo mucho, divídalas usando importaciones o archivos.claude/rules/.
Estructura: use encabezados y viñetas de markdown para agrupar instrucciones relacionadas. Claude escanea la estructura de la misma manera que los lectores: las secciones organizadas son más fáciles de seguir que los párrafos densos.
Especificidad: escriba instrucciones que sean lo suficientemente concretas para verificar. Por ejemplo:
- “Usar indentación de 2 espacios” en lugar de “Formatear código correctamente”
- “Ejecutar
npm testantes de hacer commit” en lugar de “Probar sus cambios” - “Los controladores de API viven en
src/api/handlers/” en lugar de “Mantener los archivos organizados”
.claude/rules/ periódicamente para eliminar instrucciones desactualizadas o conflictivas. En monorepos, use claudeMdExcludes para omitir archivos CLAUDE.md de otros equipos que no sean relevantes para su trabajo.
Importar archivos adicionales
Los archivos CLAUDE.md pueden importar archivos adicionales usando la sintaxis@path/to/import. Los archivos importados se expanden y se cargan en contexto al iniciar junto con el CLAUDE.md que los referencia.
Se permiten rutas relativas y absolutas. Las rutas relativas se resuelven en relación con el archivo que contiene la importación, no con el directorio de trabajo. Los archivos importados pueden importar recursivamente otros archivos, con una profundidad máxima de cinco saltos.
Para incluir un README, package.json y una guía de flujo de trabajo, haga referencia a ellos con la sintaxis @ en cualquier lugar de su CLAUDE.md:
.claude/rules/.
AGENTS.md
Claude Code leeCLAUDE.md, no AGENTS.md. Si su repositorio ya usa AGENTS.md para otros agentes de codificación, cree un CLAUDE.md que lo importe para que ambas herramientas lean las mismas instrucciones sin duplicarlas. También puede agregar instrucciones específicas de Claude Code debajo de la importación. Claude carga el archivo importado al inicio de la sesión, luego agrega el resto:
CLAUDE.md
Cómo se cargan los archivos CLAUDE.md
Claude Code lee los archivos CLAUDE.md caminando hacia arriba en el árbol de directorios desde su directorio de trabajo actual, verificando cada directorio en el camino. Esto significa que si ejecuta Claude Code enfoo/bar/, carga instrucciones tanto de foo/bar/CLAUDE.md como de foo/CLAUDE.md.
Claude también descubre archivos CLAUDE.md en subdirectorios bajo su directorio de trabajo actual. En lugar de cargarlos al iniciar, se incluyen cuando Claude lee archivos en esos subdirectorios.
Si trabaja en un monorepo grande donde se recogen archivos CLAUDE.md de otros equipos, use claudeMdExcludes para omitirlos.
Los comentarios HTML a nivel de bloque (<!-- notas de mantenimiento -->) en archivos CLAUDE.md se eliminan antes de que el contenido se inyecte en el contexto de Claude. Úselos para dejar notas para los mantenedores humanos sin gastar tokens de contexto en ellas. Los comentarios dentro de bloques de código se conservan. Cuando abre un archivo CLAUDE.md directamente con la herramienta Read, los comentarios permanecen visibles.
Cargar desde directorios adicionales
La bandera--add-dir da a Claude acceso a directorios adicionales fuera de su directorio de trabajo principal. De forma predeterminada, los archivos CLAUDE.md de estos directorios no se cargan.
Para cargar también archivos CLAUDE.md de directorios adicionales, incluyendo CLAUDE.md, .claude/CLAUDE.md y .claude/rules/*.md, establezca la variable de entorno CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:
Organizar reglas con .claude/rules/
Para proyectos más grandes, puede organizar instrucciones en múltiples archivos usando el directorio .claude/rules/. Esto mantiene las instrucciones modulares y más fáciles de mantener para los equipos. Las reglas también pueden ser limitadas a rutas de archivo específicas, por lo que solo se cargan en contexto cuando Claude trabaja con archivos coincidentes, reduciendo ruido y ahorrando espacio de contexto.
Las reglas se cargan en contexto cada sesión o cuando se abren archivos coincidentes. Para instrucciones específicas de tareas que no necesitan estar en contexto todo el tiempo, use skills en su lugar, que solo se cargan cuando las invoca o cuando Claude determina que son relevantes para su prompt.
Configurar reglas
Coloque archivos markdown en el directorio.claude/rules/ de su proyecto. Cada archivo debe cubrir un tema, con un nombre de archivo descriptivo como testing.md o api-design.md. Todos los archivos .md se descubren recursivamente, por lo que puede organizar reglas en subdirectorios como frontend/ o backend/:
paths se cargan al iniciar con la misma prioridad que .claude/CLAUDE.md.
Reglas específicas de ruta
Las reglas pueden limitarse a archivos específicos usando frontmatter YAML con el campopaths. Estas reglas condicionales solo se aplican cuando Claude trabaja con archivos que coinciden con los patrones especificados.
paths se cargan incondicionalmente y se aplican a todos los archivos. Las reglas con alcance de ruta se activan cuando Claude lee archivos que coinciden con el patrón, no en cada uso de herramienta.
Use patrones glob en el campo paths para hacer coincidir archivos por extensión, directorio o cualquier combinación:
| Patrón | Coincide con |
|---|---|
**/*.ts | Todos los archivos TypeScript en cualquier directorio |
src/**/* | Todos los archivos bajo el directorio src/ |
*.md | Archivos Markdown en la raíz del proyecto |
src/components/*.tsx | Componentes React en un directorio específico |
Compartir reglas entre proyectos con enlaces simbólicos
El directorio.claude/rules/ admite enlaces simbólicos, por lo que puede mantener un conjunto compartido de reglas y vincularlas en múltiples proyectos. Los enlaces simbólicos se resuelven y se cargan normalmente, y los enlaces simbólicos circulares se detectan y se manejan correctamente.
Este ejemplo vincula tanto un directorio compartido como un archivo individual:
Reglas a nivel de usuario
Las reglas personales en~/.claude/rules/ se aplican a cada proyecto en su máquina. Úselas para preferencias que no son específicas del proyecto:
Gestionar CLAUDE.md para equipos grandes
Para organizaciones que implementan Claude Code en equipos, puede centralizar instrucciones y controlar qué archivos CLAUDE.md se cargan.Implementar CLAUDE.md en toda la organización
Las organizaciones pueden implementar un CLAUDE.md gestionado centralmente que se aplique a todos los usuarios en una máquina. Este archivo no puede ser excluido por configuraciones individuales.Crear el archivo en la ubicación de política gestionada
- macOS:
/Library/Application Support/ClaudeCode/CLAUDE.md - Linux y WSL:
/etc/claude-code/CLAUDE.md - Windows:
C:\Program Files\ClaudeCode\CLAUDE.md
Implementar con su sistema de gestión de configuración
Use MDM, Group Policy, Ansible o herramientas similares para distribuir el archivo en máquinas de desarrolladores. Consulte configuración gestionada para otras opciones de configuración de toda la organización.
| Preocupación | Configurar en |
|---|---|
| Bloquear herramientas, comandos o rutas de archivo específicas | Configuración gestionada: permissions.deny |
| Aplicar aislamiento de sandbox | Configuración gestionada: sandbox.enabled |
| Variables de entorno y enrutamiento de proveedor de API | Configuración gestionada: env |
| Método de autenticación y bloqueo de organización | Configuración gestionada: forceLoginMethod, forceLoginOrgUUID |
| Directrices de estilo de código y calidad | CLAUDE.md gestionado |
| Recordatorios de manejo de datos y cumplimiento | CLAUDE.md gestionado |
| Instrucciones conductuales para Claude | CLAUDE.md gestionado |
Excluir archivos CLAUDE.md específicos
En monorepos grandes, los archivos CLAUDE.md ancestros pueden contener instrucciones que no son relevantes para su trabajo. La configuraciónclaudeMdExcludes le permite omitir archivos específicos por ruta o patrón glob.
Este ejemplo excluye un CLAUDE.md de nivel superior y un directorio de reglas de una carpeta principal. Agréguelo a .claude/settings.local.json para que la exclusión permanezca local en su máquina:
claudeMdExcludes en cualquier capa de configuración: usuario, proyecto, local o política gestionada. Los arrays se fusionan entre capas.
Los archivos CLAUDE.md de política gestionada no pueden ser excluidos. Esto asegura que las instrucciones de toda la organización siempre se apliquen independientemente de la configuración individual.
Auto memory
Auto memory permite que Claude acumule conocimiento entre sesiones sin que usted escriba nada. Claude guarda notas para sí mismo mientras trabaja: comandos de compilación, información de depuración, notas de arquitectura, preferencias de estilo de código y hábitos de flujo de trabajo. Claude no guarda algo cada sesión. Decide qué vale la pena recordar basándose en si la información sería útil en una conversación futura.Auto memory requiere Claude Code v2.1.59 o posterior. Verifique su versión con
claude --version.Habilitar o deshabilitar auto memory
Auto memory está habilitado de forma predeterminada. Para alternarlo, abra/memory en una sesión y use el botón de alternancia de auto memory, o establezca autoMemoryEnabled en la configuración de su proyecto:
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
Ubicación de almacenamiento
Cada proyecto obtiene su propio directorio de memoria en~/.claude/projects/<project>/memory/. La ruta <project> se deriva del repositorio git, por lo que todos los worktrees y subdirectorios dentro del mismo repositorio comparten un directorio de auto memory. Fuera de un repositorio git, se usa la raíz del proyecto en su lugar.
Para almacenar auto memory en una ubicación diferente, establezca autoMemoryDirectory en la configuración de usuario o local:
.claude/settings.json) para evitar que un proyecto compartido redirija escrituras de auto memory a ubicaciones sensibles.
El directorio contiene un punto de entrada MEMORY.md y archivos de tema opcionales:
MEMORY.md actúa como un índice del directorio de memoria. Claude lee y escribe archivos en este directorio durante su sesión, usando MEMORY.md para mantener un registro de lo que se almacena dónde.
Auto memory es local de la máquina. Todos los worktrees y subdirectorios dentro del mismo repositorio git comparten un directorio de auto memory. Los archivos no se comparten entre máquinas o entornos en la nube.
Cómo funciona
Las primeras 200 líneas deMEMORY.md se cargan al inicio de cada conversación. El contenido más allá de la línea 200 no se carga al inicio de la sesión. Claude mantiene MEMORY.md conciso moviendo notas detalladas a archivos de tema separados.
Este límite de 200 líneas se aplica solo a MEMORY.md. Los archivos CLAUDE.md se cargan completamente independientemente de la longitud, aunque los archivos más cortos producen mejor adherencia.
Los archivos de tema como debugging.md o patterns.md no se cargan al iniciar. Claude los lee bajo demanda usando sus herramientas de archivo estándar cuando necesita la información.
Claude lee y escribe archivos de memoria durante su sesión. Cuando ve “Writing memory” o “Recalled memory” en la interfaz de Claude Code, Claude está actualizando o leyendo activamente desde ~/.claude/projects/<project>/memory/.
Auditar y editar su memoria
Los archivos de auto memory son markdown plano que puede editar o eliminar en cualquier momento. Ejecute/memory para examinar y abrir archivos de memoria desde dentro de una sesión.
Ver y editar con /memory
El comando /memory enumera todos los archivos CLAUDE.md y rules cargados en su sesión actual, le permite alternar auto memory activado o desactivado, y proporciona un enlace para abrir la carpeta de auto memory. Seleccione cualquier archivo para abrirlo en su editor.
Cuando le pide a Claude que recuerde algo, como “siempre usar pnpm, no npm” o “recuerde que las pruebas de API requieren una instancia local de Redis”, Claude lo guarda en auto memory. Para agregar instrucciones a CLAUDE.md en su lugar, pídale a Claude directamente, como “agregue esto a CLAUDE.md”, o edite el archivo usted mismo a través de /memory.
Solucionar problemas de memoria
Estos son los problemas más comunes con CLAUDE.md y auto memory, junto con pasos para depurarlos.Claude no está siguiendo mi CLAUDE.md
El contenido de CLAUDE.md se entrega como un mensaje de usuario después del prompt del sistema, no como parte del prompt del sistema en sí. Claude lo lee e intenta seguirlo, pero no hay garantía de cumplimiento estricto, especialmente para instrucciones vagas o conflictivas. Para depurar:- Ejecute
/memorypara verificar que sus archivos CLAUDE.md se están cargando. Si un archivo no aparece en la lista, Claude no puede verlo. - Verifique que el CLAUDE.md relevante esté en una ubicación que se cargue para su sesión (consulte Elija dónde colocar los archivos CLAUDE.md).
- Haga instrucciones más específicas. “Usar indentación de 2 espacios” funciona mejor que “formatear código bien”.
- Busque instrucciones conflictivas en archivos CLAUDE.md. Si dos archivos dan orientación diferente para el mismo comportamiento, Claude puede elegir uno arbitrariamente.
--append-system-prompt. Esto debe pasarse en cada invocación, por lo que es más adecuado para scripts y automatización que para uso interactivo.
No sé qué guardó auto memory
Ejecute/memory y seleccione la carpeta de auto memory para examinar lo que Claude ha guardado. Todo es markdown plano que puede leer, editar o eliminar.
Mi CLAUDE.md es demasiado grande
Los archivos de más de 200 líneas consumen más contexto y pueden reducir la adherencia. Mueva contenido detallado a archivos separados referenciados con importaciones@path (consulte Importar archivos adicionales), o divida sus instrucciones entre archivos .claude/rules/.
Las instrucciones parecen perdidas después de /compact
CLAUDE.md sobrevive completamente a la compactación. Después de /compact, Claude vuelve a leer su CLAUDE.md desde el disco e lo reinyecta fresco en la sesión. Si una instrucción desapareció después de la compactación, se dio solo en la conversación, no se escribió en CLAUDE.md. Agréguelo a CLAUDE.md para que persista entre sesiones.
Consulte Escriba instrucciones efectivas para obtener orientación sobre tamaño, estructura y especificidad.
Recursos relacionados
- Skills: empaquetar flujos de trabajo repetibles que se cargan bajo demanda
- Settings: configurar el comportamiento de Claude Code con archivos de configuración
- Manage sessions: gestionar contexto, reanudar conversaciones y ejecutar sesiones paralelas
- Subagent memory: permitir que los subagents mantengan su propia auto memory