AGENTS.md vs CLAUDE.md: cómo dar contexto a Codex y Claude Code sin llenar el repositorio de instrucciones

Cuando un agente de programación falla dos veces de la misma manera, la reacción normal es añadir otra regla al repositorio. Primero ponemos los comandos de test, después el estilo, luego un mapa de carpetas, la arquitectura completa y una lista de errores históricos. Al cabo de unos meses, el archivo de instrucciones es tan largo que lo importante queda enterrado.

AGENTS.md y CLAUDE.md sirven para que Codex, Claude Code y otras herramientas conozcan convenciones que no pueden deducir con seguridad. No deberían intentar sustituir el README, la documentación de arquitectura, el linter y la suite de pruebas.

La diferencia corta

AGENTS.md es un formato abierto de instrucciones para agentes. Varias herramientas lo reconocen y puede colocarse en la raíz o dentro de subdirectorios. CLAUDE.md es el archivo de memoria de proyecto de Claude Code y añade funciones propias como importar otros archivos mediante @ruta.

	AGENTS.md	CLAUDE.md
Objetivo	Convenciones compartidas entre agentes compatibles	Contexto específico de Claude Code
Alcance local	El archivo más cercano suele aplicarse a su subárbol	Claude descubre archivos en la jerarquía y al entrar en subárboles
Importaciones	Dependen de la herramienta	Admite @ruta/al/archivo
Portabilidad	Mayor	Centrada en Claude Code
Uso conjunto	Posible, pero no conviene duplicar dos manuales completos

Qué instrucciones sí merecen estar

• Los comandos exactos para instalar dependencias, ejecutar pruebas y aplicar el linter.
• Qué carpetas son generadas, de terceros o no deben editarse.
• Convenciones del repositorio que no están automatizadas.
• La definición de terminado: pruebas, migraciones, documentación o compatibilidad necesaria.
• Enlaces a documentos concretos cuando una tarea los necesita.

Una instrucción como «haz código limpio» no reduce ninguna ambigüedad. «Ejecuta make test-unit para cambios en packages/domain y make test antes de terminar una migración» sí cambia una decisión.

Un AGENTS.md pequeño y útil

# Trabajo en este repositorio

## Comandos
- Instalar: `make install`
- Tests rápidos: `make test-unit`
- Comprobación completa: `make check`

## Límites
- No editar `vendor/`, `dist/` ni archivos generados.
- Las migraciones son acumulativas: no modificar una ya publicada.

## Antes de terminar
- Ejecutar las pruebas del paquete modificado.
- Añadir una prueba de regresión cuando se corrige un fallo.

No incluye un árbol de cincuenta carpetas porque el agente puede listar el repositorio. Tampoco explica toda la arquitectura. Si una tarea toca facturación, un archivo más cercano puede proporcionar las reglas de ese contexto.

Instrucciones por subdirectorios

AGENTS.md
packages/
  billing/
    AGENTS.md
  catalog/
    AGENTS.md
frontend/
  AGENTS.md

La raíz puede contener reglas comunes. packages/billing/AGENTS.md explica migraciones o invariantes de facturación, y frontend/AGENTS.md los comandos de pruebas visuales. De este modo el contexto específico aparece donde hace falta y no acompaña una tarea que sólo cambia el backend.

CLAUDE.md e importaciones

Claude Code permite importar documentos desde CLAUDE.md con una referencia @. Puede ser útil para no duplicar comandos ya explicados:

# Contexto del proyecto

- Comandos y desarrollo local: @docs/development.md
- Decisiones de arquitectura: @docs/architecture.md

## Reglas específicas para Claude Code
- Antes de editar, localiza las pruebas del comportamiento afectado.
- No cargues toda la documentación si la tarea no la necesita.

Importar un archivo no lo hace gratis. Su contenido también ocupa contexto. Si docs/architecture.md tiene cuarenta páginas y se carga para corregir una errata, hemos convertido la documentación en ruido.

Por qué demasiadas instrucciones pueden empeorar el resultado

Un archivo enorme tiene tres problemas. Consume parte del contexto antes de leer el código, aumenta la probabilidad de reglas contradictorias y hace más difícil distinguir una obligación de una sugerencia. OpenAI ha documentado precisamente este cambio de enfoque: con modelos recientes, las skills y archivos de instrucciones demasiado prescriptivos pueden impedir que el agente utilice capacidades que ya tiene.

La solución no es borrar todo. Es practicar divulgación progresiva: una descripción corta indica cuándo leer una guía, y la guía específica sólo se carga si la tarea llega a esa parte.

Lo que sacaría del archivo

• Una copia del README o de la estructura completa del repositorio.
• Consejos genéricos de programación que ya comprueba el linter.
• Versiones y rutas que se quedan obsoletas cada semana.
• Secretos, tokens, URLs privadas o datos de producción.
• Reglas escritas para un incidente antiguo que una prueba podría impedir.

Si una regla puede convertirse en una prueba, una restricción del tipo, un hook o una validación de CI, prefiero automatizarla. El archivo de contexto debería cubrir lo que todavía requiere criterio, no actuar como un linter en lenguaje natural.

Usar AGENTS.md y CLAUDE.md a la vez

En un equipo que utiliza varias herramientas pondría las reglas compartidas y estables en AGENTS.md. CLAUDE.md quedaría para funciones exclusivas de Claude Code o para importar documentación. Evitaría mantener dos copias manuales del mismo texto, porque acabarán contradiciéndose.

También evitaría instrucciones diseñadas para forzar a todas las herramientas a trabajar igual. Como vimos al comparar Opus y Sonnet dentro de Claude Code, cambiar modelo o esfuerzo ya cambia la estrategia. Un manual excesivamente detallado puede ocultar esas diferencias sin garantizar un resultado mejor.

Una revisión mensual de diez minutos

• ¿Sigue existiendo cada comando?
• ¿Hay reglas que ya controla CI?
• ¿Hay dos instrucciones que se contradicen?
• ¿Una regla de una carpeta se puede mover a un archivo local?
• ¿El agente falló por falta de contexto o por una prueba inexistente?

Mi regla práctica

Si una instrucción no cambia una decisión concreta, no debería ocupar contexto en cada tarea. Empiezo con comandos, límites y definición de terminado. Añado una regla cuando existe un fallo repetido y la retiro cuando ya está automatizada.

AGENTS.md y CLAUDE.md funcionan mejor como señales de tráfico que como enciclopedias. Le dicen al agente dónde puede ir, qué debe comprobar y cuándo necesita abrir otro documento. El resto debería seguir viviendo en el código, las pruebas y la documentación que ya utiliza el equipo.