Escribir reglas para agentes: cada línea de nuestro AGENTS.md costó un incidente

En la raíz de nuestro repositorio hay un archivo que todo agente lee antes de tocar nada. No es documentación: es un contrato. Y lo interesante no es lo que dice, sino cómo llegó a decirlo.

Casi ninguna de sus reglas nació de una discusión de arquitectura. Casi todas nacieron de algo que se rompió.

La regla del rsync

Un día había que subir un archivo de configuración a producción. La forma correcta era usar el script de deploy, pero era más rápido copiarlo a mano. Se ejecutó un comando con dos archivos de origen y un directorio de destino.

Lo que no se tuvo en cuenta es que la herramienta descarta la ruta de origen y copia por nombre base. El archivo de configuración de una aplicación aterrizó encima del archivo de configuración de la raíz del servidor. En producción.

Hoy esa regla ocupa un párrafo entero, con el ejemplo correcto, el incorrecto y la fecha del incidente. Es de las más largas del archivo, y es larga a propósito: quien la lea tiene que entender por qué existe, no solo qué prohíbe.

Prohibiciones concretas, no principios

La diferencia entre una regla que se cumple y una que se ignora está en lo específica que sea.

"Escribí código limpio" no sirve. No es accionable, y cada uno entiende otra cosa.

"Prohibido el borrado físico, usá borrado lógico con status: deleted" sí sirve. Es verificable: o el registro sigue ahí o no.

Nuestro archivo tiene una sección entera que es una lista de prohibiciones, cada una en una línea, cada una con su motivo entre paréntesis cuando el motivo no es evidente. Es la sección que más se consulta.

El detalle que más nos sorprendió

Escribir estas reglas para agentes mejoró cómo trabajamos las personas.

Cosas que antes vivían en la cabeza de alguien ahora están escritas. Cuando entra alguien nuevo al proyecto, lee el mismo archivo que lee el agente y arranca sabiendo dónde están los cables pelados. La documentación que nunca hubiéramos escrito "para nosotros" la escribimos porque el agente la necesitaba.

Hay algo casi cómico en eso: nos ordenamos porque teníamos que explicarle a una máquina cómo no romper las cosas.

Qué poner y qué no

Después de bastante iteración, el criterio nos quedó así.

Va al archivo lo que no se puede deducir leyendo el código: convenciones que no son obvias, decisiones que ya se tomaron y no queremos rediscutir, y todo lo que rompió algo alguna vez.

No va al archivo lo que el código ya dice. Listar la estructura de carpetas es garantizar que en tres meses la lista esté desactualizada y el agente confíe en información falsa. Una regla desactualizada es peor que ninguna regla, porque las dos se leen con la misma confianza.

La prueba de fuego

Cada tanto hacemos el ejercicio de leer el archivo completo preguntándonos, línea por línea, si sigue siendo cierta. Las que ya no lo son se borran sin nostalgia.

Un contrato con cláusulas muertas deja de ser un contrato y pasa a ser folklore.