CLAUDE.md y AGENTS.md: la diferencia

Ejemplo ilustrativo, sin resultados medidos: una tienda de recambios de Valladolid encarga cambios de su web a un proveedor que usa Claude Code y Codex. Quiere conservar los nombres del catálogo y usar las condiciones comerciales aprobadas. Gerencia necesita que esas reglas lleguen a quien prepara los cambios, sea cual sea su herramienta.

Claude Code y Codex son asistentes de inteligencia artificial (IA) que pueden trabajar con los archivos de una web. Un agente es un programa que usa IA para decidir pasos y utilizar herramientas. Estos documentos le dejan instrucciones del proyecto en Markdown: texto con títulos y listas que puedes abrir en un editor corriente. La capacidad de editar la web procede de sus herramientas y accesos, no del documento.

En Claude Code, el modo predeterminado da preferencia a los archivos propios del proyecto. Si encuentra CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el recorrido desde la raíz hasta la carpeta actual, deja de cargar AGENTS.md como alternativa. La raíz es la carpeta principal del proyecto. No basta con mirar si allí están los dos nombres: unas notas personales en otro nivel pueden cambiar la selección.

La lectura directa de AGENTS.md requiere una versión compatible y su componente integrado activo. En /config, el menú Project instructions permite elegir claude-md-and-agents-md para incorporar ambos. Escribir «lee el otro archivo» en una frase no equivale a usar la importación reconocida por Claude Code. Pide al responsable técnico que compruebe versión, ajuste y archivos aplicables antes de atribuir un fallo a las reglas.

Compara el mismo encargo con el mismo material autorizado. En la tienda de Valladolid, pide conservar las referencias del catálogo, preparar el cambio de textos y explicar qué ha cambiado. Valora el resultado después de revisarlo, no por la seguridad con la que el agente dice que ha terminado. Compartir instrucciones permite trasladar reglas; no demuestra que dos herramientas resuelvan igual una tarea.

Pide una ficha de entrega que indique qué instrucciones estaban activas y qué revisión queda pendiente. Haz una prueba sobre una copia antes de incorporar el agente al trabajo habitual. Incluye el mantenimiento y la revisión al valorar qué herramienta te conviene.

En Claude Code, /context all permite revisar lo cargado. En Codex, pide que enumere las fuentes de instrucciones activas. Codex construye su cadena al iniciar: empieza por el ámbito global y recorre desde la raíz del proyecto hasta la carpeta de trabajo. En cada nivel da preferencia a AGENTS.override.md frente a AGENTS.md y después a nombres alternativos configurados. Reiniciar la sesión permite reconstruir ese descubrimiento tras un cambio.

Con esa información puedes pedir una explicación concreta cuando una regla no aparece: qué carpeta se abrió, qué archivos tenían preferencia y cuál contiene la norma vigente. Añadir más texto no es la primera solución. Quita instrucciones que ya no correspondan al trabajo y resuelve las contradicciones antes de alargar el documento. Para desarrollar esa hoja de trabajo, consulta qué es el archivo de instrucciones del proyecto.

Los permisos efectivos determinan qué archivos y herramientas puede utilizar el agente y cuándo necesita aprobación. Una prohibición dentro del documento no instala por sí sola ese control. Para probar los cambios de la web de la tienda, pide al técnico que limite el acceso a la copia de trabajo. La prohibición de modificar cobros o extraer datos de clientes también debe quedar respaldada por los accesos y por el proceso de revisión.

Las instrucciones del proyecto tampoco son la memoria automática, que recoge información durante el trabajo, ni equivalen a las instrucciones del sistema. No guardes contraseñas en estos archivos. Si tu equipo utiliza Codex, revisa su mecanismo propio; si quieres practicar con Claude, el siguiente paso es Claude Code a fondo. El objetivo es dejar al responsable una regla clara, una comprobación observable y una decisión de publicación explícita.