CLAUDE.md y AGENTS.md: reglas para el código de IA en equipo

CLAUDE.md y AGENTS.md son archivos del repositorio que un agente de IA carga en cada tarea para conocer las reglas del equipo. Las reglas para el código de IA en un equipo van ahí, no en la cabeza de un senior. Un archivo corto indica cómo se verifica el trabajo y qué no debe hacer el agente. Pero las reglas más importantes no deberían ser texto. Deberían ser lint, tests o CI que detienen un cambio malo por sí solos.

En nuestro caso, la IA escribe la mayor parte del código. Un senior revisa cada cambio y responde de producción. Desde 2023 hemos entregado más de 15 proyectos en producción y, hasta abril de 2026, trabajamos en el equipo de producto de un SaaS que usaban más de 60.000 personas al día. Las reglas que siguen salen de esos proyectos, sobre todo de nuestros errores.

¿Qué va en CLAUDE.md o AGENTS.md?

Lo que el agente no puede deducir del código y lo que ustedes hacen distinto de los demás. En concreto:

• Cómo ejecutar el proyecto y los tests. Idealmente, un solo comando para copiar.
• Qué no debe hacer el agente. La base de datos de producción, las claves secretas, migraciones sin aprobación, hacer push directamente a la rama principal.
• Dónde está cada cosa. Dónde vive la lógica de negocio, dónde están los tests, qué se genera y no debe editarse a mano.
• Convenciones que no son estándar. Cómo nombran las cosas, cómo gestionan los errores, dónde están las traducciones.
• Cómo es un trabajo terminado. Qué tiene que pasar antes de que el agente abra un pull request.

Lo que no va ahí: el estilo que ya impone el formateador. Ensayos largos sobre arquitectura. Reglas que solo valen en una carpeta.

¿CLAUDE.md o AGENTS.md?

Claude Code lee CLAUDE.md y, si el repositorio no lo tiene, las versiones actuales leen AGENTS.md. Muchas otras herramientas, como Codex, también leen AGENTS.md. Si su equipo usa varias herramientas, no escriba las reglas dos veces.

Guárdelas en AGENTS.md y apunte a ellas desde CLAUDE.md con la línea @AGENTS.md. Claude Code lo carga entonces por sí solo. Dos copias se distancian sin que nadie lo note.

¿Cuántas reglas son demasiadas?

El límite llega antes de lo esperado. El agente carga las reglas en cada ejecución. Cuanto más texto, peor se ciñe a lo importante.

A nosotros nos funciona repartirlas en tres niveles. La raíz del repositorio contiene el mínimo que vale para todo. Las reglas de un módulo están en un archivo dentro de su carpeta, y el agente solo las carga cuando trabaja allí. Las reglas más importantes son lint o tests: nadie tiene que leerlas, detienen un cambio malo por sí solas.

Con franqueza: no tenemos una respuesta perfecta. Las reglas se acumulan con cada error. Por eso las limpiamos con regularidad y pasamos a lint todo lo que podemos.

¿De dónde salen las reglas cuando aún no hay ninguna?

De la revisión de código. Un comentario que aparece por segunda vez en una revisión no es un error del desarrollador. Es un hueco en las reglas. El proceso es sencillo:

A menudo recomendamos que el agente repase los comentarios de revisiones antiguas y extraiga reglas de ellos. Solo funciona si los comentarios existen. Si la revisión ocurre solo de palabra, en una llamada, nada llega a los pull requests. Y el agente no tiene de dónde partir.

Así que primero el hábito y después la herramienta. Escriba los comentarios en el pull request, no solo de palabra.

¿Dónde va cada regla?

Un agente puede esquivar una prohibición escrita como frase. No abrirá un archivo, pero escribirá un script que lo imprima. Por eso, para cada regla anotamos qué la hace cumplir.

Un agente que trabaja por su cuenta debe ejecutarse solo en un entorno separado, sin acceso a la operación real ni a claves secretas. Un hook que rechaza un comando peligroso es un buen primer paso. Pero es un badén, no un muro: un agente ingenioso encuentra otro camino. Ninguna frase del tipo «ten cuidado» sustituye a ninguno de los dos.

La plantilla incluye la tabla y las prohibiciones con lo que hace cumplir cada una. Abrir la plantilla: Reglas para agentes de IA en su equipo (online o PDF).

¿Cómo se comparten las reglas entre varios repositorios?

Con distribución, no con disciplina. Teníamos nuestras reglas en el repositorio principal y los demás no las veían. Algunos las copiaron. Unos meses después había varias versiones y ninguna era igual a otra.

Hoy tenemos un único paquete de reglas que se carga en cada repositorio. Está versionado y solo cambia mediante un pull request aprobado. No hay copias, así que nada puede divergir. Las reglas personales son el estilo de trabajo de cada desarrollador. Las reglas compartidas pertenecen a la empresa y tienen que vivir en un solo sitio. Configuramos el mismo paquete de reglas en los equipos a los que nos sumamos dentro de AI-native SDLC para equipos de desarrollo. ¿A su equipo le faltan más manos que reglas? Vea un desarrollador senior para su equipo.

Revisión y tests: reglas que no están en el archivo

Algunas reglas no son del agente, sino del proceso que lo rodea. ¿Cuáles tiene ya su equipo?

Un test que nunca falló solo demuestra que el agente está de acuerdo consigo mismo. Y un pipeline que solo informa es decoración.

Cómo introducir estas reglas paso a paso en todo el equipo lo explicamos en Buenas prácticas de Claude Code para equipos: 7 reglas que se mantienen. Por qué el entorno de trabajo del agente importa más que el modelo lo explica Agente = modelo + entorno. Si el equipo aún está eligiendo herramienta, lea Cursor vs Claude Code.

Cuándo no lo recomendamos

• Son uno o dos desarrolladores en un solo repositorio. Basta con un CLAUDE.md o AGENTS.md corto. Escríbanlo ustedes mismos a partir de la lista de arriba.
• No tienen tests ni una CI que bloquee. Entonces las reglas para el agente no cambiarán mucho. Primero tests y CI, después reglas.

• Espera que una plantilla sustituya sus revisiones. No lo hará. Las reglas salen de sus revisiones, así que empiece por los comentarios en los pull requests.

¿Quiere configurar las reglas con alguien que trabaja con ellas a diario?

Revisamos sus repositorios y proponemos una primera versión de las reglas y de las barreras de CI. Un senior se incorpora a su repositorio y a sus pull requests desde el primer día.

Le respondemos en dos días laborables con unas preguntas sobre su trabajo. Después acordamos qué hacemos primero.

Si prefiere hablar primero, reserve una llamada inicial de 15 minutos.

¿Dónde viven hoy las reglas de su equipo?

Preguntas frecuentes

¿Qué es CLAUDE.md?

Un archivo del repositorio que Claude Code carga cada vez que se ejecuta. Contiene las reglas para el agente: cómo ejecutar los tests, qué no debe hacer y cómo es un trabajo terminado. Otras herramientas leen un archivo parecido llamado AGENTS.md.

¿CLAUDE.md o AGENTS.md?

Si el equipo solo usa Claude Code, basta con CLAUDE.md. Si usa varias herramientas, guarde las reglas en AGENTS.md. Sin CLAUDE.md, Claude Code lo lee directamente; con él, apunte a AGENTS.md con la línea @AGENTS.md. Dos copias separadas se distancian con el tiempo.

¿Cuántas reglas debería tener CLAUDE.md?

Las menos posibles. El agente las carga en cada ejecución, y demasiado texto empeora sus resultados. En la raíz deje solo lo que vale para todo. El resto, en carpetas, y las reglas más importantes, en lint o tests.

¿Quién debería ser responsable de las reglas para la IA en un equipo?

Una persona concreta que aprueba los cambios. Cualquiera puede escribirlas mediante un pull request. Sin responsable, cada uno las ajusta a su manera y la capa compartida se desmorona.

¿Basta con decirle al agente lo que no debe hacer?

No. Un agente puede esquivar una prohibición escrita. Lo que de verdad importa, hágalo cumplir con permisos de acceso, un hook, lint o CI. Para cada regla, anote qué la hace cumplir.