Trabajas en un monorepo y abres una sesión en packages/webapp/. El agente solo ve el AGENTS.md que está justo ahí: el de la raíz del repositorio, con las convenciones del equipo, queda fuera de su alcance. Así que repites las reglas en cada directorio, o ves cómo el agente las incumple sin darse cuenta. Esta semana Hermes cambia eso: fusiona toda la cadena automáticamente.

En lo profundo de un monorepo, Hermes solía ver solo una capa

AGENTS.md es el archivo de contexto principal del proyecto de Hermes Agent: le dice al agente cómo está estructurado tu proyecto, qué convenciones seguir y a qué estar atento. Pero antes, si iniciabas una sesión en monorepo/packages/webapp/, Hermes cargaba solo el AGENTS.md del directorio actual — el archivo de la raíz del repo con las convenciones de “todo el repo” (política de commits, estrategia de ramas, flujo de CI) era invisible, a menos que lo duplicaras en cada directorio profundo.

La duplicación trae sus propios problemas: desincronización, actualizaciones no sincronizadas, presupuesto de contexto desperdiciado.

La cadena de directorios integrada en main de Hermes Agent el 2026-08-08 arregla esto: cuando tu directorio de trabajo está dentro de un repositorio git, el arranque de la sesión carga en el prompt de sistema una cadena fusionada de archivos AGENTS.md — primero la raíz de git, luego cada directorio intermedio, y por último el cwd. El mecanismo es un port del directoryChain de grok-cli.

Cómo funciona la cadena

monorepo/                       (raíz de git, cwd = packages/webapp/)
├── AGENTS.md                  ← se carga primero (convenciones de todo el repo)
└── packages/
    ├── AGENTS.md              ← se carga segundo
    └── webapp/
        └── AGENTS.md          ← se carga al final (el más específico, tiene prioridad)

Comportamientos clave:

• Etiquetas de provenance: cada archivo se inyecta bajo un encabezado con ruta relativa como ## ../../AGENTS.md o ## AGENTS.md, para que el agente pueda saber de qué directorio proviene cada regla;
• Gana lo más profundo: los archivos más profundos aparecen más tarde en el prompt, así que la guía más específica tiene prioridad sobre la guía de todo el repo;
• Deduplicación de contenido: si a lo largo de la cadena se vuelve a encontrar contenido idéntico (archivos copiados o symlinks), se conserva solo una vez — sin presupuesto de contexto desperdiciado;
• Topes de presupuesto: cada archivo pasa por su propio tope de truncamiento, y la cadena fusionada tiene además un tope total — un monorepo profundo no puede multiplicar el gasto de archivos de contexto sin límite;
• Escaneo de seguridad: cada archivo pasa por el escaneo de amenazas existente para archivos de contexto (_scan_context_content) antes de poder entrar en el prompt de sistema; el contenido malicioso queda bloqueado.

Fuera de un repo git: los directorios padre nunca se filtran

La cadena tiene un límite de seguridad deliberado: si el directorio de trabajo no está dentro de un repositorio git, la cadena es solo [cwd] — los directorios padre nunca se consultan. Un AGENTS.md plantado en /tmp o en $HOME por tanto nunca puede filtrarse a sesiones no relacionadas, reflejando la misma lógica de seguridad del .hermes.md existente.

El sistema de prioridad: un tipo de archivo de contexto por sesión

Ten en cuenta que la cadena de directorios se aplica solo a AGENTS.md. Los tipos de archivos de contexto del proyecto de Hermes se resuelven por prioridad:

.hermes.md / HERMES.md  →  AGENTS.md  →  CLAUDE.md  →  .cursorrules

(Solo se carga el primer tipo que coincida por sesión; SOUL.md se carga de forma independiente como persona global.) Así que si la raíz de tu repo usa CLAUDE.md (estilo Claude Code), la cadena no se aplica — CLAUDE.md se sigue leyendo solo desde el cwd. ¿Quieres la cadena? Usa AGENTS.md.

En qué se diferencia del descubrimiento progresivo de subdirectorios

Los lectores habituales quizá ya conozcan el otro mecanismo de Hermes: cuando el agente lee archivos en un subdirectorio a mitad de sesión, descubre progresivamente e inyecta el AGENTS.md de ese directorio bajo demanda (cada subdirectorio se comprueba como máximo una vez por sesión). La cadena de directorios lo complementa:

Mecanismo	Momento	Cobertura
Cadena de directorios (nueva)	Al inicio de la sesión	La cadena vertical raíz de git → cwd, en el prompt de sistema
Descubrimiento progresivo de subdirectorios	Durante la sesión	Los subdirectorios horizontales que el agente visita realmente, inyectados bajo demanda

Ambos están protegidos por el mismo escaneo de seguridad, y ninguno altera la estabilidad en bytes del prompt de sistema (compatible con prompt-cache).

Manual del monorepo: dividir AGENTS.md en tres capas

El uso natural de la cadena es el apilamiento por granularidad:

# AGENTS.md de la raíz del repo (nivel monorepo)
## Convenciones compartidas
- Cada PR debe pasar CI y lint
- Los mensajes de commit siguen Conventional Commits
- Las entradas de changelog van a CHANGELOG.md

# packages/AGENTS.md (nivel paquete)
## Reglas del paquete
- Los paquetes nuevos deben registrarse en el registro
- Las dependencias entre paquetes pasan solo por las APIs públicas

# packages/webapp/AGENTS.md (nivel directorio, el más específico)
## Específico del frontend
- Los componentes usan el modo estricto de TypeScript
- El estilo usa solo design tokens — nada de colores en línea
- Las pruebas viven en __tests__/, se ejecutan con Vitest

Una sesión iniciada en packages/webapp/ recibe las tres capas: las convenciones del repo como base, las reglas del paquete encima, y al final los detalles del frontend. Al tocar código del frontend, el agente no escribirá commits que violen la política del repo, ni colores en línea que rompan el sistema de diseño.

Consejos para actualizar

1. Hunde las convenciones de todo el repo (rama/commit/CI) en un AGENTS.md de la raíz; los directorios profundos deben contener solo las reglas que realmente pertenecen a esa capa — nada de copiar;
2. No copies el mismo contenido en varios directorios — la cadena deduplica, pero “guardar una sola vez” es igualmente la respuesta correcta;
3. ¿Migrando desde Claude Code / Cursor? Renombra el CLAUDE.md de la raíz a AGENTS.md (o añade un AGENTS.md) y obtienes toda la cadena.

Para llevar la fiabilidad de las tareas largas más lejos, consulta nuestra guía de configuración de tareas largas y timeouts; los archivos de contexto combinan bien con los consejos de productividad. ¿Nuevo en Hermes Agent? Empieza por la guía de instalación antes de experimentar.

Conclusión: organiza AGENTS.md en tres capas — repo, paquete, directorio — y Hermes ensambla automáticamente el contexto completo del proyecto al inicio de la sesión: las convenciones genéricas nunca se pierden, las reglas específicas aterrizan naturalmente al final, y todo ocurre con cero esfuerzo.