Cómo Claude recuerda su proyecto

Proporcione a Claude instrucciones persistentes con archivos CLAUDE.md o AGENTS.md, y permita que Claude acumule aprendizajes automáticamente con auto memory.

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

• Archivos CLAUDE.md: instrucciones que usted escribe para dar a Claude contexto persistente. Claude también puede leer archivos AGENTS.md de un repositorio, por sí solos o junto con CLAUDE.md
• Auto memory: notas que Claude escribe por sí mismo basadas en sus correcciones y preferencias

Esta página cubre cómo:

• Escribir y organizar archivos CLAUDE.md
• Usar un AGENTS.md existente como sus instrucciones de proyecto, por sí solo o junto con 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. Para bloquear una acción independientemente de lo que Claude decida, use un hook PreToolUse en su lugar. Cuanto más específicas y concisas sean sus instrucciones, más consistentemente Claude las seguirá.

Use archivos CLAUDE.md cuando quiera guiar el comportamiento de Claude. Auto memory permite que Claude aprenda de sus correcciones sin esfuerzo manual.

Los subagents también pueden mantener su propia auto memory. Consulte configuración de subagent para obtener detalles.

Archivos CLAUDE.md

Los archivos CLAUDE.md son archivos markdown que proporcionan 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. Si su repositorio utiliza AGENTS.md en su lugar, consulte AGENTS.md.

Cuándo agregar a CLAUDE.md

Trate CLAUDE.md como el lugar donde escribe lo que de otro modo tendría que re-explicar. Agregue contenido cuando:

• Claude comete el mismo error una segunda vez
• Una revisión de código detecta lo que sí llega al PR que Claude debería haber sabido sobre esta base de código
• Usted escribe la misma corrección o aclaración en el chat que escribió en la sesión anterior
• Un nuevo compañero de equipo necesitaría el mismo contexto para ser productivo

Manténgalo en hechos que Claude debe retener en cada sesión: comandos de compilación, convenciones, diseño del proyecto, reglas "siempre haga X". Si una entrada es un procedimiento de varios pasos o solo importa para una parte de la base de código, muévala a un skill o a una regla con alcance de ruta en su lugar. La descripción general de extensiones cubre cuándo usar cada mecanismo.

Elija dónde colocar los archivos CLAUDE.md

Los archivos CLAUDE.md pueden vivir en varios lugares, cada uno con un alcance diferente. La tabla a continuación los enumera en orden de carga, desde el alcance más amplio hasta el más específico, por lo que una instrucción de proyecto aparece en contexto después de una instrucción de usuario.

Los archivos CLAUDE.md y CLAUDE.local.md en la jerarquía de directorios por encima del directorio de trabajo se cargan al iniciar. Los archivos en subdirectorios se cargan bajo demanda cuando Claude lee archivos en esos directorios. Consulte Cómo se cargan los archivos CLAUDE.md para el orden de resolución completo.

Para proyectos grandes, puede dividir las instrucciones en archivos específicos de temas utilizando reglas de proyecto. Las reglas le permiten limitar el alcance de las instrucciones a tipos de archivo específicos o subdirectorios.

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, por lo que enfóquese en estándares a nivel de proyecto en lugar de preferencias personales. Para confirmar que el archivo se cargó, ejecute /context en una sesión y verifique la lista bajo Memory files.

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. La visualización de la ventana de contexto muestra dónde se carga CLAUDE.md en relación con el resto del contexto de inicio. Debido a que son contexto en lugar de configuración forzada, la forma en que escribe las instrucciones afecta la confiabilidad con la que 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, use reglas con alcance de ruta para que las instrucciones se carguen solo cuando Claude trabaje con archivos coincidentes. También puede dividir el contenido en importaciones para organización, aunque los archivos importados aún se cargan e ingresan a la ventana de contexto al iniciar.

Estructura: use encabezados markdown y viñetas 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 test antes 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"

Consistencia: si dos reglas se contradicen entre sí, Claude puede elegir una arbitrariamente. Revise sus archivos CLAUDE.md, archivos CLAUDE.md anidados en subdirectorios y .claude/rules/ periódicamente para eliminar instrucciones obsoletas o conflictivas. En monorepos, use claudeMdExcludes para omitir archivos CLAUDE.md de otros equipos que no sean relevantes para su trabajo.

Importe 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 cuatro saltos.

El análisis de importación omite espacios de código Markdown y bloques de código delimitados. Para mencionar una ruta en su CLAUDE.md sin importarla, envuélvala en backticks: escribir `@README` mantiene el texto literal, mientras que @README fuera de backticks importa el archivo.

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:

Consulte @README para obtener una descripción general del proyecto y @package.json para los comandos npm disponibles para este proyecto.

# Instrucciones adicionales
- flujo de trabajo de git @docs/git-instructions.md

Para preferencias personales privadas por proyecto que no deben verificarse en el control de versiones, cree un CLAUDE.local.md en la raíz del proyecto. Se carga junto con CLAUDE.md y se trata de la misma manera. Agregue CLAUDE.local.md a su .gitignore para que no se confirme. Con CLAUDE_CODE_NEW_INIT=1 configurado, ejecutar /init y elegir la opción personal lo hace por usted.

Si trabaja en múltiples git worktrees del mismo repositorio, un CLAUDE.local.md ignorado por git solo existe en el worktree donde lo creó. Para compartir instrucciones personales entre worktrees, importe un archivo desde su directorio de inicio en su lugar:

# Preferencias individuales
- @~/.claude/my-project-instructions.md

Cómo se cargan los archivos CLAUDE.md

Claude Code carga CLAUDE.md y CLAUDE.local.md desde su directorio de trabajo actual y cada directorio por encima de él. Ejecute Claude Code en foo/bar/ y cargará instrucciones desde foo/bar/CLAUDE.md, foo/CLAUDE.md y cualquier archivo CLAUDE.local.md junto a ellos.

Todos los archivos descubiertos se concatenan en contexto en lugar de anularse entre sí. En el árbol de directorios, el contenido se ordena desde la raíz del sistema de archivos hasta su directorio de trabajo. Para el ejemplo foo/bar/, foo/CLAUDE.md aparece en contexto antes de foo/bar/CLAUDE.md, por lo que las instrucciones más cercanas a donde lanzó Claude se leen al final. Dentro de cada directorio, CLAUDE.local.md se añade después de CLAUDE.md, por lo que sus notas personales son lo último que Claude lee en ese nivel.

Claude también descubre archivos CLAUDE.md y CLAUDE.local.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. Para el diseño completo de archivos CLAUDE.md raíz y por directorio y reglas, consulte Monorepos y repositorios grandes.

Los comentarios HTML a nivel de bloque (<!-- maintainer notes -->) 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.

Cargue desde directorios adicionales

La bandera --add-dir proporciona 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 de memoria desde directorios adicionales, configure la variable de entorno CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

La forma en línea configura la variable para ese único lanzamiento en Bash o Zsh. Para mantenerla activada para cada sesión, agréguela al bloque env en ~/.claude/settings.json como se muestra en Establecer variables de entorno.

Esto carga CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md y CLAUDE.local.md desde el directorio adicional. CLAUDE.local.md se omite si excluye local de --setting-sources.

Organice 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 el ruido y ahorrando espacio de contexto.

Configure 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/:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Instrucciones principales del proyecto
│   └── rules/
│       ├── code-style.md   # Directrices de estilo de código
│       ├── testing.md      # Convenciones de prueba
│       └── security.md     # Requisitos de seguridad

Las reglas sin frontmatter paths se cargan al iniciar con la misma prioridad que .claude/CLAUDE.md.

Las reglas de proyecto se omiten si excluye project de --setting-sources. Antes de v2.1.211, las reglas que se cargan bajo demanda, incluidas las reglas con alcance de ruta y las reglas en directorios .claude/rules/ anidados, se cargaban incluso cuando project estaba excluido.

Reglas específicas de ruta

Las reglas pueden limitarse a archivos específicos usando frontmatter YAML con el campo paths. Estas reglas condicionales solo se aplican cuando Claude trabaja con archivos que coinciden con los patrones especificados.

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

# Reglas de desarrollo de API

- Todos los puntos finales de API deben incluir validación de entrada
- Usar el formato de respuesta de error estándar
- Incluir comentarios de documentación OpenAPI

Las reglas sin un campo 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. A partir de v2.1.198, la coincidencia también funciona cuando Claude alcanza un archivo a través de una ruta enlazada simbólicamente al directorio del proyecto, por ejemplo en un checkout enlazado simbólicamente.

Use patrones glob en el campo paths para hacer coincidir archivos por extensión, directorio o cualquier combinación:

Puede especificar múltiples patrones y usar expansión de llaves para hacer coincidir múltiples extensiones en un patrón:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Cada grupo de llaves multiplica el número de patrones expandidos: src/*.{ts,tsx} se expande a dos patrones, y {a,b}/{c,d}/*.{ts,tsx} a ocho. Para mantener la expansión acotada, la lista paths completa de una regla comparte un presupuesto de 1.000 patrones expandidos y 4 MiB, y los patrones sin llaves no cuentan contra él.

Claude Code usa cualquier patrón que excedería el presupuesto sin expandir, y sus llaves literales no coinciden con ningún archivo. Antes de v2.1.217, un valor paths con muchos grupos de llaves detenía o bloqueaba la CLI al iniciar.

La sintaxis Glob trata [ como el inicio de una expresión de corchetes como [abc]. Un patrón con un [ que no se puede leer como una expresión de corchetes, como photos [2024/**, es inválido: no coincide con nada, y los otros patrones de la regla siguen funcionando. Para hacer coincidir un [ literal en un nombre de archivo, escápelo como photos \[2024/**. Antes de v2.1.207, un patrón inválido hacía que la herramienta Read fallara para cada archivo contra el cual se evaluaba la regla, en lugar de no coincidir con nada.

Referencia de frontmatter de reglas

Configure una regla con frontmatter YAML entre marcadores --- en la parte superior del archivo. paths es el único campo que Claude Code lee de una regla; cualquier otro campo se ignora sin un error. Claude Code elimina el frontmatter antes de cargar la regla en contexto.

Si el YAML entre los marcadores no se analiza, Claude Code ignora el frontmatter y carga la regla como si no tuviera paths. Ejecute claude --debug para ver el error de análisis.

Comparta 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 circulares se detectan y se manejan correctamente.

Claude Code trata un enlace simbólico cuyo destino está fuera de su directorio de trabajo como una importación externa. Las reglas vinculadas no se cargan hasta que apruebe importaciones externas para el proyecto, y después de eso solo se cargan las que no tienen un campo paths. Claude Code solo solicita esa aprobación cuando un archivo de memoria de proyecto importa un archivo fuera del directorio de trabajo con @path, no para enlaces simbólicos solos. Para cargar reglas compartidas sin esa aprobación, manténgalas en ~/.claude/rules/, donde se aplican a cada proyecto en su máquina.

Este ejemplo vincula tanto un directorio compartido como un archivo individual:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

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:

~/.claude/rules/
├── preferences.md    # Sus preferencias personales de codificación
└── workflows.md      # Sus flujos de trabajo preferidos

Claude Code carga reglas a nivel de usuario antes que reglas de proyecto, por lo que una regla de proyecto aparece más tarde en el contexto de Claude que una regla de usuario. Ninguno de los dos conjuntos anula al otro: si una regla de usuario y una regla de proyecto entran en conflicto, Claude puede seguir cualquiera de ellas, por lo que mantenga los dos consistentes.

Administre CLAUDE.md para equipos grandes

Para organizaciones que implementan Claude Code en equipos, puede centralizar instrucciones y controlar qué archivos CLAUDE.md se cargan.

Implemente CLAUDE.md en toda la organización

Las organizaciones pueden implementar un CLAUDE.md administrado centralmente que se aplique a todos los usuarios en una máquina. Este archivo no puede ser excluido por configuraciones individuales.

La clave claudeMd le permite poner contenido CLAUDE.md administrado directamente dentro de managed-settings.json en lugar de implementar un archivo separado.

Alcance: cada sesión de Claude Code en la máquina, en cada repositorio. Para orientación específica del repositorio, confirme un CLAUDE.md de proyecto en su lugar.

Precedencia: igual que un archivo CLAUDE.md administrado. Se carga antes que CLAUDE.md de usuario y proyecto.

Dónde se respeta: solo configuración administrada y de política. Configurar claudeMd en configuración de usuario, proyecto o local no tiene efecto.

El ejemplo a continuación agrega instrucciones de comportamiento directamente en un archivo de configuración administrada:

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

Un CLAUDE.md administrado y configuración administrada sirven para propósitos diferentes. Use configuración para aplicación técnica y CLAUDE.md para orientación de comportamiento:

Las reglas de configuración se aplican por el cliente independientemente de lo que Claude decida hacer. Las instrucciones CLAUDE.md moldean el comportamiento de Claude pero no son una capa de aplicación forzada.

Excluya 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ón claudeMdExcludes 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": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Los patrones se comparan contra rutas de archivo absolutas usando sintaxis glob. Puede configurar claudeMdExcludes en cualquier capa de configuración: usuario, proyecto, local o política administrada. Los arreglos se fusionan entre capas.

Para excluir un archivo de reglas que alcanza a través de un enlace simbólico, ya sea que el archivo o su directorio sea el enlace, escriba el patrón contra cualquiera de las rutas: la ruta del archivo bajo .claude/rules/ o su destino de enlace. Un patrón que coincida con cualquiera de las rutas excluye el archivo. Antes de v2.1.239, solo un patrón que coincidiera con el destino del enlace excluía el archivo.

Los archivos CLAUDE.md de política administrada no pueden ser excluidos. Esto asegura que las instrucciones de toda la organización siempre se apliquen independientemente de la configuración individual.

AGENTS.md

Claude Code puede leer AGENTS.md como sus instrucciones de proyecto, por lo que un repositorio ya configurado para otros agentes de codificación funciona sin agregar un CLAUDE.md, una importación o una configuración. Esta tabla muestra lo que Claude lee de forma predeterminada para cada combinación de archivos de instrucciones en su repositorio:

Para cambiar el comportamiento predeterminado, por ejemplo para que Claude siempre lea ambos archivos, lea solo CLAUDE.md, o lea solo las instrucciones administradas de su organización, cambie la configuración Project instructions.

Cuándo Claude Code lee AGENTS.md

De forma predeterminada, Claude lee AGENTS.md solo cuando no tiene CLAUDE.md en su directorio de trabajo o superior. Aquí están los archivos que cuentan para esa verificación:

• Cuentan, por lo que Claude los lee en lugar de AGENTS.md: un CLAUDE.md, .claude/CLAUDE.md, o CLAUDE.local.md en su directorio de trabajo o cualquier directorio superior
• No cuentan, y continúan cargándose junto con AGENTS.md: su ~/.claude/CLAUDE.md, el CLAUDE.md administrado de su organización, y los archivos .claude/rules/

Cuando ninguno cuenta, aquí está lo que Claude lee y cómo puede saberlo:

• Al inicio de la sesión: cada AGENTS.md y .claude/AGENTS.md en su directorio de trabajo y los directorios superiores. En una sesión interactiva verá una línea como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md en la conversación
• Mientras Claude trabaja en subdirectorios: el AGENTS.md de un subdirectorio, cuando Claude abre un archivo allí con la herramienta Read y ese subdirectorio no tiene ninguno de los tres archivos CLAUDE.md propios
• Dentro de cada AGENTS.md: las importaciones @path se expanden, los patrones claudeMdExcludes se aplican, y los subagentes que omiten instrucciones de proyecto también omiten estos archivos
• No se lee: AGENTS.local.md, AGENTS.override.md, o cualquier cosa bajo un directorio .agents/

Elija qué archivos de instrucciones se cargan

Para cambiar qué archivos lee Claude, escriba /config en una sesión de Claude Code para abrir el panel de configuración, luego establezca Project instructions en uno de estos valores:

También puede establecer el valor en un archivo de configuración en lugar de /config. Agréguelo bajo el ID del plugin agents-md integrado en pluginConfigs, en ~/.claude/settings.json, un archivo --settings o configuración administrada. Claude Code lo ignora en archivos de configuración de proyecto y local. Este ejemplo hace que Claude lea ambos archivos:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Su cambio se aplica desde el siguiente mensaje que envíe y en cada nueva sesión.

Cuándo el soporte de AGENTS.md no está disponible

En estas sesiones Claude lee solo archivos CLAUDE.md, y Project instructions no aparece en el panel de configuración /config:

• Está en una versión de Claude Code anterior a v2.1.277
• Su sesión no obtiene banderas de características de Anthropic, por ejemplo porque usa Amazon Bedrock u otro proveedor de terceros, o deshabilitó la telemetría. La sección vinculada tiene la lista completa
• Es su primera sesión después de instalar o actualizar a una versión con soporte de AGENTS.md. Claude lee AGENTS.md desde su siguiente sesión
• Usted deshabilitó el plugin agents-md integrado en /plugin

Para darle a Claude su AGENTS.md en estas sesiones, impórtelo desde un CLAUDE.md.

Dónde AGENTS.md difiere de CLAUDE.md

Un AGENTS.md que Claude lee a través de la configuración Project instructions difiere de un CLAUDE.md en estos lugares:

Elimine una solución anterior de AGENTS.md

Si configuró Claude Code para leer AGENTS.md antes de que lo hiciera por su cuenta, aquí está lo que debe hacer con cada configuración común:

• Un CLAUDE.md que contiene @AGENTS.md: puede dejarlo. Mantener la importación nunca hace que Claude lea AGENTS.md dos veces, cualquiera que sea el valor de Project instructions que use. Elimine el CLAUDE.md si no contiene nada más, o manténgalo si algunas de sus sesiones no pueden cargar AGENTS.md directamente.
• Un CLAUDE.md que le dice a Claude en palabras que lea AGENTS.md: Claude ve AGENTS.md solo si decide abrir el archivo. Elimine el CLAUDE.md para que Claude lea AGENTS.md directamente, o reemplace la oración con una importación @AGENTS.md.
• Un CLAUDE.md vinculado simbólicamente a AGENTS.md: nada, o elimine el vínculo simbólico. De cualquier forma, Claude lee el contenido una vez.
• Un hook SessionStart que imprime AGENTS.md: elimínelo. Una vez que Claude lee AGENTS.md directamente, el hook agrega una segunda copia al contexto.

Comparta un archivo con otras herramientas de codificación

Cuando Claude no está leyendo su AGENTS.md directamente, aún puede mantenerlo como el archivo único que comparten todas las herramientas poniendo una importación @AGENTS.md en un CLAUDE.md junto a él. Haga esto cuando su proyecto también tenga un CLAUDE.md, cuando haya establecido Project instructions en claude-md, o en sesiones que no puedan cargar AGENTS.md. Agregue cualquier instrucción específica de Claude debajo de la importación, y Claude lee el archivo importado primero, luego el resto:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Si no necesita contenido específico de Claude, un vínculo simbólico también funciona:

ln -s AGENTS.md CLAUDE.md

El comando no imprime salida en caso de éxito. Antes de elegir el vínculo simbólico sobre la importación, verifique estas restricciones:

• Edición: Claude lee CLAUDE.md a través del vínculo, pero las herramientas Edit y Write se niegan a escribir a través de un vínculo simbólico, y la negativa dirige a Claude a editar el destino del vínculo, AGENTS.md, en su lugar
• Windows: si usted o alguien que clona el repositorio trabaja en Windows, use la importación @AGENTS.md en su lugar. Crear un vínculo simbólico allí requiere privilegios de administrador o modo de desarrollador, y Git verifica un vínculo simbólico comprometido como un archivo de texto sin formato a menos que core.symlinks esté habilitado, lo que deja ese clon con un CLAUDE.md de una línea en lugar de sus instrucciones

Con cualquiera de los enfoques, ejecute /context en su siguiente sesión y confirme que CLAUDE.md aparece bajo Memory files.

Migre instrucciones de otras herramientas

Ejecutar /init lee los archivos de instrucciones de otras herramientas e incorpora las partes relevantes en el CLAUDE.md generado:

• Reglas de Cursor en .cursor/rules/ o .cursorrules
• Reglas de Copilot en .github/copilot-instructions.md
• Con CLAUDE_CODE_NEW_INIT=1 establecido: AGENTS.md, .devin/rules/, .windsurf/rules/ o .windsurfrules, y .clinerules

También puede ejecutar /import para traer la configuración de un agente de codificación compatible a Claude Code, que agrega una copia única de archivos de instrucciones como AGENTS.md al CLAUDE.md coincidente y traslada servidores MCP, comandos, subagentes y skills. Requiere Claude Code v2.1.213 o posterior.

Auto memory

Auto memory permite que Claude acumule conocimiento entre sesiones sin que usted escriba nada. Mientras trabaja, Claude guarda cuatro tipos de notas para sí mismo. Claude registra el tipo como un campo type en el frontmatter del archivo de memoria:

• user: su rol, experiencia y preferencias de trabajo
• feedback: correcciones que usted le da a Claude y enfoques que usted confirma
• project: trabajo en curso, plazos y decisiones que Claude no puede derivar del código o del historial de git
• reference: dónde encontrar información fuera del proyecto, como un rastreador de problemas o un panel de control

Claude omite cualquier cosa que pueda derivar del código base, como arquitectura, rutas de archivo o correcciones de depuración. También omite cualquier cosa que sus archivos CLAUDE.md ya digan.

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.

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, que guarda autoMemoryEnabled en la configuración de usuario en ~/.claude/settings.json. Para desactivarlo en un único proyecto, establezca autoMemoryEnabled en la configuración de ese proyecto:

{
  "autoMemoryEnabled": false
}

Para deshabilitar auto memory a través de variable de entorno, establezca 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.

Si establece CLAUDE_CODE_PROJECT_DIR_NAME junto a CLAUDE_CONFIG_DIR, Claude Code usa ese nombre como el directorio <project> bajo <config dir>/projects/ en lugar de cualquier repositorio que inicie, por lo que los proyectos iniciados con ese directorio de configuración comparten un directorio de auto memory. Requiere Claude Code v2.1.234 o posterior.

Para almacenar auto memory en una ubicación diferente, establezca autoMemoryDirectory en su settings.json. Se lee desde cualquier ámbito de configuración: usuario, proyecto, local, política, o --settings.

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

El valor debe ser una ruta absoluta o comenzar con ~/.

Cuando se establece en .claude/settings.json o .claude/settings.local.json de un proyecto, Claude Code lo respeta bajo la misma regla de confianza del espacio de trabajo que los hooks en archivos de configuración. Mientras permissions.blockReadsOutsideWorkingDirectories está activado, Claude Code no carga auto memory desde un directorio que un archivo de configuración suministrado por el repositorio elige y no guarda nada en él, dondequiera que se encuentre ese directorio.

El directorio contiene un índice MEMORY.md y un archivo de tema por memoria:

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Índice, una línea por memoria, cargado en cada sesión
├── user_role.md        # Una memoria
├── feedback_testing.md # Una memoria
└── ...                 # Cualquier otro archivo de tema que Claude cree

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.

Claude Code elimina transcripciones de sesiones antiguas después del período de retención cleanupPeriodDays, pero excluye los archivos de memoria en el directorio de memoria de ese barrido de retención. MEMORY.md y los archivos de tema permanecen hasta que usted o Claude los edite o elimine.

Cómo funciona

Las primeras 200 líneas de MEMORY.md, o los primeros 25KB, lo que sea menor, se cargan al inicio de cada conversación. El contenido más allá de ese umbral no se carga al inicio de la sesión. Claude mantiene MEMORY.md conciso moviendo notas detalladas a archivos de tema separados.

Después de que Claude escribe en MEMORY.md, Claude Code mide el archivo contra los límites de lectura de 200 líneas y 25KB. Si el archivo está cerca de un límite, Claude Code le recuerda a Claude que lo acorte: mantenga una línea por entrada, mueva detalles a archivos de tema y combine o elimine entradas obsoletas. Si el archivo supera un límite, la escritura aún tiene éxito, pero Claude Code devuelve un error indicándole a Claude que reescriba el índice, porque todo lo que está más allá del límite se descarta en la siguiente carga.

Este límite se aplica solo a MEMORY.md. Claude Code carga un archivo CLAUDE.md de hasta 4 MiB en su totalidad y omite un archivo más grande. Los archivos más cortos producen mejor adherencia.

Claude Code no carga archivos de tema como user_role.md o feedback_testing.md al iniciar. Claude los lee bajo demanda usando sus herramientas de archivo estándar cuando necesita la información.

La auto memory de la conversación principal no se carga en subagentes; la excepción es un fork, que hereda la conversación principal y el prompt del sistema. La auto memory propia de un subagente, habilitada con el campo memory del subagente, es un directorio separado.

Claude lee y escribe archivos de memoria durante su sesión. Cuando ve mensajes como "Saved 2 memories" o "Recalled 2 memories" en la interfaz de Claude Code, Claude está actualizando o leyendo activamente desde ~/.claude/projects/<project>/memory/.

Cuando Claude escribe un archivo de memoria que comienza con frontmatter YAML, Claude Code registra la hora de escritura en un campo modified del frontmatter como una marca de tiempo ISO 8601. La marca de tiempo muestra cuán actual es el hecho, tanto para usted como para Claude cuando lo vuelve a leer. Cualquier archivo que tenga frontmatter obtiene el campo la próxima vez que Claude lo escribe, incluidos los archivos creados en versiones anteriores; Claude Code nunca agrega frontmatter a un archivo que no lo tenga. El campo modified requiere Claude Code v2.1.214 o posterior.

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 sus archivos CLAUDE.md, CLAUDE.local.md y otros archivos de memoria en los ámbitos de usuario y proyecto, incluidas las entradas CLAUDE.md de usuario y proyecto para archivos que aún no existen. También le permite alternar auto memory activado o desactivado y proporciona una opción para abrir la carpeta de auto memory. Seleccione cualquier archivo para abrirlo en su editor; seleccionar uno que aún no existe lo crea primero. Para verificar qué archivos CLAUDE.md y archivos de reglas se cargaron en la sesión actual, ejecute /context.

Los editores GUI como VS Code abren el archivo en una ventana separada, y puede seguir usando la sesión mientras está abierto. Antes de v2.1.216, /memory esperaba a que cerrara el archivo antes de responder. Los editores de terminal como Vim toman el control del terminal hasta que salga.

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 /context y verifique la lista bajo Memory files para verificar que sus archivos CLAUDE.md y CLAUDE.local.md se cargaron. Si un archivo CLAUDE.md no aparece allí, Claude no puede verlo. Use /memory para abrir y editar los archivos.
• 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.

Si la instrucción es algo que debe ejecutarse en un punto específico, como antes de cada commit o después de cada edición de archivo, escríbala como un hook en su lugar. Los hooks se ejecutan como comandos de shell en eventos de ciclo de vida fijos y se aplican independientemente de lo que Claude decida hacer.

Para instrucciones que desea a nivel de prompt del sistema, use --append-system-prompt. Esto debe pasarse en el lanzamiento, por lo que es más adecuado para scripts y automatización que para uso interactivo. Para saber cómo se comporta cuando reanuda una conversación, consulte System prompt flags in resumed conversations.

Mi AGENTS.md no se está cargando

Si su repositorio tiene un AGENTS.md y Claude no parece saber qué dice, la causa habitual es un CLAUDE.md en algún lugar de la ruta del proyecto. Por defecto, Claude lee AGENTS.md solo cuando no tiene CLAUDE.md o CLAUDE.local.md en su directorio de trabajo o por encima de él. Verifique estos en orden:

1. Busque un CLAUDE.md, .claude/CLAUDE.md, o CLAUDE.local.md en su directorio de trabajo o en cualquier directorio por encima de él, excepto su ~/.claude/CLAUDE.md. Si encuentra uno, Claude lo lee en lugar de AGENTS.md a menos que establezca Project instructions en claude-md-and-agents-md.
2. Ejecute claude --version y confirme v2.1.277 o posterior.
3. Verifique si su sesión es una que no puede cargar AGENTS.md, como una sesión en un proveedor de terceros o con telemetría deshabilitada.
4. Escriba /config en su sesión para abrir el panel de configuración y confirme que Project instructions no está establecido en claude-md o managed-only. Si no ve la configuración allí en absoluto, su sesión es una que no puede cargar AGENTS.md.

Para verificar si Claude leyó su AGENTS.md, ejecute /memory y busque su ruta en la lista.

Antes de v2.1.280, /memory y /context no listaban un AGENTS.md que Claude leyera directamente. En esas versiones, pregúntele a Claude qué dicen sus instrucciones de proyecto en su lugar.

Si desea mantener el CLAUDE.md que encontró, o su sesión no puede cargar AGENTS.md, agregue un CLAUDE.md junto a su AGENTS.md que lo importe.

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. Claude Code omite un archivo de más de 4 MiB. Use reglas con alcance de ruta para cargar instrucciones solo cuando Claude trabaja con archivos coincidentes, o recorte contenido que no sea necesario en cada sesión. Dividir en importaciones @path ayuda a la organización pero no reduce el contexto, ya que los archivos importados se cargan al iniciar.

La revisión /doctor propone recortes para un CLAUDE.md registrado: elimina contenido que Claude puede derivar de la base de código, como diseños de directorios, listas de dependencias y descripción general de la arquitectura, y mantiene trampas, justificación y convenciones que difieren de los valores predeterminados de las herramientas. La verificación de recorte requiere Claude Code v2.1.206 o posterior.

Las instrucciones parecen perdidas después de `/compact`

CLAUDE.md de raíz de proyecto sobrevive a la compactación: después de /compact, Claude vuelve a leer desde el disco e lo reinyecta en la sesión. Los archivos CLAUDE.md anidados en subdirectorios y reglas con frontmatter paths: se recargan cuando Claude lee archivos a los que se aplican.

Si una instrucción desapareció después de la compactación, se dio solo en la conversación, vive en un CLAUDE.md anidado que aún no se ha recargado, o es una regla con alcance de ruta que no ha coincidido con un archivo desde entonces. Agregue instrucciones solo de conversación a CLAUDE.md para que persistan. Consulte Qué sobrevive a la compactación para el desglose completo.

Consulte Escriba instrucciones efectivas para obtener orientación sobre tamaño, estructura y especificidad.

Recursos relacionados

• Depurar su configuración: diagnosticar por qué CLAUDE.md o configuración no están surtiendo efecto
• Skills: empaquetar flujos de trabajo repetibles que se cargan bajo demanda
• Settings: configurar el comportamiento de Claude Code con archivos de configuración
• Subagent memory: permitir que los subagents mantengan su propia auto memory