AGENTS.md: el archivo que le da memoria a tu agente

AGENTS.md no hace más inteligente al modelo. Le dice lo que, si no, tendría que redescubrir cada vez.

El modelo no tiene memoria. No es una limitación que alguien planee arreglar. Así funciona la inferencia de un transformer: le das tokens, produce tokens, y cuando la sesión termina todo lo que aprendió sobre tu proyecto desaparece. La siguiente sesión empieza de cero.

No es un bug que se esquiva. Es una restricción para la que se diseña. El archivo que hace más trabajo en ese diseño es AGENTS.md.

El modelo despierta con amnesia

La guía de Anthropic para agentes de larga duración usa la analogía de ingenieros que trabajan por turnos. Cada ingeniero llega a la obra sin ningún recuerdo de lo que pasó en el turno anterior. Lee las notas de entrega, revisa el git log y recién entonces empieza a trabajar. La recomendación de Anthropic: deja un archivo de progreso, lee el historial reciente de commits, corre una verificación de punta a punta antes de tocar nada.

Tu agente de código es ese ingeniero, en cada sesión. Sin entrega de turno, supone. Algunas de esas suposiciones son incorrectas. Se acumulan en drift: el agente refactorizando lo que le dijeron que no tocara, eligiendo una librería que ya reemplazaste, rompiendo convenciones que nunca vio.

AGENTS.md es la entrega de turno. No un brief completo. Una lista ajustada de lo que la próxima sesión realmente necesita saber antes de tocar tu código.

Qué es AGENTS.md

AGENTS.md es un estándar abierto emergente: un archivo de texto plano, normalmente en Markdown, que el harness del agente lee al inicio de la sesión e inyecta en el contexto del modelo antes de que vea tu primer mensaje. Son instrucciones como memoria. No es documentación para humanos. No es un README. No es una spec. Son órdenes permanentes que persisten entre sesiones porque el archivo persiste, aunque el estado del modelo no.

Varios agentes ya lo tratan como una primitiva nativa. pi, el agente de código open source de earendil-works (Mario Zechner), lee AGENTS.md automáticamente desde el directorio actual y cada directorio padre subiendo por el árbol, además de un ~/.pi/agent/AGENTS.md global para órdenes permanentes entre proyectos. La cascada es deliberada: las reglas del proyecto pisan los valores globales por defecto, y las reglas de directorio pisan las del proyecto. Puedes tener un archivo que moldea todos los proyectos y otro más acotado que moldea este.

LangChain plantea el sistema de archivos como la primitiva más fundamental del harness y define un agente como modelo más harness. Un AGENTS.md en la raíz de tu repo es la expresión más simple posible de esa primitiva: un archivo durable que sobrevive a los resets de contexto y le dice al modelo cómo comportarse en este proyecto específico. El artículo sobre harness engineering profundiza en la arquitectura completa; este se enfoca en la capa de memoria dentro de ella.

Qué va en él

La versión liviana de AGENTS.md tiene tres cosas.

Qué es el proyecto. Un párrafo. No el pitch deck. Qué hace el sistema, con qué está construido y cómo es una tarea típica. El modelo debería poder orientarse antes de ver tu primera instrucción.

Convenciones no obvias. Lo que un ingeniero competente haría mal en su primer día. El módulo que nunca se toca sin una migración. La regla de lint que parece redundante pero atrapa una clase real de bug. La secuencia de deploy con una dependencia de orden nada obvia. Si un ingeniero senior que conoce tu stack igual se equivocaría, va aquí. Si lo adivinaría bien, no.

Punteros a contexto más profundo. Rutas a los archivos de spec, el diagrama de arquitectura, los ADRs, la referencia de variables de entorno. El agente los busca cuando los necesita. No los pegues en el archivo.

Qué va

• ✓Obligatorio:
  Resumen del proyecto en un párrafoQué hace, el stack y cómo es una tarea típica.
• ✓Obligatorio:
  Convenciones no obviasLo que un ingeniero nuevo haría mal en su primer día.
• ✓Obligatorio:
  Links o rutas a documentación más profundaSpecs, ADRs, referencias de entorno. No las pegues en el archivo.
• ✗Anti-pattern:
  El stack completo listado exhaustivamenteEl modelo ya conoce React. Dile solo lo que es inusual.
• ✗Anti-pattern:
  Principios generales de programaciónSi aplica a cualquier proyecto en cualquier lugar, va en el archivo global o en ninguno.
• ✗Anti-pattern:
  La arquitectura entera del sistema explicada en prosaEso es una spec o un ADR. Enlázalo.

Qué no va

Un AGENTS.md inflado es peor que ninguno. Cada línea que agregas quema context window en cada turno. Si tu archivo llega a 500 líneas, el agente gasta miles de tokens en órdenes permanentes antes de ver tu primer mensaje. El costo en tokens se acumula rápido a ese ritmo: un AGENTS.md largo no es memoria gratis, es memoria que pagas en cada request.

Peor: un archivo largo es un archivo que nadie actualiza. Seis meses después, la mitad está desactualizada y el agente opera sobre una ficción. El proyecto se pasó a un ORM nuevo hace dos meses. El archivo todavía dice Prisma.

Los patrones que matan un AGENTS.md:

Instrucciones genéricas que el modelo ya sigue. “Escribe código limpio.” “Maneja los errores con elegancia.” “Usa nombres de variables descriptivos.” Cuestan tokens y no cambian nada.

Principios generales que aplican a cualquier proyecto. Esos van en una config global o en un archivo del equipo, no en el archivo de este proyecto.

La spec entera de la feature que estás construyendo ahora. Es un artefacto aparte por algo. Una spec vive en un archivo de spec, versionado junto a la feature, cargado cuando trabajas en ella y archivado cuando sale a producción. No la pegues en las órdenes permanentes.

Un muro de contexto que el agente puede consultar por su cuenta. Tiene un sistema de archivos. Úsalo.

La prueba de poda

Anthropic publicó esta prueba directamente en su guía de agentes. La prueba es una pregunta por línea: si quitar esta línea no haría que el agente se equivoque, bórrala.

Corre esa prueba sobre tu AGENTS.md cada mes. Toma cada línea. Pregúntate si el agente haría algo mal sin ella. Si la respuesta es no, la línea es ruido. Bórrala.

Esto no es editar por estilo. Es editar por función. El objetivo es el archivo más chico que evite los errores reales que genera tu proyecto, y nada más.

Un AGENTS.md real, lo bastante corto para ser útil

Este es muy parecido al que usé durante el build de 70 días: una fintech cripto de 13 apps, construida en solitario con agentes de IA. Cada sesión empezaba leyendo este archivo.

# Project context

Crypto fintech monorepo. 13 apps, 3 APIs (Rust), 3 PostgreSQL databases,
Kubernetes in production. Each app is a standalone Next.js workspace.
Work targets one app at a time unless a task explicitly spans multiple.

# Non-obvious conventions

- Never modify `packages/db` shared schema directly. All schema changes
  go through a migration in the target app's `migrations/` directory.
- The `core-api` service owns auth. Do not implement auth logic in app-level
  code.
- Linting: `pnpm lint` must pass before any commit. The rule set is strict;
  do not disable rules inline without a comment explaining why.
- Environment variables: see `.env.example` in each app root. No secrets
  in code or in this file.

# Where to find context

- Architecture: `docs/architecture.md`
- Feature specs: `docs/specs/<feature>.md`
- ADRs: `docs/adr/`
- API contracts: `packages/openapi/`

Eso es todo. Menos de 200 palabras. El agente navega a esas rutas cuando necesita profundidad. El archivo en sí se mantiene liviano.

AGENTS.md no es una spec

Estas dos cosas se confunden. No son la misma herramienta.

AGENTS.md es memoria siempre encendida. Se carga en cada sesión, cuesta contexto en cada turno y debería contener solo las órdenes permanentes que aplican a cualquier tarea que vayas a correr en este repo. Responde: cómo funciona este proyecto, siempre.

Una spec es un artefacto por feature. Describe un cambio en detalle: requisitos, restricciones, criterios de aceptación, edge cases. Se carga cuando trabajas en esa feature y se archiva cuando la feature sale a producción. El artículo sobre Spec-Driven Development cubre cómo escribir una bien.

El modelo mental correcto: AGENTS.md es el manual del empleado. La spec es el brief del proyecto. El manual aplica a todos, todos los días. El brief aplica a un encargo. No metas el brief en el manual.

AGENTS.md

1. 01Se carga en cada sesión, en cada turno
2. 02Contiene órdenes permanentes para todo el repo
3. 03Corto, podado, siempre actualizado
4. 04Vive en la raíz del repo (y en los padres, y en el global)
5. 05Cubre convenciones, no detalle de features

Archivo de spec

1. 01Se carga para una feature y después se archiva
2. 02Contiene los requisitos de un cambio
3. 03Tan largo como la feature lo necesite
4. 04Vive en docs/specs/ junto a la feature
5. 05Cubre intención, restricciones, criterios de aceptación

Cómo evitar que se pudra

El archivo se pudre en el momento en que dejas de tratarlo como código.

Versiónalo. AGENTS.md vive en el repo. Cada cambio es un commit. Si una convención cambia, el archivo cambia en el mismo PR. Si renombraste el ORM, el archivo se actualiza en el mismo cambio que hace el renombre.

Aplica la prueba de poda con una cadencia. Una vez al mes alcanza para proyectos activos. El objetivo es atrapar líneas que dejaron de ser ciertas o dejaron de evitar errores reales.

Mantén el archivo global aparte. Tu ~/.pi/agent/AGENTS.md global (o el equivalente en tu harness) guarda lo que aplica a todos los proyectos: tu nombre, tu test runner preferido, el estilo de código que siempre usas. El archivo del proyecto guarda solo lo específico de este repo. Mezclarlos causa drift en las dos direcciones: el archivo del proyecto se llena de ruido genérico y el global se llena de detalles de proyecto.

Escribe el archivo para la próxima sesión, no para la actual. Cuando termines una tarea y las convenciones hayan cambiado, actualiza AGENTS.md antes de cerrar la sesión. El archivo debería reflejar el estado del proyecto hoy, no el de hace seis meses cuando lo creaste.

La versión honesta

El modelo no va a recordar tus convenciones. No va a recordar que le pediste que no tocara un módulo. No va a recordar el patrón de migración que le explicaste la semana pasada.

Eso no es un defecto. Es la arquitectura. Diseña para ella.

AGENTS.md le da al harness un archivo para leer. El harness lo inyecta. El modelo empieza la sesión sabiendo lo que de otro modo tendría que redescubrir o haría mal. No es magia. Es dejar las cosas por escrito en el único lugar que el sistema realmente lee.

Mantén el archivo corto. Mantenlo cierto. Corre la prueba de poda. El agente que corre con un AGENTS.md de 150 palabras que alguien mantiene le gana al agente que corre con un AGENTS.md de 700 palabras que nadie lee.

Preguntas frecuentes

¿Todo proyecto necesita un AGENTS.md?+

No. Un experimento de vida corta o un script de un solo archivo no lo necesita. AGENTS.md se paga solo cuando el proyecto tiene convenciones que el modelo haría mal, cuando hay varias sesiones sobre el mismo código o cuando más de una persona corre sesiones de agente en el mismo repo.

Si puedes describir todas las convenciones en un system prompt de una oración, ponlas en el system prompt. AGENTS.md es para los proyectos donde esa descripción pasa de un párrafo.

¿En qué se diferencia AGENTS.md de un system prompt?+

Un system prompt es efímero: lo defines para una sesión y desaparece. AGENTS.md es un archivo en el repo, versionado con el código, que el harness puede leer en cualquier momento. El system prompt es algo que configuras por sesión. AGENTS.md es algo que el harness lee automáticamente, así que cada sesión recibe las mismas órdenes permanentes sin que tengas que acordarte de pegarlas.

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

Lo bastante corto para leerlo en sesenta segundos. Para la mayoría de los proyectos, eso son de 100 a 250 palabras. El ejemplo de arriba cubre un monorepo de 13 apps en menos de 200 palabras.

Si tu archivo pasa de 400 palabras, aplica la prueba de poda antes de agregar nada más. Cada línea más allá de ese punto es un costo que pagas en cada turno. La mayoría no vale la pena.

¿AGENTS.md debería ir al repo o quedar fuera del control de versiones?+

Haz commit. AGENTS.md describe cómo trabajar en este código, y esa descripción debería cambiar cuando cambia el código. Git te da historial, blame y review. Dejarlo fuera del control de versiones hace que las convenciones se desvíen en silencio. La única excepción es si tu AGENTS.md contiene algo sensible: los secrets nunca deben ir a un archivo commiteado, y tampoco deberían estar en AGENTS.md.

pi lee AGENTS.md desde los directorios padre. ¿Debería poner uno en la raíz del repo y otro más adentro?+

Sí, cuando el repo tiene subcontextos relevantes. Un monorepo puede tener un AGENTS.md en la raíz con convenciones de todo el repo y un AGENTS.md por paquete con reglas específicas. pi los combina cargando desde el directorio actual hacia arriba, así que el archivo más específico se lee al final y puede sobrescribir al más general. No dupliques contenido entre niveles: si una regla aplica en todos lados, va solo en el archivo de la raíz.

¿Cuál es la diferencia entre AGENTS.md y un CLAUDE.md o un archivo de reglas de Cursor?+

El concepto es el mismo: un archivo que el harness lee antes de que el modelo vea tu mensaje. El nombre del archivo cambia según el harness. Claude Code lee CLAUDE.md. Cursor tiene su propio formato de reglas. pi lee AGENTS.md. AGENTS.md es el nombre con más impulso para convertirse en un estándar abierto entre harnesses, por eso vale la pena conocerlo, uses la herramienta que uses hoy.

Si cambias de harness, el contenido del archivo se lleva tal cual. El nombre del archivo es solo una convención.