El archivo de memoria de tu agente

lo que vas a poder hacer

entregable · lo que produces

Un AGENTS.md funcional en la raíz del repositorio, más un archivo anidado por paquete en un monorepositorio. Si tu arnés lee otro nombre, añade el puente de una línea al mismo archivo.

El ingeniero sénior que revisará tus pull requests a las 2 de la mañana el mes que viene es un archivo Markdown que escribes esta tarde.

Ese es el mecanismo, no una metáfora. En el módulo 11, tu arnés revisa pull requests con una rúbrica que vive en este archivo. Cada límite que escribas hoy se mantiene mientras duermes. Cada uno que omitas es una decisión que el modelo toma por ti, a toda velocidad y sin recordar la última vez que se equivocó en ella.

Así que no se trata de rellenar una plantilla. Son las cuatro cosas que cambian el comportamiento del agente, las siete que malgastan su atención y la línea de enlace que mantiene los cinco arneses en el mismo archivo en vez de cinco copias divergentes.

Qué es este archivo y qué no

AGENTS.md es el estándar entre proveedores para explicar "cómo funciona este proyecto, escrito para que lo lea un agente". Markdown simple, sin esquema: por eso todos los arneses lo leen y ninguno discute el formato. Lo custodia una fundación, no un proveedor; muchas herramientas lo leen de forma nativa y los grandes monorepositorios mantienen un archivo anidado por paquete, así que lo aprendido en un arnés pasa al siguiente.

Ahora, la distinción que cambia cada línea que escribes.

Esto no es documentación, un README ni una wiki. Es contexto de trabajo para un agente: comandos de configuración y habituales, mapa de arquitectura, convenciones, límites y reglas de revisión. El lector es un modelo que no sabe nada de tu proyecto, debe ser útil en 60 segundos y nunca hará una pregunta de seguimiento que no hayas invitado a hacer. Un README explica el proyecto a una persona que después puede leer el código. AGENTS.md le dice al agente qué hacer y qué evitar antes de empezar. Escribe lo primero queriendo lo segundo y tendrás un archivo agradable de leer que no cambia nada.

El modelo también olvida tu última sesión, así que lo que deba saber en cada ejecución debe vivir fuera, en un archivo que se cargue siempre. Lo que enseñas en el chat lo pagas otra vez mañana. Lo que enseñas aquí se compra una vez.

Qué funciona de verdad

Los archivos que funcionan coinciden en cuatro patrones. Tómalos como orientaciones, no medidas exactas:

• Los flujos numerados superan a la prosa. "Ejecuta estos cuatro pasos en este orden" funciona. Los mismos pasos en un párrafo, no.
• Las tablas de decisión superan a las reglas en frases. Una tabla de tres columnas —permitido, preguntar primero y nunca— se sigue con mayor fiabilidad.
• Una lista larga de prohibiciones juega en tu contra. A partir de unas 30, el agente dedica la atención a comprobarse en vez de hacer el trabajo.
• El tamaño tiene un techo estricto. Varios arneses cortan el archivo alrededor de 32 KiB sin avisar. Nadie lee el final de un archivo demasiado grande.

Debajo de los cuatro: los agentes siguen mejor una estructura positiva que reglas negativas. Como con un niño. A partir de cierta longitud, una lista de "no" deja de ser una valla y se convierte en un laberinto.

Anatomía de un buen AGENTS.md

Los diez arquetipos del paquete siguen esta estructura:

// markdown

# Vista general del proyecto (1 párrafo: qué es y qué pila usa)
# Configuración              (comandos de shell para copiar y arrancar)
# Comandos habituales        (build, dev, test, lint con descripciones de una línea)
# Arquitectura               (mapa de directorios con la función de cada uno)
# Convenciones de código     (nombres, exportaciones, elecciones de framework)
# Límites                    (tabla editar / preguntar / nunca)
# Pruebas                    (comandos y patrones)
# Pautas de PR               (formato de commits, modelo de ramas)
# Pautas de revisión         (la rúbrica de tu revisor de PR)

Esa es la columna vertebral. En monorepositorios, añade un AGENTS.md anidado en cada paquete. Todos los arneses resuelven primero el archivo más cercano, así que apps/web/AGENTS.md prevalece sobre el de la raíz para trabajo en esa carpeta.

Anidar no es solo orden. Un archivo raíz suficientemente grande para cuatro paquetes obliga a cada agente a leer tres paquetes de contexto irrelevante antes de llegar al suyo y te acerca al límite de recorte. Divídelo y cada agente cargará solo su paquete.

Límites: dale al agente un lugar donde parar

La primera de las dos secciones que justifican su lugar. Límites marca la línea que no cruzará un agente, así que usa una tabla, no un párrafo: editar libremente, preguntar primero, nunca tocar.

La columna intermedia es la que suele omitirse y la que hace el trabajo. Un agente con solo permitido y prohibido no tiene salida ante algo intermedio, así que elige la opción que le permita avanzar. Dale un estado de preguntar primero y la incertidumbre tendrá un destino que no sea adivinar.

Esa división está bajo toda configuración fiable: el modelo investiga, redacta, evalúa y da formato; una persona controla la selección y todo lo que publique, envíe, gaste o borre. Tu archivo es donde deja de ser una buena intención y se convierte en algo que el agente lee en cada ejecución.

Dos reglas para la tabla.

Nombra rutas y operaciones, no actitudes. "Ten cuidado con la base de datos" no es un límite. "Nunca edites archivos en migrations/, nunca ejecutes un comando que contenga DROP" sí: alguien que no estaba allí puede saber si se incumplió.

Pon las operaciones irreversibles en la columna nunca, no en preguntar. Preguntar primero supone que hay una persona mirando. En una ejecución sin supervisión a las 3 de la mañana no la hay; una pregunta bloqueada y una respuesta errónea te cuestan lo mismo hasta la mañana: nada. Todo lo que no puedas deshacer debe estar tras un muro, no tras una pregunta.

Pautas de revisión: la rúbrica que revisa tu código

La segunda, y la que más tiempo devuelve valor. Conecta tu arnés a la revisión de pull requests (el módulo 11 explica cómo) y esta sección se convierte en la rúbrica. Sé concreto:

// markdown

# Pautas de revisión

- Señala toda acción de servidor nueva que no llame a `requireAuth()`.
- Señala cualquier `console.log` en rutas de código de producción.
- Señala importaciones directas de `pg`/`postgres-js` fuera de `lib/db/`.
- Señala la falta de pruebas para nuevas interfaces de API públicas.
- Señala dependencias añadidas sin una entrada en CHANGELOG.md.

Reglas vagas producen revisiones vagas. Cuatro cosas de esa lista hacen más trabajo del que parece.

Cada línea empieza por "señala". No "corrige". Un revisor que señala te da una decisión. Uno que corrige te da un diff que ahora debes revisar, justo el trabajo que delegabas. Y si una revisión puede terminar de varias formas, nómbralas: aprobado, en espera, rechazado. Un agente con tres resultados definidos informa con honestidad. Uno con un solo resultado declara éxito.

Cada línea se puede comprobar sin criterio subjetivo. Una regla que el agente verifica mirando recibe una respuesta consistente. Una regla que exige gusto recibe una distinta en cada ejecución y te enseña a desconfiar del revisor.

Si un linter, una comprobación de tipos o una prueba puede hacerlo, no va aquí. Eso se ejecuta gratis en la cadena de integración, siempre y sin opinión. Dedica la atención del modelo a lo que solo detecta un lector: una llamada de autenticación ausente, un límite cruzado en silencio, una prueba que no comprueba nada.

Una persona identificada controla la compuerta. La revisión aconseja; alguien fusiona, así que escribe quién. Una rúbrica sin responsable produce una cola de avisos que nadie resuelve: parece cobertura y no aporta ninguna.

Qué NO incluir

Los siete errores:

1. Instrucciones específicas de modelo ("al usar el modelo X, haz Y"). Frágiles; divergen en cuanto cambia el modelo.
2. Secretos o valores de entorno. Nunca. Este archivo se guarda en git.
3. Hechos fechados, como una línea marcada "a marzo del año pasado". Los agentes futuros actúan con información obsoleta sin saberlo.
4. Grandes ensayos de arquitectura. El agente debe explorar el código. El archivo indica dónde mirar.
5. Preferencias personales disfrazadas de reglas. "Me gustan las comas finales" es ruido. "Conventional Commits" es una regla.
6. Configuración específica de herramienta. Va en el archivo propio de la herramienta, explicado en el módulo 5.
7. Preámbulos de rol. "Eres un ingeniero sénior con 20 años de experiencia". Los agentes ya saben hacer el trabajo.

Cada línea se carga en cada ejecución y compite con el trabajo real por la atención del modelo. Una línea que no cambia lo que hace el agente no es neutra: la pagas en cada petición y acerca el archivo al límite de recorte.

Un archivo, todos los arneses

Los cinco arneses del curso no leen todos el mismo nombre de archivo. No escribas cinco archivos. Escribe uno portable y enlaza el resto.

Claude Code lee CLAUDE.md, no AGENTS.md, y genera uno con /init. Para mantener una fuente única de verdad, escribe tu AGENTS.md y crea un enlace simbólico:

// bash

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md

Un archivo, ambos nombres, sin posibilidad de divergencia. Grandes repositorios abiertos lo usan para que quienes contribuyen con Claude Code y con otras herramientas lean el mismo contexto.

Haga lo que haga tu arnés, verifica en vez de suponer. El comportamiento documentado y el observado son afirmaciones distintas, y solo el segundo es tuyo.

La estructura portable de una skill

El formato compartido es una carpeta con un SKILL.md, cuyo frontmatter necesita name y description.

// text

review-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Descripción breve del activador en el frontmatter y procedimiento completo en SKILL.md. Carga referencias solo cuando la tarea las requiera, para mantener pequeño el costo permanente y pagar el costo bajo demanda solo cuando aporte algo.

Disciplina de mantenimiento

Trata AGENTS.md como código. Tres señales de desactualización:

• Los comandos de configuración fallan cuando los ejecuta alguien nuevo. El archivo está mal: corrígelo.
• El agente repite el mismo error. Añade una regla escrita como el flujo que querías, no como el error que obtuviste.
• El mapa de arquitectura nombra carpetas que ya no existen. Recorta.

Revísalo en cada ciclo de PR. Es lo bastante pequeño para tardar 30 segundos.

Un archivo desactualizado miente a cada agente que lo lee, y la mentira se acumula porque el agente actúa sobre ella. Una persona que lee un README erróneo se confunde y pregunta. Un agente que lee un mapa de arquitectura erróneo edita con seguridad el archivo que antes estaba allí.

Haz que tu agente escriba el primer borrador

No empieces en blanco. Tu agente puede leer este repositorio ahora mismo: el primer borrador es suyo y la edición, tuya. Abre el arnés en la raíz del repositorio y envía esto:

// text

Lee este repositorio y redacta un AGENTS.md en la raíz.

Hazlo en este orden:
1. Identifica la pila, el gestor de paquetes y los puntos de entrada en los archivos de configuración.
2. Extrae los comandos reales de compilación, desarrollo, pruebas y lint de los scripts
   de paquetes, makefiles o configuración de CI. No inventes comandos. Si no encuentras
   uno, escribe TODO al lado.
3. Mapea los directorios de nivel superior y escribe una línea por directorio que diga
   qué contiene.
4. Deduce convenciones de código solo donde la base de código sea consistente.
   Donde no lo sea, indícalo en vez de tomar partido.
5. Deja las secciones Límites y Pautas de revisión como títulos vacíos
   con una nota de una línea indicando que debo completarlas yo.

Usa estos títulos de sección en este orden: Vista general del proyecto, Configuración,
Comandos habituales, Arquitectura, Convenciones de código, Límites, Pruebas, Pautas de PR,
Pautas de revisión.

Mantén el archivo por debajo de 32 KiB. Sin secretos, valores de entorno, hechos fechados,
instrucciones específicas de modelo ni preámbulos de rol. Cita como comentario el archivo
del que tomaste cada comando para que pueda comprobarlos.

Las dos secciones vacías lo están a propósito. Los límites y las reglas de revisión codifican lo que estás dispuesto a perder, y el agente no puede saberlo. Todo lo demás describe un repositorio que puede leer.

Después comprueba el borrador. Ejecuta tú todos los comandos de Configuración y Comandos habituales. Un comando que no funciona es la línea más cara del archivo, porque el agente sigue intentándolo y declarando que el entorno está roto.

O hazlo tú

Elige el arquetipo adecuado del paquete de plantillas, colócalo en la raíz del repositorio y sustituye los marcadores: rutas, comandos y nombres de herramientas. Borra cada sección que no aplique en vez de dejar títulos vacíos, porque un título vacío se interpreta como una afirmación de que esa sección no era necesaria.

Después completa a mano Límites y Pautas de revisión. Esas dos nunca son tarea de la plantilla.

Qué haces después

Añade el puente de una línea para tu arnés para que el archivo se lea con cualquier herramienta que lances. Después pruébalo dos veces: pide al agente que enumere los archivos de instrucciones cargados y que toque algo de la columna preguntar primero para ver si se detiene. Esas dos comprobaciones enseñan más que otra hora escribiendo: el archivo que escribiste y el que leyó el agente son documentos distintos hasta que lo compruebas.

Una salvedad antes de construir sobre esto. El formato es estable: no tiene esquema ni nada que pueda romper una versión. Lo que cambia son los nombres de archivo alternativos de cada arnés y las claves de configuración que controlan esas alternativas y los límites de tamaño. Comprueba tu arnés antes de depender de una alternativa. La configuración segura es un AGENTS.md en la raíz y un enlace simbólico guardado en git para cualquier arnés que quiera otro nombre: así no quedan ajustes que puedan divergir.

Sigue el módulo 4: convertir los patrones que repites en comandos de una pulsación.

descargas

// 1 archivo · listo para usar. copia, adapta, entrega.

Paquete de plantillas AGENTS.md (10 arquetipos)~15 KBAplicación web, monorepositorio, biblioteca, CLI, cadena de ML, sitio de contenido, servicio API, IaC, móvil, proyecto de datos. Coloca, sustituye y entrega. Lo leen los cinco arneses.agents-md-template-pack.zipdescargar

recursos y referencias

// documentación oficial, herramientas e hilos que merece la pena guardar

Página de la especificación AGENTS.mdCustodiada por Agentic AI Foundation. Mínima a propósito, por eso todos los arneses pueden leerla.https://agents.mdEl AGENTS.md de un gran proyectoMerece estudiarse: el equipo usa este archivo en el repositorio que construye su propio agente.https://github.com/openai/codex/blob/main/AGENTS.mdAGENTS.md de vercel/next.jsEl patrón de «capturar una vez la salida de pruebas en un archivo» es una lección de disciplina de iteración.https://github.com/vercel/next.js/blob/canary/AGENTS.md