CLAUDE.md y AGENTS.md en el mismo proyecto: cómo no mantener dos archivos

Respuesta corta: mantén un archivo como fuente y haz que el otro apunte a él. Los dos agentes de IA leen el mismo contenido, editas en un solo sitio, y ninguno trabaja con una versión vieja de tus reglas. Duplicar el texto funciona dos semanas y después se vuelve el origen de errores que parecen aleatorios.

Claude Code lee CLAUDE.md. Codex lee AGENTS.md. Si usas ambos en el mismo proyecto, tienes dos archivos diciendo cómo trabajar en tu código, y nada obliga a que digan lo mismo.

Por qué dos archivos divergentes salen caros

El problema no es la duplicación, es su silencio. Añades una regla nueva (no tocar esta carpeta, ejecutar siempre aquel comando antes de commitear) en el archivo que tenías abierto, y olvidas el otro. Dos semanas después un agente de IA hace justo lo que la regla prohibía, y el error no dice "leí la versión vieja de tus instrucciones". Dice otra cosa, y buscas en el lugar equivocado.

Cuanto más específicas sean tus reglas, peor. Las reglas genéricas convergen solas; las de proyecto, no.

Cómo mantener ambos sin duplicar el texto

Elige un archivo como fuente y haz que el otro apunte a él. Un AGENTS.md de tres líneas basta:

# Instrucciones del proyecto\n\nLas reglas de este repositorio están en CLAUDE.md. Lee ese archivo\nantes que nada y sigue lo que diga.

Funciona porque las dos herramientas leen archivos del repositorio bajo demanda: el agente abre el que señalaste y lo sigue. Pasas a tener un solo sitio que editar, y la pregunta "¿cuál de los dos es el correcto?" deja de existir.

¿Sirve un enlace simbólico?

Sirve, y es lo más escueto si tu equipo es todo Unix: ln -s CLAUDE.md AGENTS.md y los dos pasan a ser el mismo archivo. La salvedad es Windows, donde el enlace simbólico depende de permisos y Git debe estar configurado para preservarlo. Si alguien clona en Windows sin eso, el archivo queda como un texto de una línea con una ruta dentro, y el agente de IA lo lee como si fueran tus instrucciones.

El puntero en texto no tiene ese riesgo y cuesta tres líneas. Es lo que preferimos.

Qué escribir en ese archivo

Lo que cambia el resultado no es el formato, es el contenido. Lo que rinde, con seis agentes de IA en un mismo repositorio:

• Qué NO tocar, con el motivo al lado. "No edites este archivo" se ignora; "no edites este archivo porque lo genera X y tu cambio desaparece en el próximo build" se obedece.
• El comando que demuestra que está listo. Un agente sin criterio de conclusión entrega cuando cree que terminó. Con el comando escrito, lo ejecuta y arregla antes de llamarte.
• Cómo se aísla el trabajo, si ejecutas más de un agente a la vez. Sin eso, dos agentes editan el mismo archivo y uno pierde el trabajo.

¿Y si las reglas deben ser distintas por herramienta?

Pasa, y es el único caso donde dos archivos separados se justifican: cuando la instrucción es sobre la herramienta, no sobre el proyecto. Mantén el puntero a las reglas comunes y añade abajo solo la parte específica. Lo que no puede es que la regla de proyecto viva duplicada en ambos.

¿Vale para otros agentes de IA?

Vale, y va a empeorar antes de mejorar: cada herramienta nueva trae su propio nombre de archivo. Un archivo fuente con punteros escala a los que aparezcan, porque añadir otro cuesta tres líneas y no una copia de tu manual entero.

Cómo saber que ambos se están leyendo

Pregúntale al agente. Un "¿qué instrucciones de este proyecto cargaste?" al empezar la sesión responde en un segundo, y es más fiable que suponer. Vale especialmente tras mover carpetas: un archivo de instrucciones en un subdirectorio no siempre se encuentra desde donde se abrió la herramienta.