Cómo Escribir Archivos AGENTS.md para Equipos de Desarrollo de APIs

Los agentes de codificación leen tu repositorio antes de escribir código, y el primer archivo que leen es AGENTS.md. Es la convención abierta que Codex CLI, Cursor, Aider, OpenHands y una lista creciente de otras herramientas acordaron para que un único archivo de contexto funcione en todos los agentes. Para los equipos de desarrollo de API, ese archivo es la diferencia entre un agente que ejecuta las pruebas correctas contra un servidor local real y uno que alucina endpoints y envía un cliente roto.

Esta guía cubre qué es AGENTS.md, por qué los equipos de API deberían tratarlo como código de producción, las secciones importantes para los repositorios que priorizan OpenAPI, ejemplos concretos y cómo mantenerlo actualizado a medida que la API evoluciona. Lo combinamos con Apidog al final para que el flujo de pruebas de contrato del agente se base en una especificación real.

En resumen

• AGENTS.md es un archivo Markdown simple en la raíz del repositorio que les dice a los agentes de codificación cómo navegar, construir, probar y desplegar código en tu proyecto.
• La convención es abierta y compatible con Codex CLI, Cursor, OpenHands, Aider, Claude Code y otras herramientas de agentes.
• Para los equipos de API, las secciones que más rinden son los comandos de construcción, la ruta de la especificación OpenAPI, los endpoints del servidor mock, los comandos de prueba de contrato, la configuración de autenticación y las zonas de "no tocar".
• Mantenlo corto. 200 a 400 líneas es suficiente. Si es más largo, el agente se saltará las partes importantes.
• Combínalo con una colección de Apidog para que el agente tenga tanto el contexto (AGENTS.md) como un contrato ejecutable (la especificación OpenAPI).

Qué es AGENTS.md realmente

AGENTS.md es un archivo Markdown que se confirma en la raíz de un repositorio. Los agentes de codificación lo buscan al primer contacto con la base de código y tratan su contenido como el informe autorizado sobre cómo funciona el proyecto. La convención comenzó dentro de Codex CLI de OpenAI y se publicó como un estándar abierto para que otras herramientas pudieran leer el mismo archivo. A partir de este año, Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody y varios agentes más pequeños lo leen.

Tres cosas lo hacen útil:

1. Un archivo, cada agente. Escribes el contexto una vez y cada agente en el conjunto de herramientas del equipo lo recoge. Sin desalineación de configuración por herramienta.
2. Markdown simple. Sin DSL, sin esquema, sin paso de construcción. Los ingenieros lo editan como cualquier otro documento.
3. Vive junto al código que describe. Cuando el script de construcción cambia, el archivo cambia en la misma PR. El 'diff' hace que el cambio sea visible para los revisores y para el agente.

El pariente más cercano es CLAUDE.md, que lee Claude Code de Anthropic. Ambos formatos se superponen en gran medida; muchos proyectos mantienen un AGENTS.md con un enlace simbólico a CLAUDE.md para que ambas herramientas funcionen sin configuración adicional. El equipo de Codex y Anthropic se han alineado públicamente para mantener los formatos compatibles en el futuro.

Por qué los equipos de desarrollo de API lo necesitan más que la mayoría

Los equipos de API se encuentran en una intersección incómoda: el código es pequeño, los contratos son grandes y las consecuencias de equivocarse en cualquiera de ellos son visibles para cada cliente descendente. Un agente que no sepa que la especificación reside en openapi.yaml reescribirá los tipos a partir de la forma de respuesta que recuerde de los datos de entrenamiento. Un agente que no conozca el comando de prueba de contrato confirmará código que compila pero rompe el pipeline del SDK del cliente.

Un AGENTS.md bien escrito para un repositorio de API hace cuatro cosas:

• Fija la especificación como fuente de verdad. Cada cambio comienza y termina con el esquema OpenAPI o GraphQL. El agente aprende a actualizar primero la especificación y luego a regenerar los tipos.
• Nombra los servidores locales. Los agentes que arrancan un servidor mock local o un servidor en vivo eligen la URL correcta para las pruebas, no un fragmento de Stack Overflow.
• Enumera los comandos de prueba por intención. "Ejecutar pruebas unitarias" no es lo mismo que "ejecutar pruebas de contrato" o "ejecutar pruebas de integración contra el entorno de staging".
• Señala rutas prohibidas. El código SDK generado, los wrappers de clientes de terceros y los archivos de migración a menudo parecen editables pero no lo son.

Cuando el archivo hace estas cuatro cosas, la salida del agente deja de parecerse a la de un desarrollador junior que se saltó el README y empieza a parecerse a la de un compañero de equipo.

La estructura que funciona para repositorios de API

AGENTS.md no tiene un esquema requerido. La comunidad ha establecido algunas secciones que aparecen en casi todos los archivos bien ajustados. Para un equipo de API, el orden a continuación es un buen valor predeterminado.

1. Resumen del proyecto (3-5 líneas)

Indica qué hace la API, quiénes son los consumidores y en qué lenguaje y framework se ejecuta el servidor. Sé objetivo.

# Proyecto: API de Pagos

Servicio interno de pagos para la línea de productos Acme. Los clientes son
móviles, web y backends de socios. El servidor es Go 1.23 sobre Echo, Postgres
17 para almacenamiento y una capa de idempotencia respaldada por Redis.

Este bloque le dice al agente qué lenguaje usar por defecto, qué modismos seguir y qué clientes se romperían si se envía una forma de respuesta incorrecta.

2. Comandos de inicio rápido

Cinco a diez comandos que el agente ejecutará constantemente. Siempre incluye el comando, nunca enlaces a una wiki.

## Comandos

| Intención | Comando |
|--------|---------|
| Instalar dependencias | `make deps` |
| Ejecutar servidor localmente | `make dev` (se enlaza a 127.0.0.1:8080) |
| Ejecutar pruebas unitarias | `make test` |
| Ejecutar pruebas de contrato contra el mock local | `make contract` |
| Lint | `make lint` |
| Regenerar clientes desde la especificación | `make codegen` |
| Aplicar migraciones | `make migrate` |

Si un comando necesita una variable de entorno para funcionar, pon el nombre de la variable de entorno junto a él. Los agentes son buenos exportando variables; son malos adivinando.

3. La sección de especificación OpenAPI / GraphQL

Esta es la sección más valiosa en un repositorio de API. Dile al agente dónde reside la especificación, cómo se relaciona la especificación con el código generado y en qué dirección fluyen las ediciones.

## Fuente de verdad

- La especificación está en `apis/payments/openapi.yaml`.
- Los clientes generados viven en `gen/clients/{go,ts,python}` y NO DEBEN ser editados a mano.
- El pipeline de generación es `make codegen`. Ejecútalo después de cada cambio en la especificación
  y confirma los clientes regenerados en la misma PR.
- Los cambios en la especificación fluyen: especificación -> `make codegen` -> actualizaciones del manejador del servidor ->
  pruebas de contrato -> despliegue.

Solo este bloque elimina una clase de error en la que los agentes editan el cliente generado para "corregir" una falta de coincidencia de tipos, la siguiente ejecución de codegen borra el cambio y la compilación se rompe misteriosamente dos días después.

4. Conexión del servidor mock y Apidog

Si utilizas servidores mock (y deberías hacerlo), nómbralos. Enumera las URL, la especificación de la que leen y cómo iniciarlos.

## Servidores locales

- Servidor real: `make dev` -> `http://127.0.0.1:8080`
- Servidor mock de Apidog: `make mock` -> `http://127.0.0.1:4010`
- El mock lee del mismo `openapi.yaml` y reproduce ejemplos guardados
  de la colección de Apidog en `apis/payments/apidog/`.

Aquí es donde Apidog se gana su lugar en el archivo. El servidor mock, la especificación y los ejemplos de solicitudes guardados forman un contrato que el agente puede ejecutar sin consumir llamadas en el backend real. Combínalo con la guía de pruebas de API sin Postman para el flujo de trabajo subyacente.

5. Autenticación y secretos

Dile al agente cómo se autentica la API y qué variables de entorno contienen qué. Nunca coloques secretos reales en el archivo.

## Autenticación

- La producción utiliza credenciales de cliente OAuth 2 emitidas por Auth0.
- El desarrollo local utiliza un token de desarrollo estático; exporta `DEV_TOKEN` desde `.env.local`.
- La colección de Apidog utiliza los mismos nombres de variables de entorno para que el mock y el
  cliente real se comporten de forma idéntica.
- Los tokens NO DEBEN ser confirmados; `.env.local` está en `.gitignore`.

6. Estrategia de pruebas

Clasifica las capas de prueba. Los agentes las ejecutarán en el orden en que las enumeres.

## Pruebas

1. `make test` para pruebas unitarias. Rápidas, se ejecutan en cada cambio.
2. `make contract` para pruebas de contrato OpenAPI contra el mock. Ejecutar antes
   de fusionar cualquier cambio en la especificación.
3. `make integration` para pruebas de extremo a extremo contra un servidor local con un
   Postgres real. Ejecutar antes de fusionar a main.
4. Las pruebas de resistencia en staging se ejecutan nightly a través de GitHub Actions; no es un comando local.

7. Lista de "no tocar"

El código generado, las dependencias de terceros y las migraciones casi siempre pertenecen aquí.

## No editar manualmente

- `gen/**` (regenerado por `make codegen`)
- `vendor/**` (gestionado por `go mod vendor`)
- `migrations/*.up.sql` después de la primera migración no aplicada
- Nombres de campos del esquema `apis/payments/openapi.yaml` sin la aprobación del propietario

8. Estilo de la casa

De tres a cinco reglas. Si son más, el agente elegirá la incorrecta.

## Convenciones

- Los errores devuelven JSON de problema RFC 7807; nunca cadenas simples.
- Usa snake_case en JSON, camelCase en Go, PascalCase en clientes TS.
  Codegen maneja el mapeo.
- Se requieren claves de idempotencia en todos los endpoints POST que crean recursos.
- Los nuevos endpoints requieren una prueba de contrato que ejercite tanto las rutas 200 como las 4xx.

Ejemplo concreto: un archivo de 90 líneas que cumple su función

La tentación es escribir 800 líneas. Resístete. El archivo a continuación cubre un servicio API real en 90 líneas de Markdown y es suficiente para que cualquier agente importante trabaje de manera productiva.

# Proyecto: API de Pagos

Servicio interno de pagos para la línea de productos Acme. Go 1.23, Echo,
Postgres 17, Redis para idempotencia. Los consumidores son móviles, web,
y backends de socios.

## Comandos

| Intención | Comando |
|--------|---------|
| Instalar | `make deps` |
| Ejecutar servidor | `make dev` |
| Pruebas unitarias | `make test` |
| Pruebas de contrato | `make contract` |
| Lint | `make lint` |
| Regenerar clientes | `make codegen` |
| Migrar DB | `make migrate` |

## Fuente de verdad

- Especificación: `apis/payments/openapi.yaml`
- Clientes generados: `gen/clients/{go,ts,python}` (no editar)
- Flujo de edición: especificación -> `make codegen` -> manejador -> pruebas de contrato -> despliegue

## Servidores locales

- Servidor real: `make dev` (`http://127.0.0.1:8080`)
- Mock de Apidog: `make mock` (`http://127.0.0.1:4010`)
- Colección Apidog: `apis/payments/apidog/`

## Autenticación

- Producción: credenciales de cliente OAuth 2 de Auth0.
- Desarrollo local: token estático `DEV_TOKEN` de `.env.local`.

## Orden de pruebas

1. `make test`
2. `make contract`
3. `make integration`

## No editar manualmente

- `gen/**`, `vendor/**`
- Migraciones aplicadas en `migrations/`
- Nombres de campos de la especificación sin aprobación del propietario

## Convenciones

- JSON de problema RFC 7807 para errores
- JSON snake_case, codegen maneja el mapeo de lenguajes
- Claves de idempotencia requeridas en creaciones POST
- Cada nuevo endpoint se entrega con una prueba de contrato

Eso es suficiente. Añade secciones solo cuando un agente cometa el mismo error dos veces.

Mantener el archivo actualizado

Un AGENTS.md obsoleto es peor que no tener ningún archivo. El agente lo creerá y enviará código basado en un comando de construcción que ya no funciona.

Tres hábitos lo mantienen actualizado:

1. Trátalo como código de producción. Los cambios pasan por la misma revisión que cualquier otra PR. Los revisores verifican que las listas de comandos coincidan con el `Makefile` real.
2. Intégralo en CI. Un script corto que analiza la tabla de comandos y ejecuta cada comando en una extracción nueva detecta la desalineación rápidamente. La mayoría de los equipos lo escriben en 30 líneas de Bash.
3. Actualízalo en la misma PR. Cuando añadas un nuevo comando de prueba, no prometas actualizar AGENTS.md más tarde. Actualízalo ahora. El costo son dos minutos; el costo de omitirlo son dos semanas de confusión del agente.

Apidog como el contrato de ejecución para tu AGENTS.md

AGENTS.md proporciona contexto al agente. La especificación OpenAPI le da el contrato. Apidog une ambos: lee la especificación, ejecuta un mock local en la URL listada en AGENTS.md, reproduce ejemplos de solicitudes guardados para pruebas y permite al agente ver respuestas reales sin consumir créditos en el backend en vivo.

El patrón que funciona:

• Confirma apis/<service>/openapi.yaml y apis/<service>/apidog/ (la colección exportada).
• Enumera la URL del mock y el comando make mock en AGENTS.md.
• Los agentes ejecutan make contract para pruebas rápidas contra ejemplos guardados.
• Cuando la especificación cambia, el agente regenera los clientes, ejecuta el conjunto de contratos y solo entonces interactúa con el servidor en vivo.

Para una descripción más detallada del flujo de trabajo del mock de Apidog con una API real, la guía de la API DeepSeek V4 cubre el mismo patrón aplicado a una API de modelo en lugar de una API de servicio.

Errores comunes que cometen los equipos de API

Después de revisar docenas de estos archivos, aparecen los mismos cinco problemas:

1. Enlazar en lugar de listar. "Ver la wiki para los comandos de construcción." El agente no navega por la wiki. Incluye los comandos en línea.
2. Prosa con sabor a marketing. "Nuestra plataforma API de clase mundial potencia..." El agente no necesita un discurso. Expón los hechos.
3. Comandos obsoletos. Un comando que dejó de funcionar en marzo sigue en el archivo en abril. Integra CI para detectarlo.
4. Falta la sección de especificación. El bloque más útil. Inclúyelo siempre.
5. No hay lista de "no tocar". El agente edita el código generado. La siguiente ejecución de codegen borra la edición. La compilación se rompe. Repetir.

Si quieres una base para empezar, copia el ejemplo anterior en tu repositorio, edita el resumen del proyecto y ajusta la tabla de comandos. Puedes entregar un archivo utilizable en 20 minutos.

Preguntas frecuentes

¿Es AGENTS.md lo mismo que CLAUDE.md? Los formatos son compatibles. La mayoría de los equipos mantienen uno de ellos como fuente de verdad y enlazan simbólicamente el otro. Anthropic y OpenAI se han alineado públicamente para mantener las convenciones interoperables.

¿Dónde debo colocar el archivo? Siempre en la raíz del repositorio. Algunos agentes también leen archivos AGENTS.md anidados dentro de subdirectorios, útiles para monorepos. Comienza con un archivo a nivel de raíz y añade archivos en subdirectorios solo cuando un único archivo raíz se vuelva demasiado largo.

¿Qué tan largo debe ser? Entre 200 y 400 líneas es lo ideal. Más allá de eso, los agentes empiezan a saltarse secciones. Si necesitas más profundidad, enlaza a un documento separado con un resumen de una línea en el propio archivo.

¿Debo incluir ejemplos de código? Cortos, sí. Largos, no. Guarda los ejemplos completos para las pruebas; los agentes también leen las pruebas. La guía de Codex gratuito de GPT-5.5 cubre cómo Codex utiliza específicamente los ejemplos de pruebas como señal adicional.

¿El agente vuelve a leer el archivo en cada turno? La mayoría de los agentes lo leen al inicio de la sesión y lo almacenan en caché. Algunos lo vuelven a leer después de grandes cambios en el archivo. Si realizas una edición importante, reiniciar la sesión del agente es la medida más segura.

¿Cómo pruebo que mi archivo funciona? Inicia una nueva sesión de agente sin ningún otro contexto, dale una tarea pequeña ("añadir una respuesta 422 a POST /payments") y observa lo que hace. Si lee la especificación, ejecuta make codegen y escribe una prueba de contrato, el archivo está cumpliendo su función.