Source: https://aiprimetech.io/es/blog/claude-code-agents-md-support/ Sep 19, 2026 · 8 min · Guías para desarrolladores # Claude Code ahora lee AGENTS.md: CLAUDE.md frente a AGENTS.md y el directorio .claude A Por [AI Prime Tech](https://aiprimetech.io/es/) · Con asistencia de IA Si se pregunta «qué es claude.md», es un archivo Markdown que proporciona a Claude Code instrucciones persistentes sobre su proyecto y su flujo de trabajo. Claude Code 2.1.277, publicado el 18 de septiembre de 2026, añade compatibilidad para leer AGENTS.md cuando no hay ningún archivo de instrucciones de Claude que cumpla los requisitos. Esta guía explica ese mecanismo alternativo, cómo cargar ambos archivos y dónde deben ubicarse la configuración, los comandos, los subagentes y las habilidades dentro del directorio .claude . ## ¿Qué es claude.md y qué debería incluir en él? CLAUDE.md es un archivo Markdown de texto sin formato que contiene instrucciones que Claude Code incorpora al contexto de su sesión. Le ofrece un lugar donde registrar información que, de otro modo, tendría que repetir: comandos de compilación y prueba, convenciones de código, arquitectura del proyecto y reglas del flujo de trabajo. No hay un formato de documento obligatorio. Puede organizarlo con encabezados y listas habituales de Markdown, eligiendo la estructura que facilite la comprensión de las instrucciones de su proyecto. De Claude Code /init el comando genera un archivo inicial basado en el proyecto, tal como se describe en la [documentación oficial de buenas prácticas](https://code.claude.com/docs/en/best-practices). Un punto de partida útil es abordar cuatro áreas: - Comandos de compilación y pruebas: los comandos que deben usar los colaboradores para compilar el proyecto y comprobar los cambios. - Convenciones de código: nomenclatura, formato y otras convenciones pertinentes para el repositorio. - Arquitectura del proyecto: los componentes principales y cómo encajan entre sí. - Reglas del flujo de trabajo: los pasos que quieres que Claude siga al realizar y comprobar cambios. Trata estas indicaciones como directrices persistentes. Las instrucciones se incorporan al contexto de Claude; no son una configuración que se aplique de forma obligatoria. Si necesitas configurar Claude Code, usa el archivo de configuración adecuado en lugar de esperar que el texto de CLAUDE.md funcione como un valor de configuración. Esta distinción importa al organizar un repositorio: el conocimiento del proyecto debe estar en los archivos de instrucciones, mientras que la configuración de la aplicación debe estar en los archivos de configuración. El [centro de guías de Claude Code](/es/claude-code/) ofrece un punto de partida para el flujo de trabajo relacionado. ## Dónde debe ubicarse CLAUDE.md Claude Code admite instrucciones compartidas del proyecto e instrucciones personales en varias ubicaciones. La [documentación de los archivos de instrucciones](https://code.claude.com/docs/en/memory) describe estas ubicaciones establecidas y cómo funciona la detección de instrucciones. | Ubicación | Propósito | ./CLAUDE.md | Instrucciones compartidas del proyecto | ./.claude/CLAUDE.md | Instrucciones compartidas del proyecto dentro de .claude | ~/.claude/CLAUDE.md | Instrucciones personales para todos los proyectos | ./CLAUDE.local.md | Instrucciones personales para el proyecto actual Los archivos de instrucciones de los directorios superiores se cargan al iniciar. Los archivos de los subdirectorios se cargan bajo demanda, lo que permite que las instrucciones cobren relevancia a medida que Claude trabaja en esas partes del proyecto. Para las instrucciones compartidas, elige una ubicación que tenga sentido para tu equipo. Un archivo CLAUDE.md en la raíz sitúa las directrices junto a los demás archivos del nivel superior del repositorio. .claude/CLAUDE.md las sitúa junto a los archivos del proyecto específicos de Claude. ### Las instrucciones personales afectan a algo más que la organización de archivos CLAUDE.local.md tiene un propósito distinto al del archivo compartido del proyecto: contiene tus instrucciones personales para ese proyecto. En la versión 2.1.277, su presencia también afecta a si Claude Code recurre a AGENTS.md. Esto significa que añadir un archivo de instrucciones local puede cambiar qué instrucciones compartidas se incorporan al contexto. Antes de crear uno en un repositorio que dependa de AGENTS.md, comprueba el ajuste Instrucciones del proyecto que se describe a continuación. Las ubicaciones anteriores proceden de documentación que se actualiza continuamente y cuya redacción exacta de septiembre de 19 no se verificó. El comportamiento alternativo de la siguiente sección está documentado específicamente para la versión etiquetada 2.1.277. ## ¿Claude Code lee AGENTS.md automáticamente? Sí, bajo ciertas condiciones. Las [notas de la versión 2.1.277 de Claude Code](https://github.com/anthropics/claude-code/releases/tag/v2.1.277) indican: «Se añadió compatibilidad con AGENTS.md: en un proyecto sin CLAUDE.md, Claude Code lee AGENTS.md en su lugar». El comportamiento predeterminado consiste en recurrir a una alternativa, por lo que la mera presencia de un archivo AGENTS.md no significa que vaya a cargarse. En esta versión, la comprobación abarca más que un archivo en la raíz llamado CLAUDE.md. ### ¿Qué impide que se use la alternativa predeterminada? Cualquiera de estos archivos, en cualquier punto de la ruta desde la raíz del sistema de archivos hasta el directorio de trabajo, impide que se use la alternativa predeterminada de AGENTS.md : - CLAUDE.md - .claude/CLAUDE.md - CLAUDE.local.md Las instrucciones administradas, las instrucciones personales en ~/.claude/CLAUDE.mdy .claude/rules/ sí no impiden que se use esa alternativa. Por ejemplo, considera un repositorio con un archivo compartido AGENTS.md y sin ningún archivo de instrucciones de Claude que cumpla los criterios en la ruta de directorios superiores. El modo predeterminado lee las instrucciones de AGENTS. Si después añades CLAUDE.local.md, se impide que se use la alternativa predeterminada, aunque el nuevo archivo contenga instrucciones personales en lugar de las directrices compartidas del equipo. ### Cómo funciona la detección de AGENTS.md La compatibilidad integrada la proporciona el agents-md plugin, versión 0.1.0. Detecta ambos AGENTS.md y .claude/AGENTS.md a lo largo de la ruta de directorios superiores y adjunta instrucciones anidadas cuando Claude lee archivos por debajo de la raíz del proyecto. El contenido ya cargado mediante una importación o un enlace se deduplica. Esto importa si un archivo de instrucciones de Claude ya incorpora el mismo contenido de AGENTS. A la fecha de cierre de la publicación, en septiembre de 19, el anuncio de la versión indica que esta compatibilidad aún no está disponible en Bedrock, Vertex ni Foundry. ## Configura Claude Code para leer un archivo o ambos Abre /config y cambia Instrucciones del proyecto para elegir cómo se cargan las instrucciones. El [README del plugin etiquetado v2.1.277](https://raw.githubusercontent.com/anthropics/claude-code/v2.1.277/mods/agents-md/README.md) documenta cuatro valores exactos. | Valor | Comportamiento | claude-md-or-agents-md | Predeterminado: usar los archivos de instrucciones de Claude y recurrir a AGENTS cuando no exista ningún archivo de Claude que cumpla los criterios | claude-md-and-agents-md | Cargar tanto los archivos de instrucciones de Claude como los de AGENTS | claude-md | Cargar solo los archivos de instrucciones de Claude | managed-only | Conservar las instrucciones administradas y la memoria del motor; excluir del contexto inicial las instrucciones del proyecto, locales y del usuario El README incluye una salvedad importante para managed-only: los archivos anidados de CLAUDE.md pueden seguir adjuntándose. No interpretes este valor como una garantía de que ningún contenido de instrucciones anidadas de Claude pueda incorporarse a la conversación. ### Configuración exacta para la versión 2.1.277 Para cargar ambas familias de instrucciones, usa esta configuración: ``` { "pluginConfigs": { "agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } } ``` Para esta versión, colócala en la configuración del usuario en ~/.claude/settings.json, en un archivo proporcionado mediante --settingso en la configuración administrada. El archivo del proyecto .claude/settings.json sí no proporciona estas opciones del plugin. Los cambios se aplican la próxima vez que se reconstruya el contexto, por ejemplo, en el siguiente turno o en una conversación nueva. Ten en cuenta ese momento al comprobar si un ajuste ha cambiado las instrucciones cargadas. ### Importar instrucciones compartidas sigue siendo una opción También puedes colocar @AGENTS.md dentro de un archivo adyacente CLAUDE.md. Esto importa explícitamente las instrucciones compartidas a través del archivo de instrucciones de Claude. Las importaciones de archivos de instrucciones de Claude usan @path/to/file.md y se introdujeron en la versión v0.2.107. La versión 2.1.277 deduplica el contenido de AGENTS ya importado por CLAUDE.md. Esto te ofrece dos formas de organizar las directrices compartidas: configurar Claude Code para que cargue ambos archivos o usar una importación para incorporar el contenido de AGENTS a un archivo de instrucciones de Claude. Elige la disposición que deje clara la relación para los colaboradores del repositorio. ## ¿Qué debe incluirse en el directorio .claude? El .claude directorio contiene varios tipos de archivos del proyecto. Tienen propósitos distintos, así que elige la ubicación según estés escribiendo directrices persistentes, configuración, un prompt reutilizable, una definición de subagente o un procedimiento. | Archivo o directorio | Propósito | .claude/CLAUDE.md | Instrucciones compartidas del proyecto | .claude/settings.json | Configuración compartida del proyecto que se puede incorporar al repositorio para el equipo | .claude/settings.local.json | Ajustes personales que sustituyen la configuración del proyecto | .claude/commands/.md | Prompts reutilizables para comandos personalizados con barra | .claude/agents/.md | Definiciones de subagentes del proyecto | .claude/skills//SKILL.md | Procedimientos reutilizables, acompañados opcionalmente de scripts y archivos de referencia La configuración personal para todos los proyectos se guarda en ~/.claude/settings.json. Las definiciones personales de subagentes usan ~/.claude/agents/, y las habilidades personales usan ~/.claude/skills//SKILL.md. ### Comandos, subagentes y habilidades Un archivo de comandos como .claude/commands/deploy.md crea /deploy. La versión 2.1.3 unificó los comandos de barra y las habilidades, y los archivos de comandos existentes siguen funcionando junto con las habilidades. Las definiciones de subagentes usan Markdown con metadatos YAML en la cabecera. Los campos obligatorios son name y description; entre los campos opcionales relevantes se incluyen tools, modely permissionMode. Gestiónalos con /agents, y usa la [guía de subagentes](/es/claude-code/subagents/) para esa parte de la configuración de tu proyecto. Las habilidades agrupan procedimientos reutilizables en una carpeta que contiene SKILL.md, con scripts y material de referencia opcionales. Claude puede seleccionar las habilidades pertinentes, o puedes invocar una con /skill-name; el contenido de la habilidad se carga cuando se usa. La [guía de habilidades](/es/claude-code/skills/) explica este flujo de trabajo. Estas estructuras son anteriores a la versión que incorporó el mecanismo alternativo de AGENTS. El [registro de cambios etiquetado](https://raw.githubusercontent.com/anthropics/claude-code/v2.1.277/CHANGELOG.md) confirma que la configuración del proyecto, los comandos, los agentes y las habilidades ya existían en la versión v2.1.277. Las descripciones detalladas del directorio se basan en documentación que se actualiza continuamente y cuya redacción exacta en la fecha de corte no se verificó. ## CLAUDE.md frente a la memoria automática CLAUDE.md y la memoria automática se diferencian por quién escribe el contenido. Tú escribes los archivos de instrucciones para definir las directrices del proyecto; Claude guarda contexto útil en la memoria automática. El registro de cambios etiquetado documenta el guardado automático y la gestión mediante /memory en la versión 2.1.59. Por tanto, la memoria automática cumple una función distinta de las instrucciones que mantienes deliberadamente en CLAUDE.md o AGENTS.md. Al decidir dónde debe ir la información, guíate por esa distinción de autoría. Incluye los comandos de compilación explícitos, las convenciones, las notas de arquitectura y las reglas del flujo de trabajo en tus archivos de instrucciones. Usa /memory para gestionar el contexto útil que Claude guarda automáticamente. ## Puntos clave - CLAUDE.md contiene instrucciones persistentes en Markdown que Claude Code incorpora al contexto; no impone la configuración. - Claude Code 2.1.277 añade un mecanismo alternativo condicional de AGENTS.md , con Bedrock, Vertex y Foundry excluidos en el lanzamiento. - Un archivo en un directorio antecesor, ya sea CLAUDE.md, .claude/CLAUDE.md, o CLAUDE.local.md desactiva el mecanismo alternativo predeterminado. - Establece las instrucciones del proyecto en claude-md-and-agents-md para cargar ambas familias de instrucciones. - En v2.1.277, las opciones del plugin deben estar en la configuración del usuario, en un archivo --settings o en la configuración administrada, no en la configuración del proyecto .claude/settings.json. - El .claude también contiene configuración, comandos, subagentes y habilidades; la memoria automática contiene contexto guardado por Claude. ## Preguntas frecuentes ### ¿Qué es CLAUDE.md? CLAUDE.md es un archivo Markdown de texto plano que contiene instrucciones persistentes para Claude Code, como comandos de compilación, convenciones de programación, notas de arquitectura y reglas del flujo de trabajo. Claude lo incorpora al contexto de la sesión, y /init puede generar un archivo inicial basado en el proyecto. ### ¿Qué archivo se carga cuando existen tanto CLAUDE.md como AGENTS.md? En el modo predeterminado de Claude Code 2.1.277 claude-md-or-agents-md de instrucciones, un archivo de instrucciones de Claude que cumpla los requisitos desactiva el uso de AGENTS como alternativa. Selecciona claude-md-and-agents-md para cargar ambos, o importa las instrucciones de AGENTS de un archivo vecino con @AGENTS.md dentro de CLAUDE.md. ### ¿Por qué añadir CLAUDE.local.md desactiva el mecanismo alternativo de AGENTS? La versión 2.1.277 incluye CLAUDE.local.md entre los archivos que desactivan el mecanismo alternativo predeterminado cuando se encuentran en la ruta desde la raíz del sistema de archivos hasta el directorio de trabajo. Por tanto, su presencia puede cambiar si se cargan las instrucciones compartidas de AGENTS, aunque su propósito sea proporcionar directrices personales para el proyecto. ### ¿Puedo habilitar ambos archivos en .claude/settings.json del proyecto? En v2.1.277, el archivo del proyecto .claude/settings.json no proporciona las opciones del plugin agents-md . Usa /config, o coloca la configuración documentada de pluginConfigs en la configuración del usuario, en un archivo --settings o en la configuración administrada. [Claude](/es/blog/tag/claude/)[Programación](/es/blog/tag/coding/)[Agentes](/es/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/es/) AI Prime Tech publica este blog. Los artículos se redactan con asistencia de IA; comprueba los detalles específicos de cada versión, como los identificadores de modelos, los precios y los límites, en la documentación oficial antes de basarte en ellos. Obtén acceso más económico a la API de Claude Una sola clave de API para Claude Opus 5.5, Sonnet 5, Haiku 4.5 y Fable 5.1, además de GPT-6 modelos. Pago por uso, sin suscripción. [Obtén tu clave de API →](/register) AI Prime Tech es una pasarela de API independiente de terceros. Claude™ y Anthropic® son marcas comerciales de Anthropic, PBC. No se implica ninguna afiliación ni respaldo.