AGENTS.md vs CLAUDE.md: por qué no hay estándar para agentes de IA

El problema: cada agente de IA lee las instrucciones a su manera

El formato de archivo que un asistente de programación acepta como «manual del proyecto» se ha convertido en el nuevo campo de batalla del desarrollo de software. Mientras algunas herramientas buscan AGENTS.md o .agents/skills, otras solo atienden a CLAUDE.md, y unas terceras esperan archivos propietarios. En un monorepositorio con miles de desarrolladores, esa fragmentación deja a cada agente con una visión parcial del proyecto.

El resultado, según Infosworld, ya está medido: un estudio de la Universidad Federal de Minas Gerais revisó 100 repositorios open source populares con archivos Agents.md o Claude.md y encontró que 91 de ellos contenían al menos un «smell», un defecto estructural en el propio archivo de configuración.

Por qué importa en un monorepositorio

El problema escala rápido cuando varios agentes comparten base de código. Los archivos de configuración se cargan al inicio de cada sesión y, según la documentación del Agent SDK de Anthropic, CLAUDE.md se inyecta en la conversación como contexto de proyecto, no como system prompt. Es decir, influye en el comportamiento del modelo, pero no lo garantiza: una instrucción mal redactada, obsoleta o contradictoria se diluye.

🤖 La IA no es solo para leer sobre ella

En la comunidad la aplicamos: automatización, agentes IA y herramientas reales para emprender, no solo para informarte.

👥 Aplicarla en la comunidad

Cuando distintos agentes trabajan con información incompleta o desactualizada respecto al resto del equipo, surgen inconsistencias que obligan a supervisión manual y correcciones posteriores. Algunas empresas han improvisado scripts que sincronizan instrucciones entre formatos, pero esa capa añade complejidad técnica y deuda operativa sin resolver el problema de raíz.

El catálogo de «olores» que ya mide el daño

La investigación brasileña propone el primer catálogo de configuration smells para archivos de agentes de IA. Los seis más frecuentes:

Lint leakage (62%): reglas de estilo que ya aplican los linters del proyecto y se duplican en el archivo del agente, gastando tokens.
Context bloat (42%): archivos sobredimensionados con reglas, ejemplos y detalles de baja prioridad que distraen al modelo.
Skill leakage (35%): instrucciones raras o muy específicas que se cargan en cada sesión aunque la tarea no las necesite.
Conflicting instructions (28%): reglas que se contradicen entre sí y obligan al modelo a elegir al azar.
Init fossilization (24%): archivos generados una vez y nunca revisados, llenos de reglas obsoletas.
Blind reference (16%): enlaces a otros archivos sin explicar qué son ni cuándo usarlos.

El estudio detecta además que los smells se retroalimentan: la combinación de skill leakage e instrucciones contradictorias eleva en un 83% la probabilidad de generar context bloat, según Infosworld.

Anthropic recomienda mantener CLAUDE.md por debajo de 200 líneas para mitigar el context bloat. Cada token cuenta: el system prompt de Claude Code ronda los 2.300-3.600 tokens y las definiciones de herramientas suman 14.000-17.000 tokens adicionales por sesión, según documentación recogida por TechTimes.

Estándares en formación y movimientos del mercado

El vacío lo están llenando actores con intereses distintos. Harness, la plataforma de delivery de software cofundada por Jyoti Bansal, lanzó a finales de agosto su Agent-Ready Code Repository y un AI Code Review diseñado para operar con Model Context Protocol (MCP) e interfaces CLI. El propio Bansal lo justifica así, según SiliconAngle: «Los repositorios fueron escritos hace más de 15 años, sin organización ni pensando en cómo los leería una máquina». En pruebas internas, Harness afirma haber ahorrado unas 10.000 horas en el último mes solo en su propia organización.

En paralelo, la comunidad ha convertido a CLAUDE.md en un fenómeno cultural. El desarrollador Forrest Chang destiló en enero de 2026 un post de Andrej Karpathy en un documento de cuatro reglas que, según TechTimes, acumula más de 200.000 estrellas combinadas en GitHub. Una versión extendida de diez reglas empezó a circular a finales de junio con disciplina de verificación, criterios de «hecho» verificables y un vocabulario de errores recurrentes —Kitchen Sink, Wrong Abstraction, Optimistic Path, Runaway Refactor— que el agente debe reconocer y detenerse.

El movimiento no es solo DX, también es seguridad. Investigadores de la University of Missouri-Kansas City demostraron con Ghostcommit, según BleepingComputer, que un AGENTS.md malicioso puede esconder instrucciones dentro de un PNG y conseguir que Cursor ejecutando Claude Sonnet exfiltre el archivo .env en un solo intento. Su encuesta sobre 6.480 pull requests en los 300 repositorios públicos más activos halló que el 73% de los PRs mergeados llegaron a la rama por defecto sin revisión humana sustantiva ni revisión de bot.

Mientras tanto, el Ministerio de Industria y Tecnología de China (MIIT) advirtió en julio que versiones de Claude Code entre la 2.1.91 y la 2.1.196 contenían una «vulnerabilidad de back-door» que podía enviar información sensible sin consentimiento, y Alibaba prohibió a sus empleados usar la herramienta desde el 10 de julio, ordenándoles migrar a su plataforma propia Qoder, según CNBC.

Qué significa esto para tu startup

Para un equipo pequeño o mediano, el coste no es solo filosófico: es medible. Investigaciones recogidas por TechTimes estiman que las tareas agentic gastan alrededor de 4 veces más tokens que una conversación estándar, y los sistemas multi-agente pueden llegar a 15 veces ese coste. Cuando los archivos de configuración están mal redactados, ese multiplicador opera sobre instrucciones redundantes o contradictorias que degradan los resultados.

La fragmentación de formatos también bloquea el retorno de inversión en herramientas de IA: cada nuevo agente exige traducir el manual del proyecto, mantener varios archivos sincronizados o aceptar que cada asistente opere con una versión distinta de la realidad.

Acciones concretas que puedes aplicar esta semana

Audita tu archivo de instrucciones hoy mismo. Mide cuántas líneas tiene tu CLAUDE.md o AGENTS.md. Si supera las 200, recórtalo: deja solo reglas específicas del proyecto (build, tests, convenciones) y mueve las dependencias o detalles de tarea a archivos separados con nombres descriptivos.
Adopta un único formato canónico y versiona los demás. Elige el archivo que lean todos tus agentes y mantenlo como fuente única. Si necesitas compatibilidad temporal con otra herramienta, genera los archivos derivados con un script en CI, no a mano. Así cada cambio se revisa una sola vez.
Añade un reviewer que abra los adjuntos. Dado que el 73% de los PRs en repos activos pasan sin revisión sustantiva, integra una herramienta que analice también imágenes y archivos no textuales referenciados desde AGENTS.md, no solo el código visible.
Define condiciones de parada verificables antes de lanzar un loop. El comando /goal introducido en Claude Code 2.1.139 en mayo de 2026 usa un modelo verificador independiente para comprobar si se cumple el criterio de «hecho». Sin ese tipo de guardarraíl, un loop autónomo de horas puede multiplicar una mala dirección por miles de líneas.