Patrones de AGENTS.md: lo que de verdad cambia el comportamiento del agente

Mi primer AGENTS.md fue un pegado de 200 líneas de la guía de estilo de nuestro equipo. Incluía convenciones de nombres, listas de verificación para revisiones de código, procedimientos de despliegue y principios de arquitectura. El agente ignoró casi todo. No porque las instrucciones estuvieran mal, sino porque eran documentación y no operaciones.

Un AGENTS.md debe contener instrucciones centradas en comandos con invocaciones exactas, secciones organizadas por tarea (programación, revisión, publicación) y criterios explícitos de «terminado» que el agente pueda verificar. Escribe política operativa, no documentación para personas. Incluye los comandos de shell concretos, las configuraciones del linter y los comandos de prueba que el agente debe ejecutar. Evita los párrafos de prosa, las directivas ambiguas como «ten cuidado» y las prioridades contradictorias sin un orden explícito. AGENTS.md es un estándar abierto que han adoptado más de 60.000 proyectos y funciona en Codex, Cursor, Copilot y otras herramientas de agentes.

Esa distinción importa más que cualquier patrón concreto de este artículo. AGENTS.md es política operativa para un agente de IA, no un README para personas. El agente no necesita entender por qué usas commits convencionales. Necesita conocer el comando exacto que debe ejecutar y saber cómo se ve «terminado».

TL;DR

La mayoría de los problemas con AGENTS.md nacen de escribir documentación para personas en lugar de operaciones para agentes. Los archivos eficaces se centran en comandos (invocaciones exactas, no descripciones), se organizan por tarea (secciones de programación, revisión y publicación) y definen el cierre (criterios explícitos de «terminado»). Antipatrones que el agente ignora sin falta: párrafos de prosa, directivas ambiguas («ten cuidado») y prioridades contradictorias. AGENTS.md es un estándar abierto que han adoptado más de 60.000 proyectos ¹ y funciona en Codex, Cursor, Copilot, Amp, Devin Desktop y más ².

Contexto: AGENTS.md lo gobierna la Agentic AI Foundation, bajo el paraguas de la Linux Foundation ³, y entre sus miembros platino están Anthropic, Google, Microsoft y OpenAI. Este artículo cubre los patrones prácticos. Para la configuración específica de Codex, consulta la guía de Codex. Para el equivalente de Claude Code (CLAUDE.md), consulta la guía de Claude Code.

Lo que se ignora

Estos patrones no producen ningún cambio observable en el comportamiento del agente. Identifiqué cada uno ejecutando tareas idénticas con la instrucción presente y sin ella, y comparando después la precisión con que se completaba la tarea a lo largo de más de 10 ejecuciones por patrón. El análisis de GitHub sobre más de 2.500 repositorios con archivos AGENTS.md llegó a la misma conclusión: «La mayoría de los archivos de agente fallan porque son demasiado vagos» ¹¹. Los patrones siguientes no mejoraron la precisión de ninguna forma medible.

Párrafos de prosa sin comandos

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

El agente lo lee, lo guarda como una preferencia difusa y sigue escribiendo código sin pruebas. No hay ninguna instrucción accionable, ningún comando que ejecutar, ningún umbral que alcanzar, ninguna definición de «bien probado».

Directivas ambiguas

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

«Cuidado» no es una restricción. «Cuando sea posible» no es una condición de disparo. «Con elegancia» no es una especificación de comportamiento. Eso se lee como una recomendación de persona a persona, no como una instrucción para un agente. Compáralo con lo que sí funciona: «Ejecuta alembic check antes de aplicar migraciones. Aborta si falta la ruta de downgrade.»

Prioridades contradictorias

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

El agente no puede cumplir las cuatro a la vez. Cuando las instrucciones entran en conflicto sin un orden de prioridad explícito, el modelo se salta los pasos de verificación y se lanza a generar código. Una investigación presentada en ICLR 2026 (Ambig-SWE) halló que «sin una indicación explícita, los modelos casi nunca interactúan, ni siquiera ante entradas gravemente subespecificadas»: los agentes avanzan en silencio en vez de pedir aclaraciones, mientras que pedirles que interactúen mejora el rendimiento hasta un 74 % en tareas subespecificadas ¹². Arregla las instrucciones contradictorias numerando las prioridades: «Prioridad 1: las pruebas pasan. Prioridad 2: menos de 5 minutos. Prioridad 3: publicar rápido.»

Guías de estilo sin forma de exigirlas

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

Si no incluyes el comando de linting exacto que impone ese estilo (ruff check --select D o pylint --rcfile=.pylintrc), el agente no tiene forma de verificar su propio cumplimiento. El patrón es universal: una instrucción sin comando de verificación es una sugerencia, no una regla.

Lo que funciona

Estos patrones producen cambios consistentes y medibles en el comportamiento del agente.

Instrucciones centradas en comandos

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Los comandos no son ambiguos. El agente sabe con exactitud qué ejecutar y qué argumentos pasar, y puede verificar el éxito consultando el código de salida. Cada instrucción de tu AGENTS.md debería responder a esta pregunta: «¿Qué comando demuestra que esto se hizo bien?»

Definiciones de cierre

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Las definiciones de cierre explícitas eliminan el modo de fallo más común: que el agente reporte «terminado» sin haberlo verificado. Cuando «terminado» se define como códigos de salida concretos, el agente ejecuta cada comprobación antes de dar la tarea por cerrada. Sin esa definición, «terminado» significa «creo que ya está», una fuente habitual de errores introducidos por agentes.

Secciones organizadas por tarea

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

Un archivo organizado por tarea permite que el agente elija las instrucciones relevantes según lo que está haciendo en ese momento. Las listas planas lo obligan a analizar cada instrucción sin importar el contexto. El prefijo «Cuando…» se corresponde directamente con la forma en que el agente razona sobre el contexto de la tarea.

Reglas de escalada

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

Sin reglas de escalada, los agentes bloqueados recurren a rodeos cada vez más creativos: borran archivos de bloqueo, saltan comprobaciones o silencian los fallos. La lista de «nunca» pesa tanto como las rutas de escalada. Prohibir de forma explícita los apaños destructivos evita los peores modos de fallo.

Alcance por directorio en monorepos

AGENTS.md admite alcance jerárquico como una función central de la especificación ². Los archivos más cercanos al directorio de trabajo tienen precedencia:

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

Las instrucciones de la raíz se concatenan con las de los archivos más profundos. Codex recorre el camino desde la raíz del proyecto hasta el directorio de trabajo actual y combina cada AGENTS.md que encuentra por el camino ⁴; la especificación en sí define la precedencia del archivo más cercano, así que otras herramientas pueden resolver la jerarquía de otro modo ². El propio repositorio codex de OpenAI lo practica: distribuye un AGENTS.md anidado por debajo del de la raíz ⁴.

En Codex también puedes usar AGENTS.override.md en cualquier nivel para reemplazar (no ampliar) las instrucciones del nivel superior ⁴. El mecanismo de sustitución es específico de Codex; otras herramientas no lo implementan.

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

Cuándo usar la sustitución: congelaciones de versión, modo incidente o cualquier servicio con restricciones de seguridad que se impongan sobre los valores por defecto del proyecto.

Compatibilidad entre herramientas

AGENTS.md lo han adoptado más de 60.000 proyectos ¹ y lo reconoce cualquier herramienta seria de programación con IA. Así se comporta el mismo archivo en los distintos ecosistemas (tabla verificada en agosto de 2026):

Si tu equipo usa varias herramientas: escribe AGENTS.md como la fuente canónica. Agrega archivos específicos de cada herramienta (CLAUDE.md, .cursorrules) que importen o reflejen las secciones relevantes. No mantengas conjuntos de instrucciones paralelos que acaben divergiendo.

Orden de escritura: qué agregar primero

Si escribes un AGENTS.md desde cero, agrega las secciones en este orden de prioridad. Cada capa se apoya en la anterior:

1. Comandos de build y de pruebas: el agente los necesita antes de poder hacer nada útil
2. Definición de «terminado»: evita las falsas finalizaciones del tipo «creo que ya está»
3. Reglas de escalada: evitan los rodeos destructivos cuando el agente se atasca
4. Secciones organizadas por tarea: reducen el análisis de instrucciones irrelevantes en cada tarea
5. Alcance por directorio (solo monorepos): mantiene aisladas las instrucciones de cada servicio

Deja las preferencias de estilo para cuando los cuatro primeros puntos funcionen. La mayoría de los archivos AGENTS.md fallan porque empiezan con indicaciones de estilo y nunca llegan a los comandos.

Cómo probar tu AGENTS.md

Verifica que el agente lee y sigue de verdad tus instrucciones:

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

La prueba de fuego: pídele al agente que te explique tus comandos de build. Si no puede reproducirlos palabra por palabra, o no está leyendo las instrucciones o son demasiado extensas para retenerlas en contexto. Los archivos AGENTS.md largos los trunca la ventana de contexto: mantén cada sección por debajo de 50 líneas y coloca las instrucciones más críticas al principio.

Preguntas frecuentes

¿Qué extensión debe tener un archivo AGENTS.md?

Mi regla general: cada sección por debajo de 50 líneas y el archivo completo por debajo de 150. El principio de fondo viene de las recomendaciones de Marmelab sobre experiencia de agente: el archivo debe quedarse «corto y al grano» porque los agentes lo leen al comienzo de cada sesión ¹³; los números de líneas concretos son míos, no suyos. Codex impone por defecto un límite de 32 KiB (project_doc_max_bytes) ⁴. Los archivos largos los trunca la ventana de contexto, así que coloca al principio las instrucciones más críticas, los comandos y las definiciones de cierre, antes que las preferencias de estilo.

¿AGENTS.md sustituye a los archivos de instrucciones de cada herramienta?

No. AGENTS.md convive con CLAUDE.md, .cursor/rules y otros archivos propios de cada herramienta. Escribe AGENTS.md como fuente canónica y después refleja las secciones relevantes en los archivos específicos. Los patrones de AGENTS.md (centrados en comandos, con cierre definido) funcionan en cualquier archivo de instrucciones, sea cual sea la herramienta.

¿Y si el agente ignora mi AGENTS.md?

Pruébalo pidiéndole al agente que te explique tus comandos de build. Si no puede reproducirlos palabra por palabra, el archivo es demasiado extenso (el contenido queda fuera del contexto), demasiado vago (el agente no logra extraer instrucciones accionables) o no se está descubriendo (revisa su ubicación y la documentación de la herramienta). El análisis de GitHub sobre más de 2.500 repositorios halló que la mayoría de los archivos de agente fallan porque son demasiado vagos ¹¹.

Ideas clave

Para quien programa en solitario:

• Sustituye la prosa por comandos. Cada instrucción debería poder verificarse ejecutando algo.
• Define el cierre de forma explícita. «Terminado» son códigos de salida concretos, no sensaciones.
• Prueba tu AGENTS.md pidiéndole al agente que lo recite. Lo que no sepa recitar, no lo cumplirá.

Para equipos:

• Usa AGENTS.md como única fuente de verdad. Refléjalo en los archivos de cada herramienta en vez de mantener copias paralelas.
• Organiza por tarea (programación, revisión, publicación), no por categoría (estilo, pruebas, despliegue).
• Incluye reglas de escalada. Sin ellas, un agente bloqueado improvisa de formas que no te van a gustar.
• Delimita el alcance por directorio en los monorepos. Las reglas de un servicio no deberían contaminar las instrucciones globales.

Referencias