AGENTS.md, CLAUDE.md y Copilot: qué archivo lee tu asistente
Has escrito «no cambies los datos del documento» en un archivo de instrucciones, pero el asistente vuelve a modificar una cifra. Antes de añadir otra regla en mayúsculas, averigua dónde ocurrió el fallo: ¿el archivo estaba en el lugar adecuado, entró en la conversación o se leyó y aun así no se respetó?
Esta guía sirve para diagnosticar esas tres situaciones. Las reglas de producto se contrastaron con documentación oficial el 17 de octubre de 2026. No existe una precedencia única que puedas trasladar de Codex a Claude Code o a cualquier ventana que lleve el nombre Copilot.
Identifica el cliente antes de renombrar archivos
Anota el nombre completo de la herramienta, su versión y la carpeta desde la que inicia la tarea. En una terminal, esa carpeta es el directorio de trabajo, también llamado CWD. En un editor, comprueba además el proyecto o repositorio asociado a la sesión.
«Uso Claude» puede significar que elegiste un modelo Claude dentro de otro asistente. «Uso VS Code» tampoco identifica la extensión ni el agente. Para este diagnóstico importa qué programa reúne las instrucciones y ejecuta las herramientas.
Punto de partida para localizar instrucciones; las condiciones se detallan debajo
| Dónde haces la tarea | Archivo que debes revisar primero | Dato que falta para diagnosticar |
|---|---|---|
| Codex | AGENTS.md y cualquier AGENTS.override.md en el mismo nivel | Carpeta de inicio y raíz del proyecto |
| Claude Code | CLAUDE.md; AGENTS.md según versión y configuración | Archivos presentes en la carpeta y sus ancestros |
| Copilot en VS Code | Formato admitido por el agente de esa sesión | Agent Host o Local, y agente seleccionado |
| Copilot Chat en GitHub.com | .github/copilot-instructions.md | Repositorio y función concreta de Copilot |
Si trabajas únicamente con chats y archivos subidos a ChatGPT, empieza por proyectos, memoria e instrucciones personalizadas. Poner un AGENTS.md en una carpeta de tu ordenador no demuestra que ese chat pueda acceder a ella.
Codex: AGENTS.override.md desplaza al AGENTS.md del mismo nivel
La guía oficial de AGENTS.md de OpenAI describe una cadena construida al iniciar cada ejecución. Además de la capa global, Codex recorre desde la raíz del proyecto hasta el directorio de trabajo. Si no identifica una raíz, comprueba ese directorio.
Carga como máximo un archivo por directorio: busca primero AGENTS.override.md, después AGENTS.md y luego los nombres alternativos configurados. Los archivos vacíos se omiten. Por eso añadir un override no equivale a sumar otra lista al AGENTS.md vecino. Entre niveles, las instrucciones más cercanas al directorio de trabajo se añaden después y prevalecen sobre las anteriores.
Para investigar un fallo, revisa la ruta completa, no solo el archivo que tienes abierto. Repite la comprobación en una sesión nueva después de cambiar las instrucciones. Si el texto sigue sin entrar completo, consulta en la guía los límites de tamaño y los nombres alternativos de tu configuración.
Claude Code: puede leer AGENTS.md, pero revisa el fallback
Según la documentación de Claude Code, la lectura directa de AGENTS.md está disponible desde v2.1.277, con condiciones. Por defecto deja de usar ese fallback si encuentra CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo o sus ancestros. El archivo personal ~/.claude/CLAUDE.md no cuenta para esa exclusión.
Así, añadir un CLAUDE.local.md puede cambiar qué instrucciones entran aunque nadie haya tocado AGENTS.md. Comprueba Project instructions en /config: permite elegir, entre otras opciones, la lectura de ambos formatos.
Revisa también la versión y el plugin incorporado de lectura de AGENTS.md. Si está desactivado, o tu sesión no admite esa lectura, existe la importación @AGENTS.md desde un CLAUDE.md. Antes de v2.1.281 había otras excepciones de sesión; consulta la guía o actualiza antes de sacar conclusiones.
Usa /memory para comprobar la ruta cargada. Antes de v2.1.280 ese listado no mostraba los AGENTS.md leídos directamente. AGENTS.override.md no forma parte de este mecanismo: no traslades a Claude la precedencia de Codex.
Copilot: distingue VS Code Local, Agent Host y GitHub.com
En VS Code, Agent Host sigue las reglas del agente seleccionado; Local tiene ajustes propios. La guía de instrucciones de VS Code recomienda .github/copilot-instructions.md o AGENTS.md para Copilot, CLAUDE.md para Claude y AGENTS.md para Codex. Elegir un modelo no sustituye esta selección de agente.
Abre Chat: Open Customizations con el agente correcto seleccionado. Comprueba que el archivo aparece; después inicia un chat nuevo, realiza una tarea de control y revisa References en la respuesta. El listado acredita descubrimiento, no cumplimiento.
Si usas Local, revisa sus ajustes: chat.useAgentsMdFile controla AGENTS; chat.useNestedAgentsMdFiles habilita los anidados, es experimental y está desactivado por defecto. No apliques esas opciones como solución universal a Agent Host.
En GitHub.com, distingue Chat, cloud agent y code review. La matriz oficial de compatibilidad de GitHub lista .github/copilot-instructions.md para instrucciones de repositorio en Chat. El cloud agent admite además instrucciones por ruta y archivos como AGENTS.md o CLAUDE.md. No uses la compatibilidad del cloud agent para dar por hecho que Chat web carga los mismos archivos.
Un diagnóstico en cinco pasos
No cambies a la vez el modelo, las instrucciones y la tarea: después no sabrás qué resolvió el problema. Empieza con una copia de trabajo pequeña y conserva la salida original.
- Cliente y versión. Escribe el producto concreto y el tipo de sesión. Si hay un selector de agente, registra su valor por separado del modelo.
- Carpeta. Comprueba desde dónde arranca la tarea. Confirma que el documento revisado y el archivo de instrucciones pertenecen a la copia del proyecto que esperabas.
- Nombre y alcance. Revisa extensión, ubicación, archivos alternativos y condiciones de carga del cliente. Comprueba que el editor no haya guardado
AGENTS.md.txt. - Evidencia de carga. Busca el archivo en los controles, referencias o registros disponibles. Si la única evidencia es que el modelo dice haberlo leído, anótalo como autodeclaración.
- Una conducta observable. Pide una tarea donde puedas comprobar la regla sin preguntarle al modelo si la cumplió. Conserva entrada, respuesta y resultado esperado.
Cómo interpretar lo observado sin confundir carga con calidad
| Lo que observas | Qué puedes concluir | Qué revisar después |
|---|---|---|
| El archivo existe, pero no aparece evidencia de carga | Todavía no has confirmado que llegó a la sesión | Cliente, ruta, configuración y límites del registro |
| El cliente muestra que incorporó el archivo | Hay evidencia de carga | Una tarea donde esa regla afecte al resultado |
| La respuesta repite el nombre del archivo | El modelo afirma conocerlo | Evidencia del cliente y conducta, por separado |
| La respuesta cumple una regla de formato | Cumplió ese requisito en esa ejecución | Exactitud, omisiones y otras reglas de la tarea |
| Dos archivos aplicables se contradicen | Hay un conflicto que conviene corregir | La fuente original de la regla, antes de añadir otra copia |
Puedes copiar este registro en tus notas:
Cliente y versión:
Tipo de sesión / agente seleccionado:
Modelo:
Carpeta de inicio:
Archivo y ruta de instrucciones:
Cómo comprobé su carga:
Petición exacta:
Resultado que esperaba:
Resultado observado:
Único cambio para la siguiente prueba:
El registro obliga a separar dos preguntas: «¿aplicó esta regla?» y «¿resolvió bien el encargo?». Una respuesta puede llevar el encabezado solicitado y conservar un dato incorrecto. Una revisión puede detectar el error aunque no haya cargado tu formato preferido.
Nuestra comprobación: cambió el formato, pero la lectura quedó bloqueada
El 4 de octubre de 2026 se ejecutaron dos casos con Codex CLI 0.159.2 en Windows, usando una cuenta de ChatGPT existente. La carpeta de prueba era independiente del sitio y no tenía Git. Cada caso inició una sesión efímera nueva, con --ignore-user-config y sandbox read-only.
Había dos documentos ficticios sobre un taller y dos archivos de instrucciones. AGENTS.md pedía empezar el informe con FORMATO BASE; AGENTS.override.md pedía FORMATO OVERRIDE. El resto de ambos archivos era idéntico. Ningún marcador aparecía en la petición del usuario.
Dos ejecuciones locales: conducta observada, no una comparación de calidad
| Caso | Único cambio entre casos | Primera línea de la respuesta | Revisión de los documentos |
|---|---|---|---|
| A | Ambos archivos de instrucciones presentes | FORMATO OVERRIDE | No completada: lectura bloqueada por la política del entorno |
| B | Override renombrado a AGENTS.override.md.disabled | FORMATO BASE | No completada: lectura bloqueada por la política del entorno |
El registro de errores confirma que se rechazaron los comandos Get-Content para leer los documentos. No se identificó qué política concreta originó el rechazo. Los hashes de los archivos se conservaron dentro de cada ejecución. No se comprobó la detección de la fecha incorrecta, la afirmación sin respaldo ni la conservación del cupo: el asistente no pudo hacer esa revisión.
Los marcadores respaldan el seguimiento de la instrucción de formato correspondiente en estos dos casos. El registro exportado no aporta un inventario completo de las instrucciones cargadas: el marcador es evidencia de conducta, no una auditoría de toda la cadena. La carpeta separaba los archivos de prueba, pero --ignore-user-config no garantiza aislar todas las instrucciones globales. Tampoco se probó Claude Code, Copilot, otro directorio anidado ni la frecuencia de éxito al repetir la tarea.
La enseñanza práctica es útil incluso con ese bloqueo: ver un formato correcto no significa que el asistente haya podido leer los documentos o terminar el trabajo. Aquí no se ampliaron permisos para forzar un resultado.
Cómo preparar el mismo control pequeño
Necesitas Codex CLI instalado, una sesión con acceso al servicio y una carpeta de prueba. Las solicitudes usan tu acceso habitual; el ejemplo no presupone que sean gratuitas. Puedes leer y copiar los archivos sin ejecutar el asistente.
Guarda este texto como AGENTS.md:
# Regla editorial de este ejemplo
La primera línea del informe final debe ser exactamente: FORMATO BASE
Después revisa los documentos solicitados. No edites los archivos.
Duplica ese archivo como AGENTS.override.md y sustituye únicamente FORMATO BASE por FORMATO OVERRIDE. Crea también referencia.md:
# Ficha del taller — ejemplo ficticio
- Actividad: Taller de documentación.
- Fecha: 5 de noviembre de 2026.
- Horario: 10:00 a 11:30.
- Cupo máximo: 12 personas.
- Resultado previsto: producir un borrador revisado durante el ejercicio.
- No se garantiza que todos los documentos queden sin errores.
Y borrador.md:
# Anuncio del taller — ejemplo ficticio
El Taller de documentación será el 6 de noviembre de 2026, de 10:00 a 11:30.
Hay 12 plazas disponibles.
Todas las personas terminarán el taller con documentos sin ningún error.
Desde esa carpeta, inicia una ejecución nueva de Codex CLI y envía esta petición, igual en ambos casos:
Revisa borrador.md contrastándolo con referencia.md y devuelve un informe breve. Lee únicamente los archivos necesarios de esta carpeta. No edites archivos, no investigues en Internet y no inspecciones credenciales, configuración personal ni otros proyectos.
Guarda la respuesta del caso A. Renombra solo el override a AGENTS.override.md.disabled, inicia otra ejecución y repite la petición. Comprueba por separado el encabezado y la revisión del contenido. Si se permite leer los documentos, el control espera detectar el cambio del 5 al 6 de noviembre y la promesa sin respaldo, conservando las 12 plazas. Esos son los criterios del ejercicio, no resultados que se hayan obtenido en nuestro ensayo bloqueado.
Qué hacer cuando el archivo sí entra y la respuesta falla
Reduce el problema a una regla verificable. «Hazlo perfecto» no define un resultado; «conserva los nombres y señala las fechas que contradigan el documento de referencia» sí permite comparar entrada y salida.
Si encuentras dos requisitos incompatibles, corrige la contradicción donde se origina. No acumules una tercera versión esperando que compense las anteriores. Conserva las instrucciones estables del proyecto separadas de los datos de una tarea puntual, como una fecha de entrega o una promoción.
Cuando el formato ya funciona, prueba el contenido: un dato correcto que debe conservarse, uno incorrecto que debe detectarse y una afirmación sin respaldo que no debería aceptarse. Para decidir si la herramienta sirve para tu trabajo, puedes ampliar esa comprobación con la plantilla de evaluación de una IA antes de pagar.
La salida útil de este diagnóstico es concreta: saber qué archivo se cargó, qué requisito se cumplió y qué queda por corregir, con una respuesta guardada que permita repetir la comprobación.