AGENTS.md en Claude Code: cómo validar una migración

Un equipo puede mantener la misma instrucción en varios archivos y aun así obtener cambios incompatibles. Una copia pide ejecutar las pruebas del paquete; otra conserva un comando retirado. Cuando un agente cambia de entorno, el fallo aparece como una mala decisión de programación, aunque empezó en la configuración. AGENTS.md en Claude Code permite revisar esa duplicación, pero antes conviene definir qué significa que una migración funcione: la instrucción correcta debe llegar al contexto adecuado y producir una acción comprobable.

Anthropic publicó Claude Code 2.1.277 el 18 de septiembre de 2026. La versión añade lectura de AGENTS.md cuando el proyecto no tiene CLAUDE.md, con una opción en Project instructions de /config; el anuncio excluye por ahora Bedrock, Vertex y Foundry. Es una novedad de compatibilidad, no una medición de productividad. Este artículo propone cinco criterios propios de adopción; no presenta una prueba ejecutada de Claude Code ni resultados de clientes.

El README de la versión distingue carga exclusiva de CLAUDE.md, fallback a AGENTS.md y carga de ambos. En el fallback, también importan .claude/CLAUDE.md y CLAUDE.local.md en el recorrido hacia el directorio de trabajo. Los archivos anidados pueden incorporarse al leer un subdirectorio. Por eso, comprobar únicamente la raíz visible del repositorio resulta insuficiente. La documentación describe además managed-only con salvedades; no debe interpretarse como una garantía absoluta de aislamiento.

La convención AGENTS.md ofrece un lugar predecible para instrucciones de trabajo y admite archivos específicos por subproyecto. Nuestra recomendación es separar tres preguntas durante la adopción: dónde está escrita una regla, si el entorno realmente la incorpora y si el agente la cumple. Que dos herramientas reconozcan un nombre de archivo resuelve parte de la primera pregunta. Las otras requieren evidencia en tu repositorio, con tus rutas, configuración y tareas.

Empieza con un inventario revisable de instrucciones y puntos de entrada. Incluye archivos versionados, ajustes locales relevantes, directorios desde los que se inicia el agente y referencias que importan otros documentos. Asigna un responsable a cada regla. Una instrucción sobre arquitectura puede pertenecer al equipo de plataforma; un comando de prueba debe mantenerse junto al paquete que lo implementa. La consolidación falla cuando mueve el texto pero pierde a su dueño.

Marca contradicciones antes de elegir cuál conservar. Si dos documentos ordenan usar gestores de paquetes distintos, no pidas al modelo que arbitre una decisión de infraestructura. Resuélvela con los scripts y archivos de bloqueo vigentes. Conserva un registro breve de la regla canónica y sus excepciones. El criterio de salida es concreto: ninguna instrucción operativa importante debe depender de recordar qué copia actualizó alguien la semana pasada.

Considera este ejemplo hipotético: un monorepo contiene una API y una aplicación móvil. La guía común exige revisar el diff y documentar las comprobaciones, mientras cada paquete define su comando de prueba. Copiar todos los comandos a la raíz obliga al agente a elegir por intuición. Una estructura más mantenible coloca las reglas compartidas arriba y las instrucciones específicas junto al código correspondiente, con rutas y condiciones de aplicación claras.

No conviertas la guía común en un manual de cada herramienta. Separa las convenciones del repositorio de las opciones particulares de ejecución y registra quién configura estas últimas. Para cada regla pregunta si seguirá siendo cierta después de cambiar de agente. Si depende de una integración concreta, documenta esa dependencia. Compartir contexto resulta útil cuando reduce divergencias; un archivo enorme lleno de excepciones puede trasladar el problema sin resolverlo.

En el monorepo hipotético, prepara una rama de ensayo y un entorno desechable sin credenciales de producción. Introduce una tarea pequeña cuya solución conocida requiera ejecutar la prueba del paquete correcto. Repite desde la raíz y desde el paquete, con configuraciones representativas del equipo. Compara la guía anterior con la propuesta conservando el mismo commit inicial. Así podrás atribuir una diferencia a la migración con menos variables simultáneas.

Registra versión del agente, modalidad de acceso, directorio inicial, configuración seleccionada y archivos disponibles. Si el entorno permite inspeccionar instrucciones cargadas, guarda esa evidencia junto al resultado. No aceptes como prueba suficiente que el modelo diga haber leído todo. Conserva los archivos anteriores hasta explicar las diferencias observadas y disponer de una reversión sencilla. Un despliegue por un solo paquete reduce el alcance de un error de configuración.

Define antes del ensayo qué observarás: comando ejecutado, directorio utilizado, archivos modificados y resultado de las pruebas. Una tarea puede terminar correctamente por casualidad aunque ignore el procedimiento; también puede seguirlo y descubrir un fallo previo real. Puntúa ambas dimensiones por separado. Añade un caso con una instrucción anidada y otro con una contradicción deliberada, claramente confinados al entorno de ensayo, para identificar silencios y decisiones ambiguas.

Repite las tareas para distinguir patrones de una ejecución afortunada. Revisa el coste y el tiempo como observaciones locales, sin convertir una muestra pequeña en una promesa de ahorro. Una condición razonable para avanzar es que todas las configuraciones admitidas carguen las reglas esperadas y no aparezcan regresiones inexplicadas en las tareas elegidas. Esto valida ese conjunto de casos; no demuestra que toda futura instrucción será obedecida.

Versiona las instrucciones y revísalas como parte del cambio que altera un comando o una frontera del repositorio. Las frases sensibles deben apuntar a controles verificables: si una carpeta no debe modificarse, revisa el diff automáticamente; si una prueba es obligatoria, exígela en CI. Un documento orienta al agente, pero no sustituye permisos del sistema, protección de ramas ni validaciones del producto.

Repite la prueba de compatibilidad cuando cambie la versión del agente, el modo de ejecución o la estructura de carpetas. No hace falta convertir cada edición de estilo en una campaña de evaluación: prioriza cambios que alteren alcance, precedencia o acciones exigidas. Conserva instrucciones breves y ejecutables, y elimina referencias obsoletas mediante revisión humana. El mantenimiento periódico evita que el contrato común vuelva a fragmentarse en excepciones que nadie comprueba.

Adopta una guía compartida si tu problema es la duplicación y puedes identificar entornos compatibles, propietarios y pruebas representativas. Conserva una transición explícita si dependes de configuraciones aún no cubiertas o no puedes explicar qué reglas reciben tus agentes. El éxito no consiste en borrar un archivo: consiste en reducir mantenimiento sin perder trazabilidad sobre cómo se produce un cambio.

Para un CTO, el primer entregable útil es pequeño: inventario, prueba de un paquete y criterio de reversión. Si necesitas convertir ese piloto en un flujo de ingeniería adaptado a tu organización, el servicio de agentes a medida de Wasyra puede ser el siguiente punto de conversación. Empieza por el proceso que necesitas verificar y por sus límites; la selección de herramientas viene después.