AGENTS.md en WordPress: qué es y por qué lo usamos

Desde hace unos meses, cada plugin que sale de CLOSE lleva un archivo AGENTS.md en la raíz. No es un capricho ni una moda por la IA: es la forma de que cualquier agente de código Claude, Codex, Cursor u otros entiendan el proyecto antes de tocar una línea de código, en vez de improvisar cada vez que les pides algo.

Qué es el archivo AGENTS.md

Es un archivo Markdown, normalmente en la raíz del repositorio, que le explica a un asistente de IA cómo es tu proyecto: qué hace, cómo está organizado, qué estándares de código sigue, cómo se testea y cómo se hace un release. Cursor, Copilot, Claude Code y otros asistentes lo leen automáticamente al empezar a trabajar en el repo.

Claude Code no le da soporte 100%, por lo que te recomiendo que añadas este archivo CLAUDE.md que referencie al prinicipal:

@AGENTS.md

La diferencia con un README es a quien va dirigido. El README lo lee una persona que quiere saber qué es el plugin y cómo instalarlo. El AGENTS.md lo lee un modelo que va a escribir código en tu proyecto, así que necesita otro tipo de información: comandos exactos, rutas de archivos reales, reglas de nomenclatura, qué hooks existen ya y qué no debe reinventar.

Sin ese archivo, cada sesión con la IA empieza de cero. Le explicas otra vez qué prefijo llevan las funciones, qué text domain usa el plugin, cómo se lanzan los tests… y aun así se le suele escapar algo, porque no tiene memoria entre sesiones y tiene que adivinar mirando el código.

Qué resuelve en la práctica

El AGENTS.md cumple tres funciones que antes hacíamos a mano, explicando lo mismo una y otra vez:

• Fija el objetivo del planning. Cuando la IA arma un plan de tareas para una función nueva, ya sabe qué archivos tocar, qué patrón de arquitectura respetar y qué no debe romper.
• Impone los estándares de código. Si el proyecto sigue WordPress Coding Standards con un ruleset de PHPCS concreto, el archivo lo dice explícitamente. La IA deja de proponer código que luego el linter rechaza.
• Documenta la estructura real. No es un boilerplate genérico de «así se hace un plugin de WordPress». Cada AGENTS.md refleja el proyecto tal cual es: sus hooks, sus clases, sus carpetas de tests.

Esto último es clave. Un AGENTS.md genérico, copiado de otro proyecto, es casi peor que no tener ninguno: da una falsa sensación de contexto y la IA acaba inventando comandos o rutas que no existen en tu repo.

Qué estructura suele llevar

En nuestros proyectos, el archivo se organiza más o menos así:

1. Resumen del proyecto — qué hace el plugin, en un párrafo, y con qué se integra (CRMs, pasarelas de pago, APIs externas).
2. Comandos de desarrollo — los scripts reales de composer.json y package.json: lint, tests, análisis estático, build. Nada de comandos inventados; si no existe en el repo, no va en el archivo.
3. Arquitectura — puntos de extensión (apply_filters, do_action), convenciones de clases, cómo funciona la carga condicional si el plugin es un «hub» con varias integraciones.
4. Estándares de código — sacados del .phpcs.xml.dist real del proyecto, con sus prefijos y su text domain.
5. Tests — qué cubre cada carpeta y qué exige el CI para poder mergear.
6. Proceso de release — dónde se sube la versión, qué formato lleva el changelog del readme.txt, qué dispara el deploy.
7. CI/CD — qué hace cada workflow y con qué trigger.

Si el plugin no tiene, por ejemplo, integraciones externas, esa sección directamente no aparece. Mejor omitirla que rellenarla con contenido inventado que luego confunde más que ayuda.

Por qué añadimos dos secciones: release y test enforcement

Aquí es donde el archivo cambia el día a día. En vez de una sesión larga donde le pido a la IA «termina esto y súbelo», trabajo en dos bloques distintos, cada uno con su propia parte del AGENTS.md como referencia:

Sección de release. Repasamos qué cambios hay que meter para sacar la nueva versión: bump de versión en el archivo principal del plugin, actualización del changelog en el readme.txt, y que todo lo que toque el deploy workflow esté alineado con lo que describe la sección de release del archivo. Si el AGENTS.md dice que el deploy va a WordPress.org por SVN, la IA no se inventa un paso de despliegue distinto.

## Build a release

Actions for making a release:
- Update readme Stable Tag, and Version.
- Update Plugin Header and constant.
- Build the assets.
- Create release in GitHub.

Sección Test enforcement. Cada vez que se añade una funcionalidad nueva, se le indica al agente a que realice tests para dicha funcionalidad. Si en tu repositorio tienes configurado tests unitarios o de end to end, lo tendrá en cuenta.

## Test Enforcement

- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test` with a specific filename or filter.

Esta separación en dos ayuda a que se entienda bien dos partes importantes de un plugin.

Cómo lo estamos aplicando en CLOSE

Desde close.technology estamos metiendo esto en todos los proyectos donde trabajamos con IA para programar, precisamente porque queremos que el resultado sea consistente aunque cambie quién lanza el prompt. El archivo se genera inspeccionando el repo real (composer.json, workflows de CI, ruleset de PHPCS) en vez de partir de una plantilla genérica, y se revisa contra la realidad del proyecto antes de darlo por bueno: que los comandos existan, que las rutas existan, que el proceso de release descrito coincida con lo que hace de verdad el workflow de deploy.

El resultado es menos tiempo explicando lo mismo cada sesión y menos código que hay que corregir después porque no seguía el estándar del proyecto.

Si gestionas plugins de WordPress y trabajas con asistentes de IA para programar, este archivo es de las cosas que más rentabilidad da por el tiempo que cuesta montarlo. Y si un asistente lo mantiene inspeccionando tu repo real en vez de rellenar una plantilla, mejor todavía: es la diferencia entre un archivo que sirve y uno que solo aparenta servir.