CLAUDE.md, AGENTS.md y .cursorrules: una sola estrategia

La mayoría de los equipos de desarrollo empresarial con los que trabajo ya usan más de un agente de codificación con IA. El equipo de plataforma estandarizó Claude Code, el equipo de front-end paga Cursor, todo el mundo tiene GitHub Copilot a través del acuerdo GitHub Enterprise de la organización, alguien encola tareas en segundo plano en Codex y el equipo de datos tiene Gemini CLI en la mitad de sus portátiles. Cada herramienta lee su propio archivo de instrucciones, y cada archivo lo escribió quien adoptó esa herramienta primero. Seis meses después, el comando de compilación de CLAUDE.md está mal, .cursorrules sigue prohibiendo una biblioteca de la que ahora depende el equipo y nadie sabe qué archivo es el autoritativo. Esta guía presenta una estrategia de configuración única para esa situación: una sola fuente de verdad, neutral respecto al proveedor, en AGENTS.md; adaptadores delgados específicos de cada herramienta a su alrededor; reglas claras sobre qué debe seguir siendo específico de la herramienta; y la gobernanza que mantiene los archivos honestos. Cada afirmación sobre lo que lee una herramienta está contrastada con la documentación vigente de ese proveedor y enlazada en el texto.

El problema: cinco herramientas, cinco archivos, desviación

Un archivo de instrucciones es el documento de incorporación que le entrega a un ingeniero nuevo, salvo que ese ingeniero lo lee al comienzo de cada sesión y nunca replica cuando está equivocado. Eso hace que la desviación sea costosa de una manera que la desviación de la documentación nunca lo fue. Un README.md obsoleto le hace perder una tarde a un recién llegado, una vez. Un archivo de instrucciones obsoleto envía cada sesión de agente del repositorio por el mismo camino equivocado, y como cada herramienta tiene su propio archivo, la desviación es desigual: Claude Code puede conocer el nuevo ejecutor de pruebas mientras Copilot sigue ejecutando el antiguo.

Traté los dos archivos más comunes por separado en la guía de CLAUDE.md para equipos empresariales y en la guía de AGENTS.md para codificación empresarial con IA. Esos artículos explican qué va dentro de cada archivo. Este se sitúa por encima de ellos y responde a la pregunta que no deja de llegar en consultas de búsqueda y llamadas de descubrimiento: cuando un equipo ejecuta varios agentes, ¿qué archivo gana y cómo se evita mantener cinco copias de las mismas reglas?

La respuesta corta es que no se mantienen cinco copias. Se mantiene una, y se entiende exactamente cómo la consume cada herramienta.

Qué lee cada herramienta

La tabla siguiente es la referencia que me habría gustado tener cuando empecé a desenredar este asunto. Está construida a partir de la documentación vigente de cada proveedor, y las secciones por herramienta que la siguen aportan los detalles y los enlaces.

Claude Code: CLAUDE.md y sus capas

La documentación de memoria de Claude Code enumera cuatro ámbitos en orden de carga: un archivo de política administrada que despliega TI (/Library/Application Support/ClaudeCode/CLAUDE.md en macOS, /etc/claude-code/CLAUDE.md en Linux y WSL, C:\Program Files\ClaudeCode\CLAUDE.md en Windows), el archivo de usuario en ~/.claude/CLAUDE.md, el archivo de proyecto en ./CLAUDE.md o ./.claude/CLAUDE.md, y un ./CLAUDE.local.md ignorado por Git para notas personales. Claude carga los archivos CLAUDE.md del directorio de trabajo y de cada directorio superior al inicio, los concatena desde la raíz del sistema de archivos hacia abajo de modo que el más cercano se lee al final, y carga los archivos de subdirectorios solo cuando lee, escribe o edita un archivo en ese subdirectorio.

Tres detalles importan para una estrategia compartida. Primero, la sintaxis de importación @path/to/file incorpora otro archivo al contexto, se resuelve de forma relativa al archivo que contiene la importación y puede anidarse hasta cuatro saltos de profundidad; las importaciones dentro de spans de código y bloques delimitados se ignoran. Segundo, la recomendación de Anthropic es apuntar a menos de 200 líneas por archivo CLAUDE.md, y las importaciones no reducen ese costo porque los archivos importados se cargan junto con el archivo que los importa. Tercero, los archivos .claude/rules/*.md se cargan junto al CLAUDE.md del proyecto, y un campo de frontmatter paths: limita una regla a los archivos que coincidan, de modo que solo se carga cuando Claude trabaja en ellos. Si quiere la vista capa por capa de un repositorio de Claude Code, incluidos skills y hooks, lea La anatomía de un proyecto de Claude Code.

OpenAI Codex: AGENTS.md con un archivo de anulación

Codex es la herramienta para la que se creó el formato, y su documentación de AGENTS.md es la descripción más precisa del anidamiento que encontré. Codex busca primero en su directorio de inicio (~/.codex, o CODEX_HOME), donde usa únicamente el primer archivo no vacío, prefiriendo AGENTS.override.md a AGENTS.md. Después comienza en la raíz del proyecto, normalmente la raíz de Git, y desciende hasta el directorio actual, tomando como máximo un archivo por directorio en el orden AGENTS.override.md, AGENTS.md y luego cualquier nombre listado en project_doc_fallback_filenames. Los archivos se unen desde la raíz hacia abajo separados por líneas en blanco, de modo que las instrucciones más cercanas a su directorio de trabajo aparecen más tarde en el prompt y tienen prioridad.

El límite que la mayoría de los equipos pasa por alto: project_doc_max_bytes limita el tamaño combinado a 32 KiB por defecto, y Codex deja de añadir archivos cuando la cadena alcanza ese límite. Un archivo raíz hinchado puede expulsar silenciosamente del contexto un archivo de nivel de paquete.

GitHub Copilot: tres tipos de archivo de instrucciones

La documentación de GitHub sobre instrucciones personalizadas del repositorio describe un .github/copilot-instructions.md para todo el repositorio, archivos NAME.instructions.md específicos de ruta bajo .github/instructions/ con un glob applyTo en el frontmatter (y un excludeAgent opcional con valor code-review o cloud-agent), y archivos de instrucciones para agentes: AGENTS.md en cualquier lugar del repositorio, con prioridad para el archivo más cercano, o un único CLAUDE.md o GEMINI.md en la raíz. Cuando un archivo específico de ruta coincide y además existe un archivo de todo el repositorio, se usan ambos. Entre fuentes, las instrucciones personales se sitúan por encima de las del repositorio, que a su vez se sitúan por encima de las de la organización, pero todos los conjuntos pertinentes se entregan al modelo, así que el consejo de GitHub es evitar contradicciones en lugar de confiar en la jerarquía.

La trampa está en la matriz de compatibilidad. El agente en la nube de Copilot, la revisión de código de Copilot en GitHub.com, Copilot Chat en VS Code y Copilot CLI leen AGENTS.md. Copilot Chat en GitHub.com, en Visual Studio y en los IDE de JetBrains lee .github/copilot-instructions.md pero no AGENTS.md. La revisión de código de Copilot también lee las instrucciones de la rama de origen de la pull request, no de la rama base, lo cual importa cuando cambia los archivos en la misma PR.

Cursor: .cursor/rules y AGENTS.md

La documentación de reglas de Cursor describe las reglas de proyecto como archivos .mdc bajo .cursor/rules/ (un .md sencillo allí se ignora porque no tiene frontmatter) con tres campos de frontmatter: alwaysApply: true incluye la regla en cada chat, globs la adjunta cuando un archivo coincidente está en el contexto, y description por sí sola deja que el agente decida si incorporarla. Las reglas se fusionan en el orden Team Rules, Project Rules, User Rules, con prioridad para la fuente anterior en caso de conflicto. Las Team Rules se administran desde el panel de Cursor en los planes Team y Enterprise y pueden imponerse para que los usuarios no puedan desactivarlas. Cursor también pide mantener las reglas por debajo de 500 líneas y advierte que un archivo referenciado desde una regla no se incrusta; el agente lo lee con sus herramientas solo cuando así lo decide.

AGENTS.md está documentado como una alternativa en Markdown sencillo a .cursor/rules para casos simples, compatible en la raíz del proyecto y en subdirectorios, con las instrucciones anidadas combinadas con las de sus padres y prioridad para el archivo más específico. El archivo único .cursorrules que describen las guías antiguas no aparece en absoluto en la página de reglas actual. Trátelo como heredado y migre.

Gemini CLI: GEMINI.md, con nombre configurable

La documentación de archivos de contexto de Gemini CLI describe un ~/.gemini/GEMINI.md global, archivos GEMINI.md encontrados en los directorios del espacio de trabajo configurados y sus padres, y carga justo a tiempo de archivos de cualquier directorio que toque una herramienta, hasta una raíz de confianza. Todo lo encontrado se concatena y se envía con cada prompt. Se admiten importaciones @file.md con rutas relativas y absolutas. La función que importa aquí es context.fileName en settings.json, que acepta un solo nombre o una lista, y el propio ejemplo de la documentación es ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]. /memory show imprime el contexto combinado y /memory reload vuelve a escanear los archivos.

Windsurf: reglas con límites de caracteres

La documentación de reglas de Windsurf ahora vive bajo Devin Desktop, con .devin/rules/*.md como opción preferida y .windsurf/rules/*.md mantenido como alternativa; el archivo único heredado .windsurfrules sigue leyéndose. Cada archivo de regla lleva un trigger de always_on, glob, model_decision o manual. El archivo de reglas global está limitado a 6 000 caracteres y cada archivo de regla del espacio de trabajo a 12 000 caracteres, el límite documentado más estricto de todas las herramientas aquí tratadas. AGENTS.md se admite en cualquier directorio: un archivo raíz está siempre activo y los archivos de subdirectorios reciben automáticamente un alcance por glob a su directorio. En repositorios Git la búsqueda también asciende hasta la raíz de Git, y TI empresarial puede desplegar reglas de sistema de solo lectura.

La estrategia de fuente única: AGENTS.md más adaptadores delgados

Por qué AGENTS.md es la fuente de verdad

La especificación de AGENTS.md es Markdown sencillo sin campos obligatorios, administrada por la Agentic AI Foundation bajo la Linux Foundation, y enumera entre sus adoptantes a Codex, Cursor, Gemini CLI, Windsurf, el agente de codificación de GitHub Copilot, VS Code, Zed, JetBrains Junie, Devin, Aider, Factory y otros, con más de 60 000 proyectos de código abierto que lo usan. Es el único archivo de la tabla comparativa que todas las herramientas leen de forma nativa o pueden configurarse para leer. Nada más se le acerca: CLAUDE.md lo lee Claude Code y, solo en la raíz, algunas superficies de Copilot; GEMINI.md lo leen Gemini CLI y esas mismas superficies de Copilot; .cursor/rules lo lee únicamente Cursor.

Así que las convenciones compartidas van en AGENTS.md, y todos los demás archivos se convierten en adaptadores: ya sea un stub delgado que contiene instrucciones específicas de la herramienta e incorpora el archivo compartido, o una copia generada que CI mantiene sincronizada.

Claude Code: importe, no duplique

La trampa aquí es el comportamiento por defecto. La documentación de Anthropic indica que Claude lee AGENTS.md solo cuando no hay ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo ni en ningún directorio superior. Un repositorio que tiene ambos archivos, porque alguien añadió un CLAUDE.md para notas específicas de Claude, deja silenciosamente de cargar AGENTS.md en Claude Code. La solución documentada es hacer que @AGENTS.md sea la primera línea de CLAUDE.md; Claude lee primero el archivo importado y luego el contenido específico de Claude que sigue, y la documentación confirma que la importación nunca provoca una doble lectura.

Un enlace simbólico (ln -s AGENTS.md CLAUDE.md) también funciona, pero Anthropic desaconseja usarlo cuando alguien clona en Windows, donde crear un enlace simbólico requiere privilegios de administrador o el modo de desarrollador, y Git extrae un enlace simbólico confirmado como un archivo de texto de una sola línea a menos que core.symlinks esté habilitado. La mayoría de mis clientes tienen al menos un desarrollador en Windows, así que uso la importación. Existe también un ajuste Project instructions con el valor claude-md-and-agents-md, pero solo se respeta desde los ajustes de usuario, --settings o administrados, y se ignora en los ajustes de proyecto y locales, por lo que no puede confirmarlo en el repositorio. La importación es la respuesta portable.

GitHub Copilot: genere, no apunte

Para las superficies de Copilot que leen AGENTS.md, ya ha terminado. Para Copilot Chat en GitHub.com, Visual Studio y JetBrains, el único archivo del repositorio que se carga es .github/copilot-instructions.md. Escribir «lea AGENTS.md» en ese archivo depende de que el modelo decida abrirlo, la misma debilidad que Anthropic señala para un CLAUDE.md que le dice a Claude con palabras que lea AGENTS.md. El patrón fiable es generar .github/copilot-instructions.md a partir de AGENTS.md en CI, con un encabezado que indique que es generado, y una verificación que haga fallar la canalización cuando ambos diverjan. El comportamiento de Copilot específico de ruta, como reglas que solo se aplican a **/*.sql, va en .github/instructions/*.instructions.md, que no tiene equivalente en el archivo compartido.

Cursor, Gemini CLI, Codex y Windsurf

Cursor lee de forma nativa el AGENTS.md raíz y los anidados, así que .cursor/rules se reduce a comportamiento específico de Cursor con alcance por glob y a lo que sus administradores impongan mediante Team Rules. Gemini CLI necesita una sola línea de configuración confirmada, context.fileName establecido en ["AGENTS.md", "GEMINI.md"] en .gemini/settings.json, tras lo cual GEMINI.md contiene solo instrucciones específicas de Gemini. Codex y Windsurf leen el archivo compartido sin configuración; para Codex, mantenga la cadena por debajo de 32 KiB y use AGENTS.override.md solo para anulaciones locales temporales, y si usa Codex para revisión de código en GitHub, añada una sección ## Code Review Rules al AGENTS.md más cercano al código que gobierna, que es el mecanismo que documenta OpenAI.

Lo que no se puede compartir

Los archivos de instrucciones son prosa para el modelo. Todo lo que la herramienta impone en lugar de sugerir al modelo permanece en la configuración propia de esa herramienta, y es distinto para cada una:

La página de memoria de Anthropic lo dice sin rodeos: Claude trata CLAUDE.md como contexto, no como configuración impuesta, y para bloquear una acción independientemente de lo que decida el modelo se usa un hook PreToolUse o una regla permissions.deny. Lo mismo vale para todos los archivos de esta guía. Escriba la regla en AGENTS.md para que todos los agentes la conozcan, y luego imponga las que importan en los ajustes de la herramienta y en CI.

Precedencia en monorepos: archivos raíz frente a archivos de paquete

Todas las herramientas de la tabla admiten un archivo raíz más archivos anidados, y cada una los fusiona de forma ligeramente distinta. Aquí es donde una estrategia de AGENTS.md compartido se sostiene o se derrumba.

De esa tabla se desprenden dos reglas. Primera, redacte cada AGENTS.md anidado de forma que sea correcto tanto si el raíz está también en el contexto como si no. La documentación de Copilot no promete una fusión, Codex puede truncar y Claude Code carga el archivo anidado solo cuando el agente realmente toca ese directorio. Repita el límite o los dos límites que sería catastrófico pasar por alto, y nunca contradiga al raíz; el aviso de Anthropic de que el modelo «puede elegir uno arbitrariamente» cuando las instrucciones entran en conflicto se aplica a todos los agentes. Segunda, mantenga corto el raíz. El objetivo de 200 líneas de Anthropic y el tope de 32 KiB de Codex son los dos números que acotan su diseño, y un archivo raíz que se mantiene por debajo de unos 10 KB deja espacio para dos o tres archivos de paquete antes de que Codex empiece a descartarlos.

Para equipos con decenas de paquetes, la guía de bases de código grandes de Claude Code recomienda una división en dos niveles, raíz más un archivo por paquete, cada uno mantenido por el propietario de ese paquete, con claudeMdExcludes para los paquetes en los que nunca trabaje. Ese modelo de propiedad se traslada directamente a los archivos AGENTS.md anidados de todas las demás herramientas.

Qué va en el archivo compartido y qué en los archivos específicos

La prueba que aplico a cada línea: si un desarrollador cambiara de herramienta mañana, ¿seguiría siendo cierta esta instrucción? Si la respuesta es sí, pertenece a AGENTS.md. Si solo tiene sentido dentro de un producto, pertenece al archivo de ese producto.

Gobernanza: propiedad, revisión, versionado, secretos, pruebas

Propiedad. Añada AGENTS.md, los archivos adaptadores y el script de sincronización a CODEOWNERS, con el equipo de plataforma o de experiencia de desarrollador como propietario del raíz y cada equipo de paquete como propietario de su archivo anidado. La guía de monorepos de Anthropic hace la misma recomendación para los archivos CLAUDE.md por directorio: el propietario de cada directorio mantiene su archivo.

Revisión. Cada cambio en un archivo de instrucciones pasa por una pull request como si fuera código. Claude Code ofrece aquí una ayuda: /doctor prompt-audit (v2.1.283 o posterior) revisa los archivos CLAUDE.md, CLAUDE.local.md y AGENTS.md, además de reglas y skills, en busca de referencias a archivos o comandos que no existen, instrucciones escritas para modelos antiguos y archivos que se contradicen entre sí, y propone ediciones sin cambiar nada hasta que usted las acepte. Ejecútelo antes de fusionar un cambio en el archivo compartido, incluso si Claude Code no es la herramienta que motivó el cambio.

Versionado. Los archivos viven en Git, así que están versionados. Lo que los equipos olvidan es versionar deliberadamente las copias generadas: confirme .github/copilot-instructions.md y deje que CI falle cuando esté desactualizado, en lugar de regenerarlo silenciosamente en tiempo de compilación donde nadie ve la diferencia.

Secretos. Jamás. Estos archivos se inyectan en el contexto del modelo por cada herramienta en la máquina de cada desarrollador, se envían al proveedor que esa herramienta invoque y los copian los generadores. Una cadena de conexión en AGENTS.md es una cadena de conexión en los registros de solicitudes de cinco proveedores. Los archivos personales, CLAUDE.local.md y ~/.codex/AGENTS.override.md, están ignorados por Git pero igualmente entran en el contexto, así que tampoco son lugar para secretos. Dirija a los agentes al entorno o a un gestor de secretos, y respalde la regla con una imposición: una regla permissions.deny de Claude Code como Read(./.env) bloquea la lectura sin importar la intención del modelo.

Probar las instrucciones. Trate un cambio en el archivo compartido como un cambio en un script de compilación y haga una prueba de humo en cada herramienta. Confirme primero la carga: /context en Claude Code enumera los archivos bajo Memory files, /memory show en Gemini CLI imprime el contexto combinado, Copilot Chat en GitHub.com incluye .github/copilot-instructions.md en sus References cuando usó el archivo, y OpenAI sugiere codex -c log_dir=./.codex-log para escribir un registro que pueda auditar. Después ejecute un conjunto fijo de prompts («¿qué comando ejecuta las pruebas?», «¿dónde deben ir las consultas a la base de datos?») y compare las respuestas entre herramientas. Una discrepancia es una desviación que detectó antes que un desarrollador.

Plantillas

Un conjunto breve y realista que puede copiar. El repositorio es una plataforma de pagos ficticia; sustituya los detalles.

AGENTS.md (la fuente de verdad)

# AGENTS.md: Payments Platform

## Project
Node 22 / TypeScript 5.6 monorepo using pnpm workspaces.
Services live under `services/`, shared libraries under `packages/`.

## Commands
- Install: `pnpm install --frozen-lockfile`
- Build: `pnpm -r build`
- Test: `pnpm -r test` (run before every commit)
- Lint and format check: `pnpm lint && pnpm format:check`

## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- Database access goes through `packages/db`. No raw SQL in route handlers.
- Commit subjects: `<package>: <imperative summary>`, for example `api: add idempotency keys`.

## Boundaries
- Never edit files under `**/generated/`. Run `pnpm codegen` instead.
- Never modify a migration that has merged. Add a new one.
- Never commit secrets or `.env*` files. Configuration comes from the environment.
- Changes under `services/payments/` require a human reviewer from the payments team.

## Pull requests
- Title format: `[<package>] <summary>`. Run lint and tests before opening the PR.

## Code Review Rules
- Flag any new dependency without a justification in the PR description.
- Flag raw SQL strings outside `packages/db`.

CLAUDE.md (adaptador delgado)

@AGENTS.md

## Claude Code

- Use plan mode for any change under `services/payments/`.
- Permissions, hooks and MCP servers are configured in `.claude/settings.json`. Do not duplicate them here.

.cursor/rules/testing.mdc (específico de Cursor, con alcance por glob)

---
description: Testing conventions for the payments monorepo
globs: "**/*.test.ts"
alwaysApply: false
---

- Use Vitest. Never add Jest.
- Wrap database tests in a transaction that rolls back.
- Shared project rules live in AGENTS.md; this file holds Cursor-specific behaviour only.

.gemini/settings.json (apunte Gemini CLI al archivo compartido)

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

scripts/sync-agent-instructions.sh (genere la copia de Copilot)

#!/usr/bin/env bash
set -euo pipefail
{
  echo "<!-- GENERATED from AGENTS.md. Edit AGENTS.md and run scripts/sync-agent-instructions.sh. -->"
  cat AGENTS.md
} > .github/copilot-instructions.md
# In CI, fail when the committed copy is out of date:
git diff --exit-code -- .github/copilot-instructions.md

Plan de despliegue para un equipo

1. Semana 1: inventario. Enumere todos los archivos de instrucciones de todos los repositorios, por ejemplo con git ls-files | grep -Ei 'claude\.md|agents\.md|cursorrules|cursor/rules|copilot-instructions|instructions\.md|gemini\.md|windsurf'. Registre quién escribió cada uno y cuándo cambió por última vez. Elija un repositorio en desarrollo activo como piloto.
2. Semana 2: consolidación. Fusione los archivos del piloto en un solo AGENTS.md aplicando la prueba «¿sería cierto esto en cualquier herramienta?». El /init de Claude Code lee los archivos existentes de Cursor y Copilot y, con CLAUDE_CODE_NEW_INIT=1 establecido, también AGENTS.md y los archivos de Windsurf y Cline, y propone un borrador consolidado; úselo como punto de partida, no como resultado. Escriba el CLAUDE.md delgado, el ajuste de Gemini y el script de sincronización de Copilot. Elimine .cursorrules y cualquier prosa duplicada.
3. Semana 3: piloto. Entre tres y cinco desarrolladores que, entre todos, usen cada herramienta que tenga el equipo. Cada uno ejecuta las comprobaciones de carga y el conjunto fijo de prompts, luego trabaja con normalidad durante una semana y registra cada instrucción que los agentes ignoraron o malinterpretaron. Corrija el archivo, no al desarrollador.
4. Semana 4: institucionalización. Añada entradas en CODEOWNERS, la verificación de sincronización en CI y una plantilla de repositorio. Decida qué pasa a la capa de organización: el CLAUDE.md administrado y los ajustes administrados de Claude Code, las Team Rules de Cursor, las instrucciones de organización de Copilot y las reglas de sistema de Windsurf son el lugar para las reglas que deben aplicarse a todos los repositorios. Después extienda el patrón a los siguientes repositorios, una pull request por cada uno.

Qué hacer al respecto

1. Inventaríe cada archivo de instrucciones en todos sus repositorios y nombre un propietario para cada uno.
2. Cree un AGENTS.md raíz que contenga comandos, estructura, convenciones, límites, reglas de seguridad y convenciones de PR, y manténgalo por debajo de 200 líneas.
3. Si existe un CLAUDE.md, haga que @AGENTS.md sea su primera línea y saque de él todo lo que no sea específico de Claude.
4. Establezca context.fileName para que incluya AGENTS.md en un .gemini/settings.json confirmado si alguien usa Gemini CLI.
5. Genere .github/copilot-instructions.md a partir de AGENTS.md y añada una verificación en CI que falle cuando esté desactualizado.
6. Elimine .cursorrules; conserve .cursor/rules/*.mdc para comportamiento exclusivo de Cursor con alcance por glob.
7. Añada archivos AGENTS.md anidados por paquete, autocontenidos, que nunca contradigan al raíz y repitan los límites críticos.
8. Traslade permisos, hooks y registros MCP a los ajustes de cada herramienta e imponga las reglas que importan con reglas de denegación y CI.
9. Busque secretos en todos los archivos de instrucciones, elimínelos y añada una regla de denegación para las lecturas de .env.
10. Añada los archivos a CODEOWNERS, ejecute /doctor prompt-audit antes de fusionar cambios y haga una prueba de humo en cada herramienta después de cada cambio.

Preguntas frecuentes

¿Cuál es la diferencia entre AGENTS.md y CLAUDE.md? AGENTS.md es el archivo neutral respecto al proveedor, administrado por la Agentic AI Foundation bajo la Linux Foundation y leído por Codex, Cursor, los agentes de Copilot, Gemini CLI y Windsurf. CLAUDE.md es el archivo propio de Claude Code, con importaciones @path, una capa de política administrada, CLAUDE.local.md y reglas con alcance por ruta que el formato compartido no tiene. Las convenciones compartidas van en AGENTS.md; un CLAUDE.md breve lo importa y añade instrucciones específicas de Claude.

¿Claude Code lee AGENTS.md? Sí, desde la v2.1.277, pero solo cuando no existe ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo ni por encima de él. Con ambos archivos presentes lee únicamente CLAUDE.md, a menos que Project instructions esté establecido en claude-md-and-agents-md. La solución portable es una importación @AGENTS.md en la primera línea de CLAUDE.md.

¿Debo usar .cursorrules o .cursor/rules? Use .cursor/rules/*.mdc o un AGENTS.md sencillo. La documentación actual de Cursor cubre las reglas de proyecto .mdc, las Team Rules y AGENTS.md en la raíz y en subdirectorios; ya no documenta .cursorrules.

¿GitHub Copilot lee AGENTS.md? El agente en la nube de Copilot, la revisión de código en GitHub.com, Copilot Chat en VS Code y Copilot CLI sí. Copilot Chat en GitHub.com, en Visual Studio y en los IDE de JetBrains no lo lee y depende de .github/copilot-instructions.md, así que genere ese archivo a partir de AGENTS.md.

¿Cómo funcionan los archivos AGENTS.md anidados en un monorepo? La especificación dice que el archivo más cercano gana y que las indicaciones explícitas prevalecen sobre todo lo demás. Codex concatena de la raíz hacia abajo con más peso para los archivos cercanos y se detiene a los 32 KiB por defecto; Cursor combina los archivos anidados con los padres; Windsurf les aplica automáticamente un alcance por glob; Copilot aplica el archivo más cercano. Redacte los archivos anidados de modo que nunca contradigan al raíz.

Si su equipo también está empaquetando comportamiento reutilizable de agentes y no solo instrucciones, la guía de gh skill para GitHub CLI explica cómo se instalan y fijan los skills en Copilot, Claude Code, Cursor, Codex y Gemini CLI; la misma disciplina de fuente única se aplica allí.

¿Necesita un par de manos adicional? Big Hat Group ofrece consultoría de desarrollo de aplicaciones para organizaciones de Estados Unidos y Canadá, desde una revisión de dos semanas de la configuración de agentes de codificación con IA hasta un despliegue multiagente completo en todos sus repositorios. Reserve una llamada de descubrimiento para hablar de su entorno.

Fuentes

• How Claude remembers your project (CLAUDE.md, imports, rules, AGENTS.md), documentación de Claude Code
• Settings files and precedence, documentación de Claude Code
• Set up Claude Code in a monorepo or large codebase, documentación de Claude Code
• AGENTS.md specification, Agentic AI Foundation
• Custom instructions with AGENTS.md, documentación de OpenAI Codex
• Adding repository custom instructions for GitHub Copilot, GitHub Docs
• Support for custom instructions in GitHub Copilot, GitHub Docs
• Rules, documentación de Cursor
• Provide context with GEMINI.md files, documentación de Gemini CLI
• Rules and memories, documentación de Devin Desktop (Windsurf)