Buenas prácticas de AGENTS.md: cuánto debe medir, plantilla y ejemplos

AGENTS.md es un archivo Markdown en la raíz de un repositorio de código que le indica a los agentes de programación con IA cómo trabajar en ese proyecto: stack, comandos de compilación y prueba, estilo de código, restricciones de arquitectura y límites. La página agents.md lista más de 20 herramientas que lo leen, incluidas OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf, Devin, Aider y opencode. Claude Code también lo lee, aunque por defecto solo cuando el proyecto no tiene un CLAUDE.md.

Plantilla mínima de AGENTS.md (cópiala)

# AGENTS.md

## Project overview
Next.js 15 App Router, React 19, TypeScript, Tailwind CSS, Drizzle ORM.

## Setup
Install: `pnpm install`  ·  Env: copy `.env.example` to `.env.local`

## Build and test
Build: `pnpm build`  ·  Test: `pnpm test`  ·  Lint: `pnpm lint --fix`

## Code style
Functional components with hooks only. Named exports only.

## Boundaries
Never edit files in /generated/. Never commit .env or secrets.

Sustituye tu propio stack y comandos, mantenlo corto y agrega secciones solo cuando un agente cometa un error. La versión anotada más adelante explica qué va en cada sección.

El formato está definido en agents.md y mantenido en GitHub (agentsmd/agents.md). Más de 60.000 proyectos de código abierto lo utilizan, y ahora está bajo la tutela de la Agentic AI Foundation, parte de la Linux Foundation. Aun así, la mayoría de los archivos AGENTS.md son demasiado largos, demasiado vagos o generados por un LLM, lo que empeora al agente. Aquí te explicamos cómo escribir uno que funcione y siga funcionando.

Nuestro agente de programación generaba componentes de clase sin parar. Toda la base de código era React funcional con hooks. El README decía "React 19, functional components". La guía de contribución lo explicaba con detalle.

El agente no leyó el README. No sabe que debería hacerlo.

Entonces agregamos un archivo AGENTS.md con una sola línea en la sección de estilo: Always use functional components with hooks. Never use class components. Y un ejemplo de código que mostraba la forma correcta.

El problema desapareció de inmediato.

¿Trabajas con más de un agente? Lee cómo organizar AGENTS.md para múltiples agentes sin conflictos ni desviaciones.

¿Cuánto debe medir AGENTS.md?

Respuesta corta: menos de 100 líneas es el objetivo, 150 es la señal de alerta y 200 es el límite máximo que Anthropic establece para su propio equivalente. En la práctica, la mayoría de los buenos archivos tienen entre 30 y 80 líneas.

De dónde viene cada cifra (cada una mide algo distinto, verificado el 23 de octubre de 2026):

¿Por qué decimos menos de 100 si Anthropic dice 200? Porque cada línea se carga en cada sesión, cada línea cuesta tokens en cada ejecución y casi cada línea más allá de las primeras 50 es una regla que el modelo seguiría de todas formas. El equipo de la ETH de Zúrich descubrió que los resúmenes de repositorio —lo que los proveedores de modelos recomiendan incluir con más frecuencia— básicamente no servían de nada, porque los agentes leen la base de código directamente. Elimínalos y la mayoría de los archivos quedan muy por debajo de 100 líneas.

Dos limitaciones honestas. Primero: un estudio controlado de Damon McMillan de 2026 (arXiv:2605.10039, 1650 sesiones de Claude Code, 16.050 observaciones) descubrió que, para una única regla simple de estilo de código, ni el tamaño del archivo ni la posición de la regla ni dividir el archivo ni un archivo contradictorio en una carpeta adyacente producían una diferencia medible en el seguimiento. Lo que sí importaba era la tarea y cuánto había avanzado ya el agente en la sesión: cada función adicional que escribía se asociaba con aproximadamente un 5,6% menos de probabilidad de seguir la regla. La longitud, por tanto, no es mágica. Segundo: ese estudio probó una única regla trivial en modelos Claude. Los archivos reales contienen docenas de reglas que compiten por la atención, y ahí es exactamente donde entra en juego la advertencia de Anthropic sobre el seguimiento.

La lectura práctica: un archivo corto no arregla una tarea mal planteada, pero uno largo hace que cualquier tarea sea más cara y le da al agente más oportunidades de ignorar justo la regla que importa.

Señales de que tu AGENTS.md es demasiado largo:

• Explica por qué elegiste tu stack o describe la historia del proyecto.
• Contiene un árbol de directorios o una lista de dependencias que el agente podría leer directamente del repositorio.
• Incluye un procedimiento paso a paso (una checklist de lanzamiento, un runbook de migración). Eso pertenece a una skill que solo se carga cuando se necesita.
• Encuentras dos reglas que dicen cosas distintas sobre el mismo comportamiento.
• Claude Code te advierte al inicio, o Codex descarta en silencio los archivos que superan los 32 KiB.
• Ya no recuerdas por qué existe la mitad de las reglas.

Qué va en un AGENTS.md (y qué no)

El error común es tratar AGENTS.md como documentación. Explicaciones largas. Filosofía de arquitectura. Justificaciones de diseño. Historia del proyecto.

Tu agente no necesita saber por qué elegiste Next.js en lugar de Remix. Necesita saber que usas Next.js 15 con App Router y que el comando de prueba es pnpm test, no npm test.

Estas son las secciones que importan, en el orden en que deben aparecer:

Stack del proyecto (5 a 10 líneas)

Lenguaje, framework, dependencias clave, runtime. Sé concreto.

Bien: Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun

Mal: Esta es una aplicación web moderna construida con React y varias bibliotecas de soporte.

Comandos de compilación y prueba (5 a 10 líneas)

Comandos exactos con flags exactas. El gestor de paquetes importa. Los targets de compilación importan.

Bien: Build: bun run build. Test: bun test. Lint: bun run lint --fix. Deploy: bun run deploy:staging

Mal: Ejecuta los comandos habituales de compilación y prueba como se describe en el package.json.

Convenciones de estilo de código (10 a 20 líneas, con ejemplos)

Un ejemplo de código por convención vale más que tres párrafos de descripción. Esta es la enseñanza más importante de los archivos AGENTS.md eficaces. Mostrar, no contar.

Restricciones de arquitectura (5 a 15 líneas)

Reglas de estructura de directorios. Límites de módulos. Restricciones de importación. Dirección del flujo de datos.

Límites (5 a 10 líneas)

Qué no debe tocar nunca el agente. "Nunca hacer commit de secrets" fue la restricción útil más frecuente en el análisis de GitHub de más de 2500 archivos agents.md. Agrega: archivos generados, módulos legacy, archivos de configuración que no deben cambiar y directorios gestionados por otras herramientas.

Flujo de trabajo de Git (5 líneas)

Nombres de ramas, formato de mensajes de commit, convenciones de PR. Solo squash merge. Conventional Commits: feat:, fix:, chore:, docs:.

Qué dejar fuera

Los procedimientos de varios pasos (una checklist de lanzamiento, un runbook de migración) no pertenecen a un archivo que se carga en cada sesión. La documentación de memoria de Anthropic dice lo mismo sobre CLAUDE.md: muévelos a una skill que el agente solo carga cuando la tarea lo requiere. Nuestra guía Agent Skills vs. MCP explica dónde trazar esa línea, y la carga bajo demanda es una razón clave por la que las skills pueden reducir el uso de tokens.

Las conexiones de herramientas tampoco van aquí. Esos son servidores MCP configurados en la propia herramienta (ver qué es MCP). AGENTS.md puede decir cuándo usar una herramienta, no cómo conectarse a ella.

Las reglas que nunca deben romperse tampoco van aquí. AGENTS.md es orientación, no aplicación. Si algo debe ocurrir siempre antes de cada commit o nunca debe ocurrir, usa un pre-commit hook, un hook de Claude Code o una regla de permisos. El archivo puede explicar la regla; el hook la aplica.

El ciclo de vida de las reglas: agrégala cuando falle, bórrala cuando se aprenda

Este hábito mantiene un AGENTS.md corto durante años, no solo semanas.

1. Empieza con 30 a 50 líneas: stack, comandos, estilo de código con un ejemplo cada uno, límites.
2. Agrega una regla solo cuando un agente cometa un error más de una vez. Un error puede ser de la tarea; dos son una laguna en el archivo.
3. Formula la regla como una directiva con ejemplo, no como una explicación. "Money is Decimal, never float" vale más que un párrafo sobre precisión.
4. Prueba sin la regla cada pocas semanas o después de una actualización de modelo. Borra la línea y ejecuta el mismo tipo de tarea. Si el agente lo hace bien sin indicaciones, la regla es peso muerto. Los modelos más nuevos siguen por sí solos muchas convenciones que los más antiguos necesitaban que les escribieran.
5. Revisa el archivo completo cada trimestre, y en el mismo PR cuando cambie una convención.

Una prueba útil para cada línea: ¿un desarrollador competente que nunca haya visto este repositorio cometería este error? Si no, bórrala. Estás pagando tokens para predecirle al modelo sus propios valores predeterminados.

Las reglas contradictorias hacen más daño que las duplicadas

Una regla duplicada desperdicia unos pocos tokens. Una contradicción hace que el comportamiento del agente sea impredecible, porque tiene que elegir un lado y tú no controlas cuál.

Anthropic lo dice directamente en su documentación de memoria: "Si dos instrucciones se contradicen, Claude puede elegir una de forma arbitraria." Esto aplica entre archivos también: tu archivo raíz, un archivo de subdirectorio, un archivo global personal y cualquier archivo de reglas terminan en el mismo contexto.

Dónde se esconden las contradicciones:

• Un archivo raíz que dice "usa Jest" y el archivo de un paquete que dice "usa Vitest" sin aclarar que eso es solo para ese paquete.
• Tu archivo global personal (~/.codex/AGENTS.md o ~/.claude/CLAUDE.md) con una regla específica del proyecto que es incorrecta en otros repositorios.
• Una regla antigua que nunca se borró después de una migración ("use the v1 API client").
• Una regla y su excepción en secciones distintas.

Cómo encontrarlas:

• Ejecuta /doctor prompt-audit en Claude Code (versión 2.1.283 en adelante). La documentación de Anthropic lo describe como una comprobación que "encuentra instrucciones para modelos más antiguos, referencias a archivos o comandos inexistentes y archivos que se contradicen entre sí", y sugiere cambios sin modificar nada hasta que des tu aprobación. Por defecto cubre tus archivos CLAUDE.md, CLAUDE.local.md y AGENTS.md.
• En cualquier herramienta, puedes preguntarle al agente: "List every instruction you've been given about testing, and flag any two that conflict."
• Escribe las reglas de subdirectorios como especializaciones ("este paquete usa Vitest"), nunca como inversiones del archivo raíz.

Un matiz por precisión: el estudio de McMillan mencionado antes encontró que un archivo contradictorio en una carpeta adyacente no tenía efecto medible sobre una única regla trivial. Eso no hace que las contradicciones sean inofensivas. Significa que el daño surge cuando reglas compiten, y eso es exactamente lo que crea un archivo que crece sin control.

Los tres errores que dejan AGENTS.md inservible

Error 1: dejarlo escribir a un LLM

Es el más común y el más dañino. En el estudio de la ETH de Zúrich, los archivos generados por LLM redujeron el éxito en un 0,5% en SWE-bench Lite y en un 2% en AGENTbench, perdieron en 5 de 8 escenarios y añadieron entre 2,45 y 3,92 pasos extra por tarea. Los archivos escritos por desarrolladores funcionaron mejor (unos +4% en AGENTbench), aunque también costaron hasta un 19% más.

¿Por qué? Los LLM generan instrucciones genéricas y verbosas que dicen lo obvio. "Follow best practices for error handling." "Write clean, maintainable code." "Use descriptive variable names." Tu agente ya sabe todo eso.

Escribe tu AGENTS.md a mano. Si usas un agente para hacer un borrador, trátalo como el primer PR de un empleado nuevo: elimina todo lo genérico y conserva solo lo específico de tu proyecto.

Error 2: describir las convenciones en lugar de mostrarlas

Mal:

Use our custom error handling approach where errors bubble up through
the service layer and are caught by the global error handler rather
than being caught at individual function level.

Bien:

// Error handling: Let errors propagate. Do not wrap individual calls
// in try/catch. The global handler catches everything.

// CORRECT
async function getUser(id) {
  const user = await db.users.findById(id);
  return user;
}

// WRONG
async function getUser(id) {
  try {
    const user = await db.users.findById(id);
    return user;
  } catch (e) {
    logger.error(e);
    throw e;
  }
}

El ejemplo de código transmite al instante lo que tres párrafos de descripción no logran.

Error 3: no actualizarlo

Un AGENTS.md con nombres de tablas obsoletos, comandos descatalogados o restricciones de arquitectura superadas es peor que no tener ninguno. Lleva activamente al agente por el camino equivocado.

Actualízalo en el mismo PR en el que cambian las convenciones y sigue el ciclo de vida de reglas descrito arriba. Si un agente produce repetidamente la misma salida incorrecta, hay una laguna en tu archivo. Si produce la salida correcta sin la regla, hay una línea que borrar.

¿Realmente funciona AGENTS.md?

Sí, pero solo la variante escrita a mano y específica.

El escepticismo es legítimo. Si dejaste que un agente escribiera tu AGENTS.md, lo ejecutaste y no viste mejoras, eso es exactamente lo que predice la investigación. Los autores de la ETH de Zúrich descubrieron que los agentes siguen bien las instrucciones de estos archivos. El problema es que la mayoría de los archivos están llenos de instrucciones que no cambian nada.

Lo que funciona es acotado: instrucciones que le dicen al agente algo que no podría haber deducido de la base de código. Tu gestor de paquetes. Tu comando de prueba con las flags exactas. El único directorio que nunca debe tocar. La convención de tu base de código que parece inusual para un modelo entrenado con el código de todos los demás.

AGENTS.md vs CLAUDE.md vs .cursorrules (¿cuál necesitas?)

Empieza con AGENTS.md y añade archivos específicos de cada herramienta solo cuando necesites sus funciones especiales.

AGENTS.md tiene la compatibilidad más amplia. Más de 20 herramientas lo leen de forma nativa. Es el formato universal.

CLAUDE.md es el archivo propio de Claude Code. Trae funciones que AGENTS.md no tiene, como importaciones @path y archivos .claude/rules/ adaptados a tipos de archivo. Ya no lo necesitas para que Claude Code vea tu AGENTS.md (ver Cómo lee Claude Code el AGENTS.md más adelante), pero en cuanto existe un CLAUDE.md, Claude Code deja de leer AGENTS.md por defecto. Si mantienes ambos, haz que CLAUDE.md importe el archivo compartido:

@AGENTS.md

Mantén AGENTS.md como única fuente de verdad para todas las herramientas, y que CLAUDE.md contenga ese import más las personalizaciones de Claude que realmente necesites. Ten en cuenta que los imports organizan un archivo pero no lo reducen: la documentación de Anthropic señala que los archivos importados se cargan junto con el CLAUDE.md que los importa y por tanto cuentan en el mismo contexto. Un symlink de CLAUDE.md a AGENTS.md también funciona, pero Anthropic recomienda el import si alguien del equipo usa Windows, donde Git puede hacer checkout del symlink como un archivo de texto plano.

.cursorrules es específico de Cursor. Su característica especial es el frontmatter con globs de archivo que activa distintas instrucciones según el tipo de archivo. Si tu equipo usa Cursor y necesita reglas por tipo de archivo, agrégalas.

La mayor parte del contenido es idéntico en los tres archivos. Los comandos de compilación, las reglas de arquitectura, las convenciones de prueba y los límites no cambian de una herramienta a otra. Una utilidad llamada rule-porter puede convertir entre formatos si hace falta.

Cómo lee Claude Code el archivo AGENTS.md

Claude Code lee AGENTS.md desde la versión 2.1.277 (publicada el 18 de septiembre de 2026), con una condición importante: por defecto lee AGENTS.md solo cuando no hay un CLAUDE.md. Esto viene directamente de la documentación de memoria de Anthropic:

Los detalles que suelen causar problemas:

• Qué cuenta como "un CLAUDE.md": un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o en cualquier directorio por encima. Tu ~/.claude/CLAUDE.md personal, el CLAUDE.md gestionado de tu organización y los archivos .claude/rules/ no cuentan y se siguen cargando junto a AGENTS.md.
• La trampa de CLAUDE.local.md: si creas un CLAUDE.local.md para tus notas personales sin commitear, Claude Code silenciosamente deja de leer el AGENTS.md de tu equipo.
• Qué se carga: cada AGENTS.md y .claude/AGENTS.md desde tu directorio de trabajo hacia arriba al iniciar la sesión, más el AGENTS.md de un subdirectorio cuando Claude abre un archivo ahí. En una sesión interactiva verás una línea como no CLAUDE.md found; AGENTS.md loaded: ....
• Qué se ignora: AGENTS.local.md, AGENTS.override.md y todo lo que esté dentro de un directorio .agents/. El archivo override es una convención de Codex, no de Claude Code.
• Cambiar el comportamiento predeterminado: escribe /config y establece Project instructions en claude-md-or-agents-md (el valor por defecto), claude-md-and-agents-md (leer ambos, con CLAUDE.md primero por directorio), claude-md (ignorar AGENTS.md) o managed-only.
• Advertencias de tamaño: Claude Code avisa al inicio y en /status cuando un archivo supera el límite recomendado y cuando varios archivos individualmente aceptables superan juntos un límite compartido.

Dos notas sobre versiones. Antes de v2.1.281 (23 de septiembre de 2026), las sesiones en Amazon Bedrock, Google Vertex AI, Microsoft Foundry, gateways LLM o con telemetría desactivada seguían leyendo solo CLAUDE.md. Y la primera sesión tras actualizar desde v2.1.276 o anterior puede que aún no recoja AGENTS.md; se cargará a partir de la siguiente sesión. Si usas una versión más antigua, el import @AGENTS.md dentro de un CLAUDE.md funciona en todas partes y nunca hace que el archivo se lea dos veces.

Si antes lo habías conectado a mano, el consejo de Anthropic es: mantén un CLAUDE.md que solo contenga @AGENTS.md (es inofensivo), o bórralo; reemplaza un CLAUDE.md que en palabras instruya a Claude a leer AGENTS.md por un import real; y elimina cualquier hook SessionStart que imprima AGENTS.md, porque ahora añade una segunda copia al contexto.

¿Claude Code no lee AGENTS.md? Las cuatro causas

Si Claude Code ignora tu AGENTS.md, casi siempre es por una de estas cuatro razones. Compruébalas en este orden. Todo lo que aparece aquí proviene de la documentación de memoria de Anthropic y del changelog de Claude Code, verificado el 23 de octubre de 2026.

1. El archivo está en el lugar o con el nombre equivocado. Al iniciar la sesión, Claude Code carga AGENTS.md y .claude/AGENTS.md desde tu directorio de trabajo y cualquier directorio por encima. Si inicias Claude en una carpeta superior al repositorio, el AGENTS.md del repo es un archivo de subdirectorio y no se carga al inicio. Inicia en la raíz del repo y llama al archivo exactamente AGENTS.md.

2. Un CLAUDE.md tiene prioridad. Lo más habitual es que el culpable sea un CLAUDE.local.md olvidado. Agrega @AGENTS.md al CLAUDE.md, o establece Project instructions en claude-md-and-agents-md en /config. Comprueba que la configuración no sea claude-md ni managed-only, porque ambas omiten AGENTS.md por completo.

3. Estás usando una versión con un bug ya corregido. Ejecuta claude --version. Antes de v2.1.281, las sesiones con Bedrock, Vertex, Foundry, gateway y sin telemetría solo leían CLAUDE.md. La v2.1.290 (5 de octubre de 2026) corrigió que el AGENTS.md de un subdirectorio no se añadiera cuando mencionabas un archivo de ese directorio con @. Actualiza Claude Code y abre una nueva sesión.

4. Es un archivo anidado que aún no se ha cargado. El AGENTS.md de un subdirectorio no se lee al inicio. Claude Code lo carga cuando Claude abre un archivo en ese directorio, y solo si dicho directorio no tiene su propio CLAUDE.md. Pon en el archivo raíz las reglas que siempre deben aplicarse.

Para confirmar qué se cargó, ejecuta /memory y busca la ruta de tu AGENTS.md.

¿AGENTS.md funciona con OpenAI Codex?

Sí. Codex lee AGENTS.md de forma nativa, y el mismo archivo funciona en Codex, Cursor, Gemini CLI y Claude Code sin modificaciones.

Las reglas de resolución de Codex están más estratificadas que las de la mayoría de herramientas. Según la guía de AGENTS.md de OpenAI para Codex, construye la cadena de instrucciones una vez por ejecución:

• Global: en tu home de Codex (~/.codex, o donde apunte CODEX_HOME), Codex lee AGENTS.override.md si existe y, si no, AGENTS.md. Solo se usa un archivo en este nivel.
• Proyecto: partiendo de la raíz del proyecto (generalmente la raíz de Git), desciende hasta tu directorio de trabajo actual. En cada directorio comprueba AGENTS.override.md, luego AGENTS.md, luego los nombres que hayas listado en project_doc_fallback_filenames, y toma como máximo un archivo por directorio.
• Fusión: los archivos se concatenan de raíz a hoja, de modo que los archivos más cercanos a tu lugar de trabajo quedan al final y anulan los anteriores.

Límite de tamaño. Codex omite los archivos vacíos y deja de agregar archivos en cuanto el tamaño total alcanza project_doc_max_bytes, que por defecto es 32 KiB. Esto aplica a toda la cadena, no por archivo. Puedes aumentar el valor, pero si estás cerca del límite, es mejor borrar líneas:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Verificar qué se cargó. Ejecuta codex --ask-for-approval never "Summarize the current instructions." en la raíz del repo. Codex reconstruye la cadena en cada ejecución (una vez por sesión en la TUI interactiva), así que no hay caché que limpiar cuando edites un archivo; solo reinícialo. Si esa prueba termina con stream disconnected before completion, es un error de conexión, no un problema del archivo de instrucciones.

Un aviso práctico. Codex ejecuta los comandos de compilación y prueba de tu AGENTS.md en su sandbox. Un comando incorrecto no genera un error útil; el agente lo ejecuta, ve que falla y rodea el obstáculo. Antes de confiar en un comando de tu AGENTS.md, ejecútalo tal cual en un terminal limpio.

Claude Code no lee AGENTS.override.md ni los nombres de archivo fallback de Codex. Si un repositorio sirve a ambos agentes, mantén las reglas comunes en archivos AGENTS.md normales.

AGENTS.md global vs a nivel de directorio

Hay tres alcances, y confundirlos es una fuente habitual del "¿por qué el agente ignora mis instrucciones?".

Global (personal). Un archivo en el directorio de configuración de tu herramienta, como ~/.codex/AGENTS.md. Se aplica a todos los proyectos que abras. Úsalo para preferencias que son tuyas, no del proyecto. No se commitea, así que tus compañeros nunca lo ven.

Raíz del repositorio. El archivo que la mayoría de la gente tiene en mente cuando dice "AGENTS.md". Está commiteado en el repo y lo comparte todo el equipo. Úsalo para reglas que aplican en todo el proyecto.

Subdirectorio. Amplía el archivo raíz para un directorio concreto. Úsalo cuando un directorio tiene reglas realmente distintas: un paquete con su propio comando de compilación, un directorio /mobile con un framework diferente.

La mayoría de los proyectos solo necesitan el archivo raíz. Si tu AGENTS.md raíz es demasiado largo, la solución es borrar líneas, no distribuirlas en directorios.

AGENTS.md anidado y global: cuál prevalece

Respuesta corta: el archivo más cercano al código que se edita gana, y lo que escribas en el chat supera cualquier archivo. Así lo expresan las FAQ de agents.md: "El AGENTS.md más cercano al archivo que se edita gana; los prompts explícitos del usuario en el chat anulan todo."

Para Claude Code, la documentación de Anthropic describe los archivos de instrucciones como concatenados, no como que se sobreescriben entre sí, y advierte que Claude puede elegir arbitrariamente cuando hay archivos contradictorios. En Claude Code "el más cercano gana" es una tendencia, no una garantía. Estas reglas aplican en todas partes:

• No contradigas, especializa. Un archivo de subdirectorio debe añadir reglas para ese directorio, no invertir las del archivo raíz.
• Preferencias personales en global, reglas del proyecto en el repo.
• Dilo en el prompt cuando sea importante. Una excepción puntual va en el prompt, no en un cambio de AGENTS.md.

¿Se debe commitear AGENTS.md en git?

Sí. AGENTS.md pertenece al control de versiones, junto al código que describe, en la raíz del repositorio. Cada colaborador y cada herramienta de IA lo lee desde ahí, y los cambios se revisan en el mismo PR que el cambio de convención que los originó.

Dos excepciones. Las preferencias personales van en tu archivo global, no en el repositorio. Y nunca incluyas secrets o URLs internas directamente; haz referencia a ellos desde .env o desde un archivo excluido por gitignore.

Seguridad: AGENTS.md es una superficie de inyección de prompts

El equipo de IA Red Team de NVIDIA demostró una inyección indirecta de AGENTS.md contra OpenAI Codex en la que una dependencia maliciosa secuestra el comportamiento del agente explotando el orden de precedencia de las instrucciones. El ataque requiere una dependencia ya comprometida, así que no hay razón para entrar en pánico con cada repositorio que clones. Pero demuestra que los archivos de instrucciones para agentes son contexto ejecutable y amplían la superficie de ataque de la cadena de suministro.

Las medidas de protección prácticas:

• Lee el AGENTS.md de cualquier repositorio que clones antes de ejecutar un agente sobre él.
• Trata AGENTS.md como un Makefile o un script post-install. Influye en comandos que se ejecutan en tu máquina.
• Revisa los cambios en AGENTS.md con el mismo cuidado que los cambios en la configuración de CI.
• Ejecuta los agentes en un sandbox cuando sea posible, para que una instrucción que pase desapercibida cause menos daño.

Más allá del código: AGENTS.md para agentes de negocio

La idea detrás de AGENTS.md surgió en repositorios de código, pero el principio se aplica a cualquier agente de IA: dale contexto breve y específico al inicio y trabajará mejor. La lección sobre la longitud también aplica. Un agente de negocio con una descripción de rol de dos páginas la sigue peor que uno con diez líneas claras.

Para los agentes de negocio (soporte, ventas, operaciones), la configuración equivalente abarca:

• Identidad: quién es el agente, su rol y tono.
• Capacidades: qué herramientas y aplicaciones puede usar.
• Restricciones: qué no debe hacer y qué acciones requieren aprobación humana.
• Nivel de confianza: solo borradores, actúa con aprobación o actúa de forma autónoma dentro de límites.
• Reglas de escalado: cuándo transferir a una persona.
• Formato de salida: cómo debe responder.

Para los agentes de programación, AGENTS.md es un archivo que escribes y mantienes. Para los agentes de negocio, esta configuración es más fácil de gestionar en un constructor visual. Así funciona el constructor de agentes de IA de BetterClaw: identidad, capacidades, restricciones, niveles de confianza (Internal, Specialist, Lead), reglas de escalado y formato de salida son campos en el constructor, versionados por ti, y no hay ningún archivo que puedas olvidar actualizar. Cada agente puede usar tu propia clave de modelo sin recargo. Prueba BetterClaw gratis: el plan Starter cuesta $19/mes, y Pro cuesta $49/mes para 5 agentes.

La plantilla anotada (cópiala y adáptala)

Aquí tienes un AGENTS.md mínimo y eficaz. Elimina las secciones que no apliquen. Un archivo más corto y correcto supera a uno extenso y genérico.

# Project Name

Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun.

## Commands

Build: `bun run build`
Test: `bun test`
Lint: `bun run lint --fix`
Single test: `bun test path/to/file.test.ts`

## Code Style

Functional components only. Never class components.
Use `const` exclusively. Never `var`, never `let` unless reassignment is needed.
Named exports only. Never default exports.

// Component example:
export const UserCard = ({ name, email }: UserCardProps) => {
  return <div className="p-4">{name}</div>;
};

## Error Handling

Let errors propagate. Do not wrap individual calls in try/catch.
The global error handler in middleware.ts catches everything.

## Architecture

/app         -> Routes and page components
/components  -> Shared UI components
/lib         -> Business logic and utilities
/db          -> Database schema and migrations

Never import from /app into /lib. Data flows one direction.

## Boundaries

Never modify files in /generated/.
Never commit .env or any file containing secrets.
The /legacy/ module uses sync code. Do not convert to async.

## Git

Squash merge only.
Conventional commits: feat:, fix:, chore:, docs:.
Branch format: type/short-description (e.g., feat/user-auth).

Son menos de 50 líneas, y cada una es específica. Si supera las 100, vuelve al ciclo de vida de reglas y empieza a borrar.

Ejemplos de AGENTS.md: tres archivos para tres tipos de proyecto

Los archivos reales son más cortos y más raros que las plantillas, porque solo contienen lo que los agentes de ese proyecto se equivocan una y otra vez. Estos tres son ejemplos representativos para mostrar ese rango, no copias del archivo de ningún repositorio en concreto.

Ejemplo 1: una aplicación web Next.js (12 líneas)

# Storefront

Next.js 15 App Router, TypeScript, Tailwind, Bun.

Build: `bun run build` | Test: `bun test` | Lint: `bun run lint --fix`

Server Components by default. Add `'use client'` only for event handlers or hooks.
Never fetch in a Client Component. Fetch in the page, pass data down as props.
Named exports only.

Never edit `/app/generated/`. It is regenerated on every build.
Never add a dependency without asking. This bundle is size-budgeted.

Por qué funciona: la regla de 'use client' es exactamente lo que un agente se equivoca de forma fiable en proyectos App Router, formulada como regla más excepción en una sola línea.

Ejemplo 2: un backend Python con FastAPI (16 líneas)

# Billing API

Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, uv.

Install: `uv sync` | Run: `uv run uvicorn app.main:app --reload`
Test: `uv run pytest -x` | Single test: `uv run pytest tests/test_invoices.py::test_name`

All DB access is async. Never use the sync Session. Never call `.commit()` in a
route handler; the dependency in `app/deps.py` handles the transaction boundary.

Pydantic models live in `app/schemas/`. SQLAlchemy models live in `app/models/`.
Never import a SQLAlchemy model into a route signature.

Schema changes require a migration: `uv run alembic revision --autogenerate -m "..."`.
Never edit an existing migration that has been merged.

Money is `Decimal`, never `float`. Amounts are stored in minor units (cents).

Por qué funciona: la regla del dinero. Una línea clara que previene toda una clase de errores caros de detectar.

Ejemplo 3: un monorepo (22 líneas)

# Platform monorepo

pnpm workspaces + Turborepo. Node 22.

apps/web    -> Next.js 15 storefront
apps/admin  -> Vite + React admin panel
packages/ui -> Shared component library
packages/db -> Drizzle schema and client

Always run commands from the repo root: `pnpm turbo build --filter=web`.
Never `cd` into a package and run `pnpm install` there.

Test: `pnpm turbo test` | Single app: `pnpm turbo test --filter=admin`

apps/* may import from packages/*. packages/* must never import from apps/*.
packages/ui must never import from packages/db. UI takes data as props.

Adding a dependency to a package: `pnpm add <pkg> --filter=<package-name>`.

Each app has its own AGENTS.md with framework-specific rules. This file covers
the workspace-level rules only.

Por qué funciona: las reglas de dirección de importación y la última línea, que le dice al agente que existen instrucciones más específicas más adelante en el árbol.

El hilo conductor: cada línea es una regla que un agente rompería sin indicaciones, formulada como directiva en lugar de explicación. Ninguna describe para qué sirve el proyecto y ninguna se acerca siquiera a las 100 líneas.

La versión corta

El mejor AGENTS.md es el que tu equipo mantiene de verdad. Empieza con 30 líneas. Agrega una regla cuando un agente cometa el mismo error dos veces. Bórrala cuando el agente lo haga bien sin indicaciones. Mantenlo por debajo de 100 líneas, busca contradicciones cada trimestre y aplica lo que sea crítico con un hook en lugar de con una frase.

Y si tus agentes son de negocio y no de programación, toda esa configuración pertenece a un constructor visual, no a un archivo Markdown. Construye tu agente en BetterClaw, o empieza ya con tu propia clave de modelo.

Preguntas frecuentes

¿Cuánto debe medir un archivo AGENTS.md?

Apunta a menos de 100 líneas y empieza a borrar cuando supere las 150. Anthropic recomienda mantener CLAUDE.md, el archivo equivalente, por debajo de 200 líneas porque "los archivos más largos consumen más contexto y reducen el seguimiento", y Codex deja de cargar archivos de instrucciones por defecto cuando el total supera los 32 KiB. Un estudio de la ETH de Zúrich encontró que los archivos de contexto aumentan los costos de inferencia en más del 20% de media sin mejorar el éxito en general, así que cada línea tiene un precio. En la práctica, la mayoría de los buenos archivos tienen entre 30 y 80 líneas.

¿Mi AGENTS.md es demasiado largo?

Probablemente, si explica por qué elegiste tu stack, contiene un árbol de directorios o una lista de dependencias, incluye procedimientos paso a paso, tiene dos reglas que se contradicen o ya no recuerdas por qué existe la mitad de las reglas. Claude Code también te avisa al inicio si un archivo supera el límite recomendado. Borra todo lo que el agente podría leer directamente del código y mueve los procedimientos a skills.

¿Qué es un archivo AGENTS.md?

AGENTS.md es un archivo Markdown en la raíz de un repositorio de código que da instrucciones específicas del proyecto a los agentes de programación con IA: comandos de compilación, estilo de código, restricciones de arquitectura, pruebas y límites. Más de 20 herramientas lo leen de forma nativa, incluidas OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf y Devin. Claude Code lo lee cuando el proyecto no tiene un CLAUDE.md. Más de 60.000 proyectos de código abierto lo utilizan, y está bajo la tutela de la Agentic AI Foundation en la Linux Foundation.

¿Qué hago si mi agente ignora una regla?

Primero comprueba que el archivo se haya cargado realmente (/memory en Claude Code, o pídele a Codex que resuma sus instrucciones). Luego hazla más concreta y agrega un ejemplo. Después busca una segunda regla que la contradiga. Si la regla nunca puede romperse, no dependas del archivo: usa un hook o una configuración de permisos que se aplique independientemente de lo que decida el agente.

¿Lee Claude Code el AGENTS.md?

Sí, desde la versión 2.1.277 de Claude Code (18 de septiembre de 2026). Por defecto lee AGENTS.md solo cuando no hay ningún CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo ni por encima. Para que lea ambos, establece Project instructions en claude-md-and-agents-md en /config, o escribe @AGENTS.md en tu CLAUDE.md. No lee AGENTS.override.md ni AGENTS.local.md.

¿Cómo se relacionan AGENTS.md, CLAUDE.md y .cursorrules?

AGENTS.md tiene la compatibilidad más amplia. CLAUDE.md es el archivo propio de Claude Code y añade importaciones @ y reglas por ruta. .cursorrules añade reglas específicas de Cursor basadas en globs. La mayor parte del contenido es idéntico en los tres. Empieza con AGENTS.md como única fuente de verdad y, si añades un CLAUDE.md, empiézalo con un import @AGENTS.md.

¿Debo usar un LLM para generar mi AGENTS.md?

No. En el estudio de la ETH de Zúrich, los archivos de contexto generados por LLM redujeron el éxito en 5 de 8 escenarios y añadieron entre 2,45 y 3,92 pasos extra por tarea. Los LLM escriben consejos genéricos que el agente ya sigue. Escríbelo a mano, o trata un borrador generado por IA como algo que vas a recortar, no a commitear.

¿Puedo usar el mismo AGENTS.md para Codex y Claude Code?

Sí. Codex lo lee de forma nativa; Claude Code lo lee mientras el proyecto no tenga un CLAUDE.md, y de lo contrario necesita un import @AGENTS.md en el CLAUDE.md. Ten en cuenta que Claude Code ignora el AGENTS.override.md de Codex. Por eso mantén las reglas compartidas en archivos AGENTS.md normales y ejecuta cada comando del archivo en un terminal limpio antes de confiar en él.

¿Commiteo AGENTS.md o lo agrego al .gitignore?

Commitéalo. Es documentación del proyecto y pertenece a la raíz del repositorio para que cada colaborador y cada herramienta lean las mismas instrucciones. Mantén las preferencias personales en el archivo global de tu herramienta y nunca incluyas secrets.

¿Se pueden aplicar los principios de AGENTS.md a los agentes de negocio?

Sí. La misma idea (contexto breve y específico sobre identidad, capacidades, restricciones y límites) aplica a cualquier agente de IA. Para los agentes de negocio, las secciones son identidad, capacidades, restricciones, niveles de confianza, reglas de escalado y formato de salida, y son más fáciles de gestionar en un constructor visual como BetterClaw que en un archivo Markdown.