CLAUDE.md, AGENTS.md y el fichero que hace útil a un agente de código

Un agente de código que aterriza en tu repositorio sabe el lenguaje y no sabe nada de ti. No sabe que las pruebas necesitan un contenedor levantado, que el directorio legacy/ está congelado, que tu equipo escribe las migraciones de una forma concreta ni que el módulo utils es donde las cosas van a morir.

Puedes explicárselo en cada sesión o puedes escribirlo una vez. Ese fichero —CLAUDE.md, AGENTS.md, lo que lea tu herramienta— es lo que más apalanca en el repositorio en cuanto hay agentes en juego, y casi todos los que vemos o no existen o son tres veces demasiado largos.

Qué va dentro

Cómo se ejecuta cada cosa. Los comandos exactos de instalación, build, pruebas, linter y prueba individual. No «npm test» si la respuesta de verdad es «npm test necesita el stack de docker-compose levantado, y la batería de integración necesita TEST_ENV=local». Esto solo ya elimina el fallo más común: un agente que no puede verificar su propio trabajo y que, por tanto, no lo verifica.

La estructura, en cinco líneas. Dónde están los puntos de entrada, qué contiene cada directorio de primer nivel, dónde vive lo que sorprende a la gente. Un agente que tiene que buscar para encontrar la capa de API la encontrará, al final, después de leer ficheros que no necesitaba.

Las convenciones que son tuyas y no del lenguaje. No «usa nombres de variable con significado». Cosas como: los errores se envuelven con fmt.Errorf y nunca se registran donde se crean; todo endpoint pasa por el decorador de permisos; el SQL vive en la capa de repositorio y en ningún otro sitio. Entre tres y ocho, las que corregirías en una revisión.

Las prohibiciones, con su motivo. No edites lo que hay bajo generated/. No actualices el ORM, está fijado por una razón. No añadas dependencias sin preguntar. Una regla con motivo sobrevive; una regla pelada se acaba interpretando por los bordes.

Dónde buscar más contexto. Punteros al documento de arquitectura, al runbook, al esquema. Los agentes siguen bien las referencias, y un puntero cuesta una línea donde el contenido costaría cincuenta.

Qué no va dentro

Nada que se deduzca del código. Listar los módulos y lo que hace cada uno duplica algo que el agente puede leer y garantiza un fichero equivocado en un mes. El contexto caducado es peor que el contexto ausente, porque se sigue con confianza.

Prosa sobre vuestros valores. «Nos importa la calidad» no cambia nada. Cada línea debería ser accionable o borrable.

La documentación completa de la API. Infla la ventana de contexto en cada turno, incluidos los que no tocan la API.

Nada secreto. Estos ficheros se leen dentro del contexto de un modelo y se comprometen en un repositorio semipúblico. Nada de nombres de host internos que no publicarías, nada de credenciales, evidentemente, pero tampoco nombres de producto sin anunciar en un repositorio que podría abrirse.

Por qué los largos dejan de funcionar

Un fichero de contexto se antepone a prácticamente cada petición. A trescientas líneas está compitiendo por la atención con la tarea real, y el efecto práctico es que el modelo sigue las primeras y las últimas instrucciones y se despista en el medio. Además cuesta tokens en cada turno, que es dinero de verdad cuando hay volumen.

La disciplina es la misma que mantiene útil un README: una página, y cada línea se gana el sitio. Si necesitas más, pártelo: casi todas las herramientas admiten ficheros anidados, de modo que frontend/CLAUDE.md solo se carga cuando el agente trabaja en ese directorio. Ese acotado es como los monorepos grandes mantienen corto el fichero raíz.

Mantenlo honesto

Trátalo como código: revisado en pull requests, actualizado cuando cambian los comandos de build y podado cuando una regla deja de ser cierta. La señal de que un fichero ha caducado es que la gente ha empezado a corregir al agente sobre lo mismo por chat en vez de arreglar el fichero, que es el equivalente documental de esquivar un proceso roto.

Un buen hábito: después de cualquier sesión en la que hayas corregido al agente dos veces sobre el mismo punto, añade la línea. En un par de meses el fichero converge exactamente hacia el conocimiento tácito que necesitaría alguien que entra nuevo, que es un efecto secundario agradable: el documento de incorporación se escribe solo, en el único formato que alguien mantiene de verdad.

Qué hacer esta semana

Abre tu repositorio principal y comprueba si el comando de pruebas del fichero de contexto todavía funciona. En cerca de la mitad de los repositorios que miramos no funciona, lo que significa que cada sesión de agente ha estado partiendo de una afirmación falsa y construyendo hacia fuera.