Claude Code y AGENTS.md: cómo usarlo junto con CLAUDE.md

Claude Code AGENTS.md llegó con la versión 2.1.277: en un proyecto sin CLAUDE.md, Claude Code ahora lee tu AGENTS.md como instrucciones del proyecto. No necesitas un import, un symlink ni ninguna configuración. Si tu repositorio tiene ambos archivos, Claude solo lee CLAUDE.md, a menos que cambies la opción Project instructions en /config para cargar ambos.

Si tu equipo combina varios agentes de programación, el mismo AGENTS.md que Codex y Cursor ya leen ahora también guía a Claude Code. Esta guía cubre la precedencia, la migración y un AGENTS.md que enseña a cualquier agente a probar tus APIs con la CLI de Apidog.

¿Qué es AGENTS.md en Claude Code?

AGENTS.md es un archivo Markdown plano con instrucciones para agentes de programación: comandos de compilación, comandos de prueba, estilo de código y reglas del proyecto. Desde la v2.1.277, Claude Code lo lee a través de un plugin integrado, así que un repositorio configurado para otros agentes funciona con Claude Code sin archivos adicionales. No requiere campos obligatorios ni sintaxis especial.

El formato en sí es abierto. El sitio de AGENTS.md lo describe como «un formato simple y abierto para guiar agentes de programación», usado por más de 60 000 proyectos de código abierto y actualmente administrado por la Agentic AI Foundation bajo la Linux Foundation. OpenAI Codex y Cursor documentan ambos el soporte de AGENTS.md, y Claude Code era el ausente evidente hasta esta versión.

¿Primer contacto con el formato? Empieza con cómo escribir archivos AGENTS.md para equipos de desarrollo de APIs.

Este es el historial de la versión según el changelog oficial de Claude Code:

Ejecuta claude --version antes de confiar en cualquiera de estas funciones. En cualquier versión anterior a la 2.1.277, Claude Code solo lee archivos CLAUDE.md.

CLAUDE.md vs AGENTS.md: ¿cuál gana?

Por defecto, gana CLAUDE.md. Claude Code lee AGENTS.md solo cuando no existe ningún CLAUDE.md en tu directorio de trabajo ni en ningún directorio superior. La documentación de memoria de Claude Code detalla tres casos:

No todos los archivos cuentan para esa comprobación. Estos tres bloquean AGENTS.md:

• CLAUDE.md en el directorio de trabajo o superior
• .claude/CLAUDE.md en el directorio de trabajo o superior
• CLAUDE.local.md en el directorio de trabajo o superior

Estos no lo bloquean y se siguen cargando junto con AGENTS.md: tu archivo de usuario en ~/.claude/CLAUDE.md, el CLAUDE.md gestionado por tu organización y los archivos bajo .claude/rules/.

Cuidado con la trampa de CLAUDE.local.md: si añades uno personal para notas sin confirmar, Claude deja de leer el AGENTS.md del equipo en tu caso.

Qué carga Claude Code, y cuándo

Cuando nada lo bloquea, Claude Code lee:

1. Al iniciar la sesión: cada AGENTS.md y .claude/AGENTS.md en el directorio de trabajo y los directorios superiores. Las sesiones interactivas muestran una línea como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
2. En subdirectorios: el AGENTS.md de un subdirectorio, una vez que Claude abre un archivo allí con la herramienta Read y esa carpeta no tiene un CLAUDE.md propio.
3. Imports: los imports @path dentro de AGENTS.md se expanden, y se aplican los patrones de claudeMdExcludes.

Claude Code no lee AGENTS.local.md, AGENTS.override.md ni nada bajo .agents/. Si compartes un repositorio con Codex, que sí documenta AGENTS.override.md, tenlo presente.

Cómo cambiar qué archivos de instrucciones carga Claude Code

Escribe /config en una sesión y establece Project instructions en uno de estos cuatro valores:

Para la mayoría de los equipos mixtos, claude-md-and-agents-md es la opción que buscas. Conserva tu CLAUDE.local.md personal y sigue cargando el AGENTS.md compartido.

También puedes establecerlo en un archivo de configuración. Claude Code lee esta entrada desde ~/.claude/settings.json, un archivo --settings o los ajustes gestionados, y la ignora en los archivos de configuración de proyecto y locales:

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

Antes de la v2.1.285, el ID del plugin era agents-md@builtin. Las versiones desde la 2.1.285 aceptan cualquiera de los dos ID, así que usa el antiguo si instalaciones más antiguas comparten el archivo. El cambio aplica a partir de tu siguiente mensaje.

Si Project instructions no aparece en /config, tu sesión no puede cargar AGENTS.md: estás en una versión anterior a la 2.1.277, desactivaste el plugin integrado con /plugin, o es tu primera sesión tras la actualización (funciona desde la siguiente).

Cómo migrar una solución antigua con AGENTS.md

Muchos equipos integraron AGENTS.md en Claude Code a mano antes de esta versión. La documentación recomienda:

Conserva el import @AGENTS.md si alguien de tu equipo sigue usando una versión anterior a la 2.1.277. Es la única configuración que funciona en todas las versiones.

¿Import o symlink?

Si necesitas reglas específicas de Claude sobre el archivo compartido, usa un import. Claude lee primero el archivo importado y luego el resto:

@AGENTS.md

## Claude Code

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

Si no necesitas nada específico de Claude, un symlink funciona:

ln -s AGENTS.md CLAUDE.md

Dos advertencias: las herramientas Edit y Write de Claude no escriben a través de un symlink, y Git en Windows descarga un symlink confirmado como un archivo de texto de una línea a menos que core.symlinks esté activado. Si alguien de tu equipo usa Windows, elige el import.

En cualquier caso, ejecuta /context all en tu siguiente sesión y confirma que CLAUDE.md aparece en Memory files.

Un AGENTS.md para Codex, Cursor y Claude Code

La ventaja es tener una única fuente de verdad. Pon tus comandos de compilación, comandos de prueba y convenciones en el AGENTS.md de la raíz del repositorio. Codex, Cursor y Claude Code lo leen todos.

Una estructura que funciona en la práctica:

• AGENTS.md en la raíz: todo lo que necesita cualquier agente. Comandos, mapa de carpetas, reglas de estilo, qué no tocar.
• AGENTS.md en subcarpetas grandes: reglas que solo aplican ahí, como services/payments/AGENTS.md. Claude Code las carga bajo demanda cuando lee un archivo de esa carpeta.
• CLAUDE.md opcional: solo si necesitas comportamiento exclusivo de Claude, como el modo plan o hooks. Empiézalo con @AGENTS.md.

Una advertencia: un AGENTS.md cargado mediante la configuración no dispara hooks de InstructionsLoaded, y no se carga desde directorios añadidos con --add-dir. Si dependes de alguna de esas cosas, usa la vía del import @AGENTS.md.

Enseña a tu agente a probar APIs con la CLI de Apidog en AGENTS.md

Escribe tus reglas de pruebas de API una vez, y el agente que abra el repositorio ejecutará las pruebas siempre igual. La CLI de Apidog le da al agente una salida JSON estructurada que puede leer, así que el ciclo se mantiene en la terminal.

Configúralo una vez por máquina:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Un atajo: dile a tu agente «Read https://apidog.com/apidog-cli-installation-guide.md and set up Apidog CLI». Esa guía está escrita para agentes y cubre la instalación, el inicio de sesión y el skill.

Luego añade una sección como esta a tu AGENTS.md:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

Ahora un solo prompt hace el trabajo en Claude Code, Codex o Cursor:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

El agente sigue tus reglas y ejecuta comandos como estos:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

Cada flag anterior proviene de apidog <cmd> --help en Apidog CLI 2.2.12. La misma línea de apidog run con -r junit se integra en CI, y --upload-report envía el resumen de la ejecución a la app para que tu equipo pueda verlo. Para más detalles sobre Claude Code, consulta cómo usar la CLI de Apidog en Claude Code; los usuarios de Codex pueden seguir la CLI de Apidog en Codex. Apidog Free cubre hasta 4 usuarios, así que un equipo pequeño puede probarlo hoy mismo.

Solución de problemas: mi AGENTS.md no se carga

1. Busca un CLAUDE.md en la ruta. Un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o superior gana por defecto. Tu ~/.claude/CLAUDE.md no cuenta.
2. Verifica tu versión. Ejecuta claude --version. Necesitas la 2.1.277 o posterior, y la 2.1.281 o posterior en Bedrock, Vertex AI, Foundry, gateways o con la telemetría desactivada.
3. Revisa la configuración. Abre /config y asegúrate de que Project instructions no esté en claude-md ni en managed-only.
4. Confirma que se cargó. Ejecuta /memory y busca la ruta del AGENTS.md en la lista.

Preguntas frecuentes

¿Claude Code ya lee AGENTS.md? Sí, desde la v2.1.277. Sin ningún CLAUDE.md en tu directorio de trabajo o superior, Claude Code lee AGENTS.md como instrucciones del proyecto automáticamente.

Si tengo tanto CLAUDE.md como AGENTS.md, ¿cuál usa Claude Code? Solo CLAUDE.md, por defecto. Establece Project instructions en claude-md-and-agents-md en /config para cargar ambos, primero el CLAUDE.md.

¿Debo eliminar mi CLAUDE.md que importa @AGENTS.md? No hace falta. El import nunca carga AGENTS.md dos veces, y sigue funcionando para compañeros con versiones anteriores a la 2.1.277. Elimínalo solo si no contiene nada más y todos ya se han actualizado.

¿Claude Code lee AGENTS.override.md como Codex? No. Claude Code ignora AGENTS.override.md, AGENTS.local.md y todo lo que esté bajo .agents/.

¿AGENTS.md funciona en Amazon Bedrock o Google Vertex AI? Sí, desde la v2.1.281. Las versiones anteriores en Bedrock, Vertex AI, Foundry, gateways o con la telemetría desactivada solo leen CLAUDE.md; usa un import @AGENTS.md en esos casos.