Claude Code y AGENTS.md: cómo activar las instrucciones compartidas

Cómo hacer que Claude Code lea AGENTS.md: respuesta rápida

Sigue esta secuencia:

1. Ejecuta claude --version. Necesitas v2.1.277 o una versión posterior.
2. Actualiza si hace falta. Una instalación nativa admite claude update; con Homebrew o WinGet, utiliza el comando de actualización de su gestor de paquetes.
3. Comprueba que la sesión pueda obtener los feature flags de Anthropic. La carga nativa de AGENTS.md no está disponible en sesiones con proveedores externos como Amazon Bedrock, Agent Platform de Google Cloud y Microsoft Foundry, ni cuando la telemetría o la configuración del tráfico no esencial impiden consultar ese flag.
4. Coloca AGENTS.md o .claude/AGENTS.md en la ruta del proyecto. Con el modo predeterminado, confirma que no exista un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md del proyecto en el directorio de trabajo ni en ninguno de sus directorios superiores.
5. Si necesitas las dos familias de archivos, abre /config y cambia Project instructions a claude-md-and-agents-md.
6. Haz la prueba en una sesión nueva. La primera sesión tras instalar o actualizar es una excepción, así que abre la siguiente antes de evaluar el resultado.

Ese es el camino nativo. Si Project instructions no aparece en /config, conserva la importación documentada @AGENTS.md dentro de CLAUDE.md.

Cómo decide Claude Code qué archivo cargar

El nuevo comportamiento funciona como un selector, no como una búsqueda indiscriminada de todos los archivos de instrucciones. En el modo predeterminado claude-md-or-agents-md, Claude Code busca primero las instrucciones de Claude a nivel de proyecto. Solo recurre a AGENTS.md cuando no encuentra ninguno de los archivos de Claude que cumplen los requisitos en el directorio de trabajo ni en los niveles superiores.

El matiz importante está en el alcance. Un CLAUDE.local.md ubicado en un directorio superior desactiva la alternativa. En cambio, no la desactivan un ~/.claude/CLAUDE.md personal, un CLAUDE.md administrado por la organización ni .claude/rules/. Esta diferencia explica muchos casos en los que dos desarrolladores abren el mismo repositorio y obtienen comportamientos distintos.

Cuando corresponde usar la alternativa, Claude Code lee al inicio de la sesión los archivos AGENTS.md y .claude/AGENTS.md del directorio de trabajo y de los directorios superiores. El AGENTS.md de un subdirectorio puede cargarse más adelante cuando Claude lea un archivo de esa ruta, siempre que el subdirectorio no tenga su propio archivo de Claude válido. No lee directamente AGENTS.local.md, AGENTS.override.md ni archivos guardados en .agents/.

Se parece más al selector eléctrico de un edificio que a una búsqueda por carpetas. Primero, el selector elige qué circuito de instrucciones queda activo. Los archivos del otro circuito pueden ser perfectamente válidos y, aun así, permanecer desconectados.

Configura de forma explícita el modo Project instructions

Abre /config, busca Project instructions y elige según la fuente de verdad que deba usar el repositorio:

• Alternativa, claude-md-or-agents-md: la mejor opción para un repositorio que ya utiliza AGENTS.md y no tiene un archivo de Claude en el proyecto. Es el modo predeterminado.
• Ambos, claude-md-and-agents-md: la mejor opción cuando AGENTS.md contiene las reglas compartidas y CLAUDE.md añade indicaciones específicas para Claude.
• Solo Claude, claude-md: la mejor opción si el equipo todavía no quiere exponer las instrucciones compartidas de sus agentes a Claude Code.
• Solo administrado, managed-only: la mejor opción para un entorno de inicio controlado en el que deben cargarse la política de la organización y la memoria automática, pero no las instrucciones del repositorio.

En el modo que carga ambos, Claude Code lee primero el contenido de Claude y después el de AGENTS en cada directorio. También evita cargar dos veces el mismo AGENTS.md si CLAUDE.md ya lo importa o apunta a él mediante un enlace simbólico.

La selección se aplica desde el siguiente mensaje y se conserva en las sesiones nuevas. También puede definirse en la configuración de usuario mediante el plugin integrado agents-md@builtin, en un archivo --settings o en la configuración administrada. Claude Code ignora esta opción dentro de los archivos de configuración locales y del proyecto, por lo que un repositorio no puede imponer silenciosamente la misma selección a todos los desarrolladores. Un administrador sí puede fijarla de forma centralizada mediante la configuración administrada.

Cómo comprobar qué archivo cargó una sesión nueva

Utiliza un dato inofensivo, no una instrucción destructiva. Añade esta línea al archivo que quieras probar:

Project probe: BASALT-HERON.

Después, cierra la sesión, inicia otra sesión nueva dentro del repositorio y pregunta: What is the project probe? Si responde correctamente BASALT-HERON, el contenido llegó al contexto de la sesión. Elimina la línea cuando termine la comprobación.

No uses /context como único criterio. Un AGENTS.md cargado directamente no aparece en la lista Memory files. Con el modo alternativo predeterminado, una sesión interactiva puede mostrar al iniciar la línea AGENTS.md loaded. Preguntar por la prueba inofensiva también funciona con los demás modos de selección.

Si la prueba falla, revisa estos puntos en orden:

1. Versión: v2.1.277 o posterior.
2. Número de sesión: que no sea la primera sesión después de instalar o actualizar.
3. Proveedor: que la sesión no utilice un proveedor que impida obtener los feature flags de Anthropic.
4. Entorno: que ninguna variable de telemetría o tráfico no esencial haya desactivado esa consulta.
5. Plugin y política: que el plugin integrado agents-md esté habilitado y que ni disableAllHooks ni allowManagedHooksOnly lo bloqueen.
6. Jerarquía de archivos: que, en el modo predeterminado, no exista un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md válido en el nivel actual ni en niveles superiores.
7. Modo: que /config corresponda al comportamiento que buscas.

Si Project instructions no aparece en /config, eso ya es una señal de diagnóstico. La sesión usa una versión incompatible o no puede utilizar la función.

Conserva la importación cuando el soporte nativo no pueda funcionar

La importación existente sigue siendo la capa de compatibilidad más segura para Bedrock, Vertex, Foundry, otros proveedores externos, los entornos con telemetría restringida y los equipos que mezclan versiones. Añade lo siguiente a un CLAUDE.md situado junto a AGENTS.md:

@AGENTS.md

Debajo puedes añadir instrucciones específicas para Claude. Claude lee primero el archivo compartido importado y después las indicaciones exclusivas para Claude. Mantener este puente no provoca una carga duplicada cuando un usuario compatible selecciona el modo que carga ambos archivos.

Un enlace simbólico de CLAUDE.md a AGENTS.md también funciona, aunque la importación es una opción más segura entre plataformas. En Windows, crear enlaces simbólicos puede requerir privilegios elevados o el modo de desarrollador, y Git necesita la configuración adecuada para gestionarlos. Cuando la carga directa funcione, conviene retirar cualquier hook SessionStart que imprima AGENTS.md, ya que puede inyectar una copia duplicada.

Esta versión cambia el costo de mantenimiento. Antes, un equipo con una sola política para distintos agentes solía mantener dos archivos, un puente de importación o un hook. En las sesiones compatibles, la ruta predeterminada ahora puede reducirse a un único archivo de instrucciones incluido en el repositorio. La licencia de Claude no se abarata: Anthropic incluye Claude Code en el plan Pro de $20 al mes. El ahorro está en tener menos puntos de sincronización y menos sesiones que trabajen con reglas desactualizadas.

Para completar la configuración, la guía general de Claude Code explica la instalación, el contexto del proyecto y el flujo de comandos cotidiano. Si el repositorio también define agentes especializados, la guía de subagentes describe su contexto de inicio independiente.

Siete situaciones en las que este cambio resulta útil

La lista está ordenada según la magnitud del problema de coordinación que elimina el nuevo selector.

Los tres primeros casos ofrecen el mayor retorno porque el problema se multiplica entre personas y repositorios. En un repositorio individual con un solo agente, la comodidad existe, pero su impacto es menor.

Qué productos podrían construirse alrededor de esta función

1. Una herramienta de diagnóstico de instrucciones entre agentes

Crea una CLI local y una comprobación de CI que expliquen con precisión qué archivos de instrucciones cargará cada agente de programación. Los equipos de plataforma y las consultoras pagarían por tener una respuesta fiable antes de extender una configuración a todos sus repositorios.

La demanda ya es visible: claude code setup recibe unas 1,900 búsquedas mensuales en EE. UU.; claude md vs agents md, por su parte, alcanza 480 y ha crecido un 1,500% interanual. La versión mínima vendible analizaría el árbol de archivos, leería la versión de Claude Code y la configuración del proveedor, señalaría los archivos que ocultan a otros y mostraría un plan con el orden de carga. Una capa de pago para equipos podría aplicar la misma política en varios repositorios.

Es la oportunidad más sólida porque resuelve un problema de diagnóstico, no uno de plantillas. El riesgo es depender demasiado de la plataforma. Anthropic podría incorporar estas comprobaciones a claude doctor, así que un producto duradero tendría que cubrir varios agentes de programación y mantener un historial de cambios en las políticas, no limitarse a un solo comando de Claude.

2. Un generador y linter de políticas para AGENTS.md

Crea un editor guiado que convierta comandos de compilación, reglas de pruebas, límites entre directorios y requisitos de revisión en un AGENTS.md conciso; después, que compruebe si hay contradicciones o lenguaje ambiguo. El público comprador serían los equipos pequeños de ingeniería que están adoptando varios agentes.

agents md recibe unas 2,900 búsquedas mensuales en EE. UU. La consulta más específica agents md best practices llega a 210 y ha crecido un 750% interanual. Un MVP necesita un analizador del repositorio, una entrevista breve, un borrador generado y reglas de lint para detectar instrucciones duplicadas o contradictorias. También debe respetar la recomendación del proveedor de mantener concisos los archivos del proyecto, en vez de producir un manual de políticas gigantesco.

El punto débil es la falta de una defensa competitiva clara. Cualquier agente de programación puede redactar Markdown. El producto solo justifica su lugar si la validación refleja el orden de carga real y demuestra que cada herramienta compatible consumió el resultado.

3. Una auditoría de migración para flotas mixtas

Ofrece un informe que identifique CLAUDE.md, AGENTS.md, importaciones, enlaces simbólicos, hooks, reglas anidadas y excepciones de proveedores, y que después proponga un plan seguro para migrar a una sola fuente. Las agencias y los equipos grandes que utilizan varias herramientas de agentes serían los compradores más probables.

Las 480 búsquedas mensuales de claude md vs agents md, con un crecimiento interanual del 1,500%, evidencian de forma especialmente directa esta confusión. El MVP puede ser un analizador del repositorio de solo lectura acompañado de un plan de pull request. Nunca debería eliminar un puente de forma automática, porque las sesiones incompatibles podrían seguir necesitándolo.

El riesgo es que la oportunidad tenga una ventana breve. A medida que los equipos adopten una convención estable para compartir archivos, habrá menos migraciones puntuales. Para sostener el servicio, las auditorías periódicas de políticas y las comprobaciones de compatibilidad entre proveedores tendrían que convertirse en su núcleo.

Límites y conclusión honesta

La alternativa nativa elimina un puente. No convierte las instrucciones del proyecto en mecanismos de cumplimiento, no hace compatibles a todos los proveedores ni resuelve reglas contradictorias. Anthropic describe los archivos de instrucciones como contexto. Si un comando debe bloquearse siempre, utiliza una regla de permisos o un hook PreToolUse.

Tampoco hace que AGENTS.md aparezca en los mismos diagnósticos que CLAUDE.md. Una carga directa no figura en /memory ni en la lista Memory files de /context. Esa incoherencia justifica conservar la prueba inofensiva dentro de la lista de comprobaciones de la migración.

No elimines una importación que funciona en una flota con varios proveedores solo porque la prueba nativa dio resultado en una estación de trabajo. Tampoco selecciones el modo que carga ambos archivos sin revisar antes sus contradicciones. Dentro de un directorio, el contenido de Claude se lee antes que el de AGENTS, pero el orden del contexto no constituye un sistema estricto de precedencia de políticas.

Aun así, esta versión aporta una mejora operativa importante. Un repositorio que ya utiliza AGENTS.md como fuente compartida ahora puede funcionar con Claude Code sin fingir que el segundo nombre de archivo es la fuente real. Es una función pequeña con un efecto considerable sobre la coordinación.

Si buscas un sistema fiable de instrucciones para varios agentes adaptado a tus repositorios, puedo ayudarte con la arquitectura y el despliegue de agentes.