Patrones de AGENTS.md: Qué realmente 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 nomenclatura, listas de verificación para revisión de código, procedimientos de despliegue y principios arquitectónicos. El agente ignoró la mayor parte. No porque las instrucciones estuvieran mal, sino porque eran documentación, no operaciones.

La distinción importa más que cualquier patrón específico en este artículo. AGENTS.md es política operativa para un agente de IA, no un README para humanos. El agente no necesita entender por qué utiliza conventional commits. Necesita saber el comando exacto que debe ejecutar y cómo se ve el estado “terminado”.

TL;DR

La mayoría de los problemas con AGENTS.md provienen de escribir documentación para humanos en lugar de operaciones para agentes. Los archivos efectivos son basadas en comandos (invocaciones exactas, no descripciones), organizadas por tareas (secciones de codificación, revisión, lanzamiento) y con definición de cierre (criterios explícitos de “terminado”). Anti-patrones que se ignoran de forma confiable: párrafos en prosa, directivas ambiguas (“tenga cuidado”) y prioridades contradictorias. AGENTS.md es un estándar abierto adoptado por más de 60.000 proyectos ¹ y funciona con Codex, Cursor, Copilot, Amp, Windsurf y más ².

Contexto: AGENTS.md está administrado por la Agentic AI Foundation bajo la Linux Foundation ³, con miembros platino que incluyen Anthropic, Google, Microsoft y OpenAI. Este artículo cubre patrones prácticos. Para configuración específica de Codex, consulte la guía de Codex. Para el equivalente de Claude Code (CLAUDE.md), consulte la guía de Claude Code.

Qué se ignora

Estos patrones producen de forma confiable ningún cambio observable en el comportamiento del agente. Identifiqué cada uno ejecutando tareas idénticas con y sin la instrucción presente, y luego comparando la precisión de finalización de tareas en más de 10 ejecuciones por patrón. El análisis de GitHub de 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, no por limitaciones técnicas” ¹¹. Los patrones a continuación no lograron mejorar la precisión de ninguna manera medible.

Párrafos en 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 lee esto, lo representa como una preferencia vaga y procede a escribir código sin pruebas. No hay instrucción accionable — ningún comando que ejecutar, ningún umbral que cumplir, ninguna definición de “debidamente 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. “Donde sea posible” no es una condición de activación. “Con elegancia” no es una especificación de comportamiento. Esto se lee como orientación de humano a humano, no como instrucciones para agentes. Compare con lo que funciona: “Ejecute alembic check antes de aplicar migraciones. Aborte si falta la ruta de degradación.”

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 satisfacer las cuatro simultáneamente. Cuando las instrucciones entran en conflicto sin un orden explícito de prioridad, el modelo omite los pasos de verificación y se apresura a la generación de código. La investigación de ICLR 2026 (AMBIG-SWE) encontró que los agentes “adoptan por defecto un comportamiento no interactivo sin estímulo explícito” — procediendo en silencio en lugar de hacer preguntas de clarificación, lo que redujo las tasas de resolución del 48,8% al 28% ¹². Corrija las instrucciones conflictivas numerando las prioridades: “Prioridad 1: Las pruebas pasan. Prioridad 2: Menos de 5 minutos. Prioridad 3: Enviar rápido.”

Guías de estilo sin cumplimiento

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

A menos que incluya el comando exacto de linting que hace cumplir el estilo (ruff check --select D o pylint --rcfile=.pylintrc), el agente no tiene mecanismo para verificar su propio cumplimiento. El patrón aquí es universal: las instrucciones sin comandos de verificación son sugerencias, no reglas.

Qué funciona

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

Instrucciones basadas 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 son inequívocos. El agente sabe exactamente qué ejecutar, qué argumentos pasar y puede verificar el éxito comprobando el código de salida. Cada instrucción en su AGENTS.md debería responder a la pregunta: “¿Qué comando demuestra que esto se hizo correctamente?”

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: el agente reporta “terminado” sin verificar. Cuando “terminado” se define como códigos de salida específicos, el agente ejecuta cada verificación antes de reportar la finalización. Sin esta definición, “terminado” significa “creo que terminé” — una fuente común 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>"`

Los archivos organizados por tarea permiten al agente seleccionar instrucciones relevantes según lo que está haciendo actualmente. Las listas planas obligan al agente a analizar cada instrucción independientemente del contexto. El prefijo “When…” se mapea directamente a cómo el agente razona sobre el contexto de la tarea.

Reglas de escalación

## 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 escalamiento, los agentes recurren a soluciones alternativas cada vez más creativas cuando se bloquean — eliminando archivos de bloqueo, omitiendo verificaciones o ignorando fallos silenciosamente. La lista de “Never” es tan importante como las rutas de escalamiento. Prohibir explícitamente los patrones de recuperación destructivos previene los peores modos de fallo.

Alcance por directorio para 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 del nivel raíz se concatenan con los archivos más profundos. Las herramientas recorren desde la raíz del proyecto hasta el directorio de trabajo actual, combinando cada AGENTS.md encontrado en la ruta ⁴. El propio repositorio de Codex de OpenAI usa 88 archivos AGENTS.md separados para su monorepo — uno por servicio y paquete ⁴.

En Codex, también puede usar AGENTS.override.md en cualquier nivel para reemplazar (no extender) las instrucciones del padre ⁴. El mecanismo de override 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 override: Congelamiento de lanzamientos, modo de incidentes o cualquier servicio con restricciones de seguridad que superen las configuraciones predeterminadas del proyecto.

Compatibilidad entre herramientas

AGENTS.md es adoptado por más de 60.000 proyectos ¹ y reconocido por todas las principales herramientas de codificación con IA. Así es como el mismo archivo se comporta en diferentes ecosistemas:

Si su equipo usa múltiples herramientas: Escriba AGENTS.md como la fuente canónica. Agregue archivos específicos de herramientas (CLAUDE.md, .cursorrules) que importen o repliquen las secciones relevantes. No mantenga conjuntos paralelos de instrucciones que se desincronicen.

Orden de escritura: Qué agregar primero

Si está escribiendo un AGENTS.md desde cero, agregue las secciones en este orden de prioridad. Cada capa se construye sobre la anterior:

1. Comandos de compilación y pruebas — el agente los necesita antes de poder hacer algo útil
2. Definición de terminado — previene falsas finalizaciones de “creo que terminé”
3. Reglas de escalación — previene soluciones destructivas cuando el agente se bloquea
4. Secciones organizadas por tarea — reduce el análisis de instrucciones irrelevantes por tarea
5. Alcance por directorio (solo monorepos) — mantiene las instrucciones del servicio aisladas

Omita las preferencias de estilo hasta que las primeras cuatro estén funcionando. La mayoría de los archivos AGENTS.md fallan porque comienzan con orientación de estilo y nunca llegan a los comandos.

Probando su AGENTS.md

Verifique que el agente realmente lee y sigue sus 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 definitiva: Pida al agente que explique sus comandos de compilación. Si no puede reproducirlos textualmente, las instrucciones no se están leyendo o son demasiado extensas para retener en el contexto. Los archivos AGENTS.md largos se truncan por las ventanas de contexto — mantenga cada sección por debajo de 50 líneas y coloque las instrucciones más críticas al principio.

Preguntas frecuentes

¿Qué tan largo debería ser un archivo AGENTS.md?

Mantenga cada sección por debajo de 50 líneas y el archivo total por debajo de 150 líneas ¹³. Codex impone un límite predeterminado de 32 KiB (project_doc_max_bytes) ⁴. Los archivos largos se truncan por las ventanas de contexto, así que coloque las instrucciones más críticas al principio — comandos y definiciones de cierre antes que las preferencias de estilo.

¿AGENTS.md reemplaza los archivos de instrucciones específicos de cada herramienta?

No. AGENTS.md funciona junto con CLAUDE.md, .cursor/rules y otros archivos específicos de herramientas. Escriba AGENTS.md como la fuente canónica, luego replique las secciones relevantes a los archivos específicos de cada herramienta. Los patrones en AGENTS.md (basadas en comandos, definición de cierre) funcionan en cualquier archivo de instrucciones independientemente de la herramienta.

¿Qué pasa si el agente ignora mi AGENTS.md?

Pruebe pidiendo al agente que explique sus comandos de compilación. Si no puede reproducirlos textualmente, el archivo es demasiado extenso (el contenido se desplaza fuera del contexto), demasiado vago (el agente no puede extraer instrucciones accionables) o no se está descubriendo (verifique la ubicación del archivo y la documentación de la herramienta). El análisis de GitHub de 2.500 repositorios encontró que la vaguedad — no las limitaciones técnicas — causa la mayoría de los fallos ¹¹.

Puntos clave

Para desarrolladores individuales:

• Reemplace la prosa con comandos. Cada instrucción debería ser verificable ejecutando algo.
• Defina el cierre explícitamente. “Terminado” significa códigos de salida específicos, no sensaciones.
• Pruebe su AGENTS.md pidiéndole al agente que lo recite. Lo que no puede recitar, no lo seguirá.

Para equipos:

• Use AGENTS.md como la única fuente de verdad. Replique a archivos específicos de herramientas, no mantenga copias paralelas.
• Organice por tarea (codificación, revisión, lanzamiento), no por categoría (estilo, pruebas, despliegue).
• Incluya reglas de escalamiento. Sin ellas, los agentes bloqueados improvisan de maneras que no le gustarán.
• Defina el alcance por directorio en monorepos. Las reglas específicas del servicio no deberían contaminar las instrucciones globales.

Referencias