Un archivo AGENTS.md indica a un agente de programación cómo trabajar en un repositorio. Se carga en el contexto en cada sesión, de modo que cada línea añadida tiene un coste en cada tarea y compite con la solicitud real por la atención del agente.

Este único hecho explica casi todo lo que sigue.

Escribe solo lo que no se pueda descubrir

Si el agente puede aprender algo examinando el repositorio, no lo escribas. La estructura de directorios, el framework utilizado y la convención para nombrar los archivos de pruebas son visibles en el repositorio y no hace falta repetirlos.

Lo que no se puede descubrir son la intención y las restricciones:

  • El comando que ejecuta las pruebas, cuando no resulta evidente
  • Convenciones que el código todavía no aplica de manera uniforme
  • Elementos que parecen errores, pero son deliberados
  • Directorios que no deben editarse y el motivo

Mantenlo lo bastante corto para leerlo entero

Un archivo de más de unas cien líneas empieza a comportarse como documentación que nadie lee. Las instrucciones escondidas en la línea 180 no cambian el comportamiento de forma fiable porque compiten con todo el contexto restante.

Si el tuyo ya ha crecido demasiado, la pregunta útil no es «¿cómo consigo que el agente siga esto?», sino «¿cuáles de estas líneas han cambiado alguna vez el resultado?».

Especifica los comandos

Las indicaciones imprecisas producen comportamientos imprecisos. Compara:

Run the tests before committing.

con:

Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.

La segunda versión evita un fallo concreto y recurrente. La primera solo expresa una intención.

Explica el motivo, no solo la regla

Una regla que explica su motivo sigue siendo útil ante una situación desconocida; una prohibición sin más, no. «No edites src/generated/» invita a hacer una excepción la primera vez que editarlo directamente parece conveniente. «No edites src/generated/: pnpm codegen lo sobrescribe y el cambio desaparecerá» no deja esa duda.

Revísalo cuando deje de funcionar

Trata el archivo como algo que se degrada con el tiempo. Cuando el agente hace repetidamente algo que no querías, eso aporta información sobre el archivo, no solo sobre el modelo. O falta una instrucción o la instrucción existente está quedando sepultada bajo trescientas líneas que ya no importan.