SpyBara
Go Premium

memory.md 2026-10-01 23:59 UTC to 2026-10-02 04:57 UTC

This page contains 98 additions and 96 deletions.

2026
Fri 2 04:57

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:

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á.

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 repositorio, compartido entre worktrees
Se carga en Cada sesión Cada sesión (primeras 200 líneas o 25KB)
Usar para Estándares de codificación, flujos de trabajo, arquitectura del proyecto Sus preferencias, correcciones que le da a Claude, contexto del proyecto que Claude no puede derivar del código

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, tu flujo de trabajo personal o toda tu organización. Tú escribes estos archivos en texto plano; Claude los lee al inicio de cada sesión. Si tu repositorio utiliza AGENTS.md en su lugar, consulta AGENTS.md.

Cuándo agregar a CLAUDE.md

Trata CLAUDE.md como el lugar donde escribes lo que de otro modo tendrías que volver a explicar. Agrega contenido cuando:

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

Limítalo a hechos que Claude debe retener en cada sesión: comandos de compilación, convenciones, estructura del proyecto, reglas de "siempre haz X". Si una entrada es un procedimiento de varios pasos o solo importa para una parte de la base de código, muévela 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.

Elige 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.

Alcance Ubicación Propósito Ejemplos de casos de uso Compartido con
Política administrada • 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 administradas 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 de usuario ~/.claude/CLAUDE.md Preferencias personales para todos los proyectos Preferencias de estilo de código, atajos de herramientas personales Solo tú (todos los proyectos)
Instrucciones de proyecto ./CLAUDE.md o ./.claude/CLAUDE.md. Consulta AGENTS.md para saber cuándo ./AGENTS.md se carga en su lugar o junto con ellos 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 locales ./CLAUDE.local.md Preferencias personales específicas del proyecto; agrégalo a .gitignore Tus URLs de sandbox, datos de prueba preferidos Solo tú (proyecto actual)

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. Consulta Cómo se cargan los archivos CLAUDE.md para ver el orden de resolución completo.

Para proyectos grandes, puedes dividir las instrucciones en archivos específicos por tema utilizando reglas de proyecto. Las reglas te permiten limitar las instrucciones a tipos de archivo o subdirectorios específicos.

Configura un CLAUDE.md de proyecto

Un CLAUDE.md de proyecto puede almacenarse en ./CLAUDE.md o ./.claude/CLAUDE.md. Crea este archivo y agrega 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 tu equipo a través del control de versiones, así que enfócate en estándares a nivel de proyecto en lugar de preferencias personales. Para confirmar que el archivo se cargó, ejecuta /context en una sesión y revisa la lista bajo Memory files.

Escribe instrucciones efectivas

Claude trata los archivos CLAUDE.md como contexto, no como configuración forzada, por lo que la forma en que escribes las instrucciones afecta la confiabilidad con la que Claude las sigue. Escribe instrucciones lo suficientemente concretas para poder verificarlas:

  • "Usar indentación de 2 espacios" en lugar de "Formatear código correctamente"
  • "Ejecutar npm test antes de hacer commit" en lugar de "Probar tus cambios"
  • "Los controladores de API viven en src/api/handlers/" en lugar de "Mantener los archivos organizados"

Mantén tus archivos cortos, organizados y consistentes:

  • Tamaño: apunta a menos de 200 líneas por archivo CLAUDE.md. Los archivos más largos consumen más contexto y reducen la adherencia. Mueve las instrucciones que importan solo para parte de la base de código a reglas con alcance de ruta, que se cargan solo cuando Claude trabaja con archivos coincidentes. Las importaciones te ayudan a organizar un archivo largo pero no reducen su costo de contexto, porque los archivos importados también se cargan al iniciar.
  • Estructura: agrupa las instrucciones relacionadas bajo encabezados y viñetas markdown. Las secciones organizadas son más fáciles de seguir para Claude que los párrafos densos.
  • Consistencia: si dos instrucciones se contradicen entre sí, Claude puede elegir una arbitrariamente. Revisa periódicamente tus archivos CLAUDE.md, los archivos CLAUDE.md anidados en subdirectorios y .claude/rules/ para eliminar instrucciones obsoletas o conflictivas. Para que Claude las encuentre por ti, ejecuta una auditoría de prompts.

Audita tus archivos de instrucciones

Para que Claude revise tus archivos de instrucciones en busca de contenido obsoleto o conflictivo, ejecuta /doctor prompt-audit en una sesión. Claude busca problemas como instrucciones escritas para modelos más antiguos, referencias a archivos o comandos que no existen y archivos que se contradicen entre sí. Obtienes un informe de hallazgos con ediciones propuestas, y nada en tus archivos cambia hasta que le pidas a Claude que las aplique.

De forma predeterminada, la auditoría cubre tus archivos CLAUDE.md, CLAUDE.local.md y AGENTS.md, además de las reglas, skills, comandos, subagentes y estilos de salida bajo .claude/ y ~/.claude/. Para auditar un solo archivo o directorio en su lugar, pasa su ruta, por ejemplo /doctor prompt-audit .claude/skills/deploy.

La auditoría se ejecuta a través del skill incluido /claude-api. No está disponible mientras ese skill esté desactivado en skillOverrides o con disableBundledSkills. /doctor prompt-audit requiere Claude Code v2.1.283 o posterior.

Importa 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.

Para importar un archivo cuya ruta contiene espacios, coloca una barra invertida antes de cada espacio. Sin las barras invertidas, la ruta termina en el primer espacio, incluso cuando la importación está sola en una línea. Una ruta entre comillas no se importa en absoluto, con o sin las barras invertidas. Esta importación carga un archivo desde una carpeta llamada Design Docs:

- API conventions @Design\ Docs/api-conventions.md

El análisis de importaciones omite los fragmentos de código en línea y los bloques de código delimitados de Markdown. Para mencionar una ruta en tu CLAUDE.md sin importarla, envuélvela 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, haz referencia a ellos con la sintaxis @ en cualquier lugar de tu CLAUDE.md:

Consulta @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 subirse al control de versiones, crea un CLAUDE.local.md en la raíz del proyecto. Se carga junto con CLAUDE.md y se trata de la misma manera. Agrega CLAUDE.local.md a tu .gitignore para que no se incluya en ningún commit. Con CLAUDE_CODE_NEW_INIT=1 configurado, ejecutar /init y elegir la opción personal lo hace por ti.

Si trabajas en múltiples git worktrees del mismo repositorio, un CLAUDE.local.md ignorado por git solo existe en el worktree donde lo creaste. Para compartir instrucciones personales entre worktrees, importa en su lugar un archivo desde tu directorio home:

# 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 tu directorio de trabajo actual y cada directorio por encima de él. Si ejecutas Claude Code en foo/bar/, carga 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 sobrescribirse entre sí. A lo largo del árbol de directorios, el contenido se ordena desde la raíz del sistema de archivos hasta tu directorio de trabajo. En el ejemplo de foo/bar/, foo/CLAUDE.md aparece en contexto antes que foo/bar/CLAUDE.md, por lo que las instrucciones más cercanas a donde iniciaste Claude se leen al final. Dentro de cada directorio, CLAUDE.local.md se añade después de CLAUDE.md, por lo que tus 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 tu directorio de trabajo actual. En lugar de cargarse al iniciar, se incluyen cuando Claude lee archivos en esos subdirectorios. Para archivos dentro de un worktree bajo .claude/worktrees/, consulta Aislar subagentes con worktrees.

Si trabajas en un monorepo grande donde se recogen archivos CLAUDE.md de otros equipos, usa claudeMdExcludes para omitirlos. Para ver la estructura completa de archivos CLAUDE.md raíz y por directorio y de las reglas, consulta 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. Úsalos para dejar notas a los mantenedores humanos sin gastar tokens de contexto en ellas. Los comentarios dentro de bloques de código se conservan. Cuando abres un archivo CLAUDE.md directamente con la herramienta Read, los comentarios siguen visibles.

Carga desde directorios adicionales

El flag --add-dir le da a Claude acceso a directorios adicionales fuera de tu 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, establece 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 establece la variable solo para ese inicio en Bash o Zsh. Para mantenerla activada en cada sesión, agrégala 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 excluyes local de --setting-sources.

Organiza reglas con `.claude/rules/`

Para proyectos más grandes, puedes organizar las 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 limitarse a rutas de archivo específicas, de modo que solo se cargan en contexto cuando Claude trabaja con archivos coincidentes, lo que reduce el ruido y ahorra espacio de contexto.

Configura reglas

Coloca archivos markdown en el directorio .claude/rules/ de tu 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 puedes organizar las 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 excluyes 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 endpoints 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. La coincidencia también funciona cuando Claude llega a un archivo a través de una ruta enlazada simbólicamente al directorio del proyecto, por ejemplo en un checkout enlazado simbólicamente.

Usa 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

Puedes especificar múltiples patrones y usar expansión de llaves para hacer coincidir múltiples extensiones en un solo 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, toda la lista paths de una regla comparte un único presupuesto de 1.000 patrones expandidos y 4 MiB, y los patrones sin llaves no cuentan contra él.

Claude Code usa sin expandir cualquier patrón que excedería el presupuesto, 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 expresión de corchetes, como photos [2024/**, es inválido: no coincide con nada, y los demás patrones de la regla siguen funcionando. Para hacer coincidir un [ literal en un nombre de archivo, escápalo 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 que se evaluaba la regla, en lugar de no coincidir con nada.

Referencia de frontmatter de reglas

Configura 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 error. Claude Code elimina el frontmatter antes de cargar la regla en contexto.

Campo Requerido Descripción
paths No Patrones glob que limitan la regla a los archivos coincidentes. Acepta una lista YAML o una cadena separada por comas

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

El directorio .claude/rules/ admite enlaces simbólicos, por lo que puedes mantener un conjunto compartido de reglas y enlazarlas 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 tu directorio de trabajo como una importación externa. Las reglas enlazadas no se cargan hasta que apruebes las 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 con @path un archivo fuera del directorio de trabajo, no por los enlaces simbólicos por sí solos. Para cargar reglas compartidas sin esa aprobación, mantenlas en ~/.claude/rules/, donde se aplican a cada proyecto en tu máquina.

Este ejemplo enlaza 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

Si apuntas un enlace simbólico de .claude/rules/ o CLAUDE.md a una ruta de red, como el recurso compartido UNC \\server\share o una ruta bajo /net o /Network, las instrucciones enlazadas no se cargan. Claude Code no sigue el enlace, porque buscar una ruta así puede contactar al host que nombra. Las rutas \\wsl$ no cuentan como rutas de red.

Reglas a nivel de usuario

Las reglas personales en ~/.claude/rules/ se aplican a cada proyecto en tu máquina. Úsalas para preferencias que no son específicas de un proyecto:

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

Claude Code carga las reglas a nivel de usuario antes que las reglas de proyecto, por lo que una regla de proyecto aparece más tarde en el contexto de Claude que una regla de usuario. Ningún conjunto sobrescribe al otro: si una regla de usuario y una regla de proyecto entran en conflicto, Claude puede seguir cualquiera de las dos, así que mantén ambas consistentes.

Administra CLAUDE.md para equipos grandes

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

Implementa un CLAUDE.md para toda la organización

Las organizaciones pueden implementar un CLAUDE.md administrado centralmente que se aplique a todos los usuarios de una máquina. Este archivo no puede excluirse mediante la configuración individual.

1

Crea el archivo en la ubicación de política administrada

  • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
  • Linux y WSL: /etc/claude-code/CLAUDE.md
  • Windows: C:\Program Files\ClaudeCode\CLAUDE.md
2

Impleméntalo con tu sistema de gestión de configuración

Usa MDM, Group Policy, Ansible o herramientas similares para distribuir el archivo en las máquinas de los desarrolladores. Consulta configuración administrada para conocer otras opciones de configuración para toda la organización.

La clave claudeMd te permite poner contenido de 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 de un repositorio, haz commit de un CLAUDE.md de proyecto en su lugar.

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

Dónde se respeta: solo en la configuración administrada y de política. Establecer claudeMd en la configuración de usuario, de 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 la configuración administrada sirven para propósitos diferentes. Usa la configuración para la aplicación técnica y CLAUDE.md para la orientación de comportamiento:

Aspecto Configurar en
Bloquear herramientas, comandos o rutas de archivo específicos Configuración administrada: permissions.deny
Aplicar el aislamiento del sandbox Configuración administrada: sandbox.enabled
Variables de entorno y enrutamiento de proveedores de API Configuración administrada: env
Método de inicio de sesión y restricciones de organización Configuración administrada: forceLoginMethod, forceLoginOrgUUID
Directrices de estilo y calidad de código CLAUDE.md administrado
Recordatorios de manejo de datos y cumplimiento CLAUDE.md administrado
Instrucciones de comportamiento para Claude CLAUDE.md administrado

El cliente aplica las reglas de la configuración independientemente de lo que Claude decida hacer. Las instrucciones de CLAUDE.md moldean el comportamiento de Claude, pero no son una capa de aplicación estricta.

Excluye archivos CLAUDE.md específicos

En monorepos grandes, los archivos CLAUDE.md de directorios superiores pueden contener instrucciones que no son relevantes para tu trabajo. El ajuste claudeMdExcludes te 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égalo a .claude/settings.local.json para que la exclusión se mantenga local en tu máquina:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

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

Para excluir un archivo de reglas al que llegas a través de un enlace simbólico, ya sea que el enlace sea el archivo o su directorio, escribe el patrón contra cualquiera de las dos rutas: la ruta del archivo bajo .claude/rules/ o el destino del enlace. Un patrón que coincida con cualquiera de las dos 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 excluirse. Esto garantiza 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:

Su repositorio tiene Claude lee
Un AGENTS.md, y ningún CLAUDE.md o CLAUDE.local.md en su directorio de trabajo o superior Su AGENTS.md
Un AGENTS.md y un CLAUDE.md o CLAUDE.local.md en su directorio de trabajo o superior Solo sus archivos CLAUDE.md
Un CLAUDE.md que ya importa AGENTS.md Su CLAUDE.md, con AGENTS.md incluido a través de la importación

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:

Valor Lo que Claude lee
claude-md-or-agents-md Sus archivos CLAUDE.md, o sus archivos AGENTS.md cuando no tiene CLAUDE.md o CLAUDE.local.md en su directorio de trabajo o superior. Este es el valor predeterminado
claude-md-and-agents-md Sus archivos CLAUDE.md y AGENTS.md juntos, los archivos CLAUDE.md de cada directorio primero y su AGENTS.md después. Claude Code omite un AGENTS.md que ya ha cargado, por lo que uno que su CLAUDE.md importa o vincula simbólicamente no se lee dos veces
claude-md Solo sus archivos CLAUDE.md
managed-only Solo el CLAUDE.md administrado de su organización y auto memory al iniciar. Sus archivos CLAUDE.md de proyecto, local y usuario, sus archivos .claude/rules/, y cada AGENTS.md se dejan fuera. El CLAUDE.md de un subdirectorio y los archivos .claude/rules/, y las reglas con alcance de ruta, aún se cargan cuando Claude lee un archivo allí

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
  • Usted deshabilitó el plugin agents-md integrado en /plugin
  • En algunos casos, es su primera sesión después de actualizar desde v2.1.276 o anterior. Claude lee AGENTS.md desde su siguiente sesión

Antes de v2.1.281, algunas sesiones, como las en Amazon Bedrock o con telemetría deshabilitada, leían solo archivos CLAUDE.md. En esas versiones, actualice Claude Code. Para darle a Claude su AGENTS.md en cualquiera de 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:

CLAUDE.md AGENTS.md leído a través de la configuración
Hooks InstructionsLoaded Se activan No se activan. Se activan como de costumbre para un AGENTS.md que un CLAUDE.md importa o vincula simbólicamente
Directorios que agrega con --add-dir mientras CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD está establecido Su CLAUDE.md se carga Su AGENTS.md no se carga
Una importación @path de un archivo fuera de su directorio de trabajo Claude Code le pide que apruebe importaciones externas Se carga solo si ya aprobó importaciones externas para este proyecto, sin solicitud

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

La memoria automática está habilitada de forma predeterminada en las sesiones locales. Fuera de las sesiones de Claude Tag, una sesión en un entorno autoalojado se ejecuta con la memoria automática desactivada de forma predeterminada.

Para alternarla, abre /memory en una sesión y usa el botón de alternancia de la memoria automática, que guarda autoMemoryEnabled en tu configuración de usuario en ~/.claude/settings.json. Para desactivarla en un único proyecto, establece 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.
  • Verifique si su instrucción compite con la orientación que Claude Code añade por su cuenta. Si su CLAUDE.md establece reglas de commit o pull request, desactive las integradas con includeGitInstructions y establezca el texto de atribución con attribution.

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. Antes de v2.1.281, algunas sesiones, como las en Amazon Bedrock o con telemetría deshabilitada, no podían cargar AGENTS.md tampoco, por lo que en esas versiones actualice a v2.1.281 o posterior.
  3. 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.

Si uno de sus archivos de instrucciones supera la longitud recomendada, verá una advertencia al iniciar y cuando ejecute /status. También verá una advertencia cuando archivos que están cada uno dentro de esa longitud se suman más allá de un límite combinado al inicio de la sesión. Cada CLAUDE.md, archivo de reglas e importación @path cuenta como un archivo separado.

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.

  • 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