Un AGENTS.md ligero es un archivo de contexto escrito para orientar agentes de código, no para resumir todo el repositorio. Debe decirle a Codex, Claude Code y herramientas parecidas qué comandos importan, qué riesgos no pueden pasar y cuándo la tarea está lista para revisión.

En 2026, el sitio oficial de AGENTS.md dice que el formato aparece en más de 60.000 proyectos open-source (AGENTS.md, "A simple, open format for guiding coding agents", 2026). Esa adopción explica la urgencia: si el archivo se vuelve ruido de contexto, el agente obedece instrucciones que empeoran la tarea.

Resumen práctico

  • Escribe solo reglas que cambian una decisión del agente.
  • Coloca comandos de prueba cerca del paquete correcto.
  • Convierte feedback repetido de PR en reglas cortas.
  • Valida el archivo con tareas reales antes de ampliarlo.

Composición abstracta muestra capas de contexto conectadas a agentes de código sin texto visible.

¿Por qué AGENTS.md se volvió una disputa de contexto?

En 2026, el artículo "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" encontró costo medio de inferencia superior a 20% cuando se añadían archivos de contexto sin mejorar el éxito general de las tareas (arXiv, "Evaluating AGENTS.md", 2026). La disputa existe porque los agentes siguen instrucciones, incluso cuando esas instrucciones crean trabajo innecesario.

La respuesta no es abandonar AGENTS.md. La respuesta es dejar de usarlo como enciclopedia. El estudio observó que los agentes obedecen instrucciones, pero las vistas generales del repositorio ayudan poco cuando repiten lo que la búsqueda, las pruebas y los metadatos ya muestran.

En la práctica, un buen AGENTS.md se parece más a un contrato operativo que a documentación de producto. Dice cómo instalar dependencias, qué prueba valida el cambio, qué directorio tiene reglas especiales y qué tipo de cambio exige revisión humana.

Este texto continúa la conversación sobre context engineering para agentes de código. Allí, el foco era el presupuesto de prompt. Aquí, el foco es el archivo que entra al inicio de la sesión y moldea decisiones posteriores.

Cápsula citable: En 2026, AGENTS.md pasó de truco de prompt a superficie de ingeniería. El artículo de arXiv "Evaluating AGENTS.md" midió costo superior a 20% con archivos de contexto, así que el archivo debe registrar solo reglas que cambian ejecución, pruebas o revisión.

¿Qué entra en el archivo y qué queda fuera?

En 2026, la documentación de personalización de Codex recomienda mantener AGENTS.md pequeño y empezar solo con instrucciones importantes (OpenAI Developers, "Customization", 2026). Entra lo que evita errores repetidos; queda fuera lo que el agente puede descubrir leyendo el repositorio.

Incluye comandos que no son obvios. Si npm test falla sin Redis local, dilo. Si el paquete de pagos usa otro comando, coloca esa regla en el directorio de pagos. Si todo PR necesita prueba de contrato, escribe el criterio de listo.

Deja fuera árboles de carpetas, resúmenes largos de arquitectura y consejos genéricos de calidad. El agente puede usar rg, leer package.json, abrir workflows e inspeccionar pruebas. Repetir esas señales en el contexto inicial añade ruido.

Cuando una tarea cruza varias sesiones, uso RemoteCode como extensión de contexto para Claude Code y Codex en flujos agentic largos, sobre todo cuando quiero continuidad sin volcar todo el historial en el prompt principal. Es una herramienta mía, así que esta mención es editorial y contextual.

Una regla útil es simple: si una instrucción no cambia comando, límite, riesgo, estilo de patch o criterio de aceptación, probablemente pertenece a otro documento. AGENTS.md debe apuntar a ese documento solo cuando la tarea lo necesita.

¿Cómo escribir un AGENTS.md mínimo?

En 2026, la documentación de Codex dice que lee AGENTS.md desde el alcance global, la raíz del proyecto y los directorios hasta la carpeta actual, con un límite combinado controlado por project_doc_max_bytes (OpenAI Developers, "Custom instructions with AGENTS.md", 2026). Eso favorece instrucciones cortas y cercanas al código afectado.

Empieza con un archivo raíz pequeño. Después mueve reglas específicas a directorios. El servicio de pagos no debería obligar a un agente de frontend a cargar detalles de webhooks. Un paquete de design system no debería heredar reglas de migración de base de datos.

Un ejemplo suficiente:

# AGENTS.md

## Entorno
- Usa `npm ci` para instalar dependencias.
- Antes de editar TypeScript, ejecuta `npm run typecheck`.

## Criterios de listo
- Ejecuta la prueba más cercana al archivo modificado.
- Si cambia un contrato de API, actualiza la prueba de integración.
- Si no puedes ejecutar una prueba, explica el bloqueo en el resumen final.

## Límites
- No edites migraciones aplicadas sin revisión humana.
- No añadas dependencias de producción sin explicar impacto.

Observa que no hay mapa de carpetas. El archivo dice cómo trabajar, no intenta narrar el repositorio. Si el agente necesita contexto de arquitectura, apunta a un documento corto en vez de copiar todo el documento al contexto inicial.

Loop abstracto muestra agentes pasando por comandos, pruebas y correcciones sin texto visible.

Cápsula citable: Un AGENTS.md mínimo ayuda a Codex y Claude Code cuando registra comandos, criterios de listo y límites de permiso. La documentación de Codex expone project_doc_max_bytes para instrucciones combinadas de proyecto, lo que vuelve más seguro el alcance por directorio que un archivo raíz inflado.

¿Dónde encajan CLAUDE.md, MEMORY.md y skills?

En 2026, la documentación de Claude Code dice que MEMORY.md carga las primeras 200 líneas o 25 KB al inicio de la conversación, mientras que los archivos CLAUDE.md se cargan completos y funcionan mejor por debajo de 200 líneas (Claude Code Docs, "How Claude remembers your project", 2026). Eso cambia la arquitectura de contexto.

Usa CLAUDE.md para instrucciones persistentes que Claude Code debe ver siempre. Usa AGENTS.md cuando el objetivo es interoperabilidad con Codex, Cursor, Gemini CLI y otros agentes. Si el equipo usa varias herramientas, mantén una fuente canónica y crea puente cuando haga falta.

Usa memoria para aprendizaje operativo, no para política permanente. Un hallazgo de depuración puede empezar como memoria. Si se convierte en feedback repetido de PR, promueve la regla a AGENTS.md o CLAUDE.md en el directorio correcto.

Usa skills cuando la instrucción es grande, rara o procedural. En 2026, la documentación de skills de Codex dice que la lista inicial usa como máximo 2% de la ventana de contexto del modelo, u 8.000 caracteres cuando la ventana es desconocida, y solo carga el SKILL.md completo cuando se elige la skill (OpenAI Developers, "Agent Skills", 2026). Eso es progressive disclosure aplicado a agentes.

Esta separación combina con RAG de codebase vía MCP para agentes. AGENTS.md define cómo trabajar. MCP y skills entregan contexto bajo demanda. La memoria registra aprendizaje que todavía no es regla estable.

¿Cómo validar si el archivo ayuda o estorba?

En 2026, el artículo "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" analizó 10 repositorios y 124 pull requests; con AGENTS.md, observó runtime mediano 28,64% menor y 16,58% menos tokens de salida, con comportamiento de finalización comparable (arXiv, "On the Impact of AGENTS.md Files", 2026). El resultado opuesto al otro estudio muestra que el contenido del archivo importa.

Valida con tareas reales de tu repositorio. Usa correcciones pequeñas, refactors de riesgo medio y cambios que exigen pruebas. Ejecuta con y sin AGENTS.md. Compara tiempo, tokens, archivos leídos, pruebas ejecutadas, regresiones y calidad del resumen final.

La señal más importante es negativa: el archivo no debe hacer que el agente explore más de lo necesario. Si lee documentación amplia antes de cambiar una línea simple, hay exceso. Si ejecuta pruebas irrelevantes por una regla genérica, hay exceso.

Usa una rúbrica corta para PRs de agente:

Señal observada Interpretación Acción en AGENTS.md
Faltó la misma prueba otra vez. Falta una regla útil. Añadir comando cerca del paquete.
El agente leyó demasiados documentos. El ruteo es débil. Apuntar solo a fuentes prioritarias.
El patch tocó la capa equivocada. La frontera de módulo es débil. Registrar el límite del directorio.
El resumen final omitió riesgo. El criterio de listo es vago. Exigir evidencia y riesgo residual.

Esta validación conversa con evals de PR para agentes en CI. AGENTS.md orienta el comportamiento. El eval mide si ese comportamiento entregó suficiente prueba para el revisor.

Cápsula citable: Dos estudios de 2026 sobre AGENTS.md llegaron a señales distintas: uno midió costo superior a 20% sin ganancia general de éxito, otro midió runtime 28,64% menor en 124 PRs. La conclusión práctica es probar el archivo en tu propio repositorio antes de ampliarlo.

¿Cómo mantener AGENTS.md vivo sin convertirlo en depósito?

En 2026, Codex recomienda tratar AGENTS.md como loop de feedback: cuando el agente hace una suposición incorrecta, corrígela y pide actualizar el archivo para que futuras sesiones hereden la regla (OpenAI Developers, "Customization", 2026). El mantenimiento debe nacer de errores repetidos, no de ansiedad documental.

Revisa el archivo como código. Cada regla nueva debe responder a una falla observada: prueba olvidada, comando incorrecto, estilo de diff incompatible, riesgo de seguridad o feedback repetido en PR. Si nadie puede nombrar la falla, la regla no entra.

También elimina reglas. Cuando un comando se vuelve estándar del repositorio, la instrucción especial pierde valor. Cuando un paquete desaparece, borra el bloque. Cuando una skill o herramienta MCP cubre mejor un procedimiento, deja que AGENTS.md apunte a la herramienta.

Matriz abstracta muestra decisiones sobre contexto, pruebas y límites de agentes sin texto visible.

Para equipos con fan-out de subagentes, mantén la regla en el menor alcance útil. Un agente de revisión necesita criterios de riesgo. Un agente de patch necesita comando de prueba. Un agente de inventario necesita saber dónde buscar. Eso profundiza el patrón de fan-out de subagentes para migraciones.

Preguntas frecuentes sobre AGENTS.md ligero

¿AGENTS.md debe explicar toda la arquitectura?

No. En 2026, "Evaluating AGENTS.md" indicó costo medio superior a 20% cuando se añadían archivos de contexto sin mejora general de éxito. Explica solo excepciones, límites y comandos. Para arquitectura completa, apunta a documentos que el agente lee bajo demanda.

¿Codex y Claude Code pueden compartir el mismo archivo?

Sí, con cuidado. En 2026, el formato AGENTS.md declara compatibilidad con un ecosistema amplio y más de 60.000 proyectos open-source. Para Claude Code, puedes mantener puente con CLAUDE.md, pero evita duplicar reglas divergentes entre herramientas.

¿Cuál es el tamaño ideal de un AGENTS.md?

No hay tamaño universal. En 2026, Claude Code recomienda apuntar por debajo de 200 líneas para CLAUDE.md, mientras Codex expone project_doc_max_bytes para instrucciones combinadas de proyecto. Usa esos límites como alerta: cuanto mayor el archivo, más fuerte debe ser la evidencia.

¿Cuándo debo crear AGENTS.md por directorio?

Créalo cuando el subdirectorio tiene comando, riesgo o regla diferente. En 2026, la documentación de Codex dice que archivos más cercanos a la carpeta actual aparecen después en la cadena y pueden sobrescribir orientación anterior. Eso evita cargar reglas de backend en tareas de frontend.

¿Cómo sé que mi AGENTS.md mejoró el agente?

Mide en tareas reales. En 2026, un estudio con 10 repositorios y 124 pull requests asoció AGENTS.md con runtime 28,64% menor y 16,58% menos tokens de salida. Si tu archivo no reduce errores, lectura inútil o retrabajo, todavía no está listo.

Cierre

AGENTS.md no es un lugar para volcar contexto. Es un contrato pequeño para decisiones repetidas: instalar, probar, revisar, limitar herramientas y registrar excepciones. En agentes de código, buen contexto no es contexto grande. Es contexto que cambia la próxima acción.

Empieza pequeño, evalúa en CI y promueve solo reglas nacidas de errores reales. Luego conecta esto con tu harness de agentes para PRs confiables, tus evals de PR y las herramientas MCP que ya entregan contexto bajo demanda. Así el agente gasta menos atención en ruido y más atención en el patch.

Fuentes consultadas

  • AGENTS.md, "A simple, open format for guiding coding agents", recuperado en 2026-07-04, https://agents.md/
  • arXiv, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", recuperado en 2026-07-04, https://arxiv.org/abs/2602.11988
  • arXiv, "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents", recuperado en 2026-07-04, https://arxiv.org/abs/2601.20404
  • OpenAI Developers, "Custom instructions with AGENTS.md", recuperado en 2026-07-04, https://developers.openai.com/codex/guides/agents-md
  • OpenAI Developers, "Customization", recuperado en 2026-07-04, https://developers.openai.com/codex/concepts/customization
  • OpenAI Developers, "Agent Skills", recuperado en 2026-07-04, https://developers.openai.com/codex/skills
  • Claude Code Docs, "How Claude remembers your project", recuperado en 2026-07-04, https://code.claude.com/docs/en/memory
  • OpenAI Developers, "Best practices", recuperado en 2026-07-04, https://developers.openai.com/codex/learn/best-practices