Você abre uma sessão em packages/webapp/ dentro de um monorepo grande e espera que o agente conheça as convenções do time: política de commits, regras de branch, fluxo de CI. Mas o Hermes só enxerga o AGENTS.md daquele diretório — o arquivo da raiz do repositório, onde essas convenções moram, fica invisível. Resultado: ou você repete as regras em todo lugar, ou assiste o agente quebrá-las uma a uma. Esta semana isso muda: o Hermes mescla automaticamente a cadeia inteira, da raiz do git até o seu diretório de trabalho.

No fundo de um monorepo, o Hermes costumava ver apenas uma camada

AGENTS.md é o principal arquivo de contexto de projeto do Hermes Agent: ele diz ao agente como seu projeto é estruturado, quais convenções seguir e com o que se preocupar. Mas, anteriormente, se você iniciasse uma sessão em monorepo/packages/webapp/, o Hermes carregava apenas o AGENTS.md do diretório atual — o arquivo da raiz do repositório com as convenções “do repositório inteiro” (política de commits, estratégia de branches, fluxo de CI) ficava invisível, a menos que você o duplicasse em cada diretório profundo.

A duplicação traz seus próprios problemas: divergência, atualizações dessincronizadas, orçamento de contexto desperdiçado.

A cadeia de diretórios mesclada no main do Hermes Agent em 2026-08-08 resolve isso: sempre que seu diretório de trabalho está dentro de um repositório git, a inicialização da sessão carrega uma cadeia mesclada de arquivos AGENTS.md — raiz do git primeiro, cada diretório intermediário e depois o cwd — no prompt do sistema. O mecanismo é um port do directoryChain do grok-cli.

Como a cadeia funciona

monorepo/                       (raiz do git, cwd = packages/webapp/)
├── AGENTS.md                  ← carregado primeiro (convenções do repositório inteiro)
└── packages/
    ├── AGENTS.md              ← carregado em segundo
    └── webapp/
        └── AGENTS.md          ← carregado por último (mais específico, tem precedência)

Comportamentos principais:

• Rótulos de proveniência: cada arquivo é injetado sob um cabeçalho de caminho relativo como ## ../../AGENTS.md ou ## AGENTS.md, para que o agente saiba de qual diretório veio cada regra;
• Mais profundo vence: arquivos mais profundos aparecem depois no prompt, então orientações mais específicas têm precedência sobre as do repositório inteiro;
• Deduplicação de conteúdo: conteúdo idêntico encontrado novamente ao longo da cadeia (arquivos copiados ou symlinks) é mantido apenas uma vez — sem desperdício de contexto;
• Limites de orçamento: cada arquivo passa pelo seu próprio orçamento de truncamento, e a cadeia mesclada tem um teto total adicional — um monorepo profundo não pode multiplicar o gasto de arquivos de contexto sem limite;
• Varredura de segurança: todo arquivo passa pela varredura de ameaças de arquivos de contexto existente (_scan_context_content) antes de poder entrar no prompt do sistema; conteúdo malicioso é bloqueado.

Fora de um repositório git: diretórios pais nunca vazam

A cadeia tem uma fronteira de segurança deliberada: se o diretório de trabalho não estiver dentro de um repositório git, a cadeia é apenas [cwd] — diretórios pais nunca são consultados. Um AGENTS.md plantado em /tmp ou $HOME nunca pode, portanto, vazar para sessões não relacionadas, espelhando a lógica de segurança existente do .hermes.md.

O sistema de prioridade: um tipo de arquivo de contexto por sessão

Note que a cadeia de diretórios se aplica apenas ao AGENTS.md. Os tipos de contexto de projeto do Hermes são resolvidos por prioridade:

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

(Apenas o primeiro tipo correspondente é carregado por sessão; SOUL.md é carregado independentemente como persona global.) Então, se a raiz do seu repositório usa CLAUDE.md (estilo Claude Code), a cadeia não se aplica — CLAUDE.md continua sendo lido apenas do cwd. Quer a cadeia? Use AGENTS.md.

Como isso difere da descoberta progressiva de subdiretórios

Leitores assíduos talvez já conheçam o outro mecanismo do Hermes: quando o agente lê arquivos em um subdiretório no meio da sessão, ele descobre progressivamente e injeta o AGENTS.md daquele diretório sob demanda (cada subdiretório é verificado no máximo uma vez por sessão). A cadeia de diretórios complementa isso:

Mecanismo	Momento	Cobertura
Cadeia de diretórios (nova)	No início da sessão	A cadeia vertical raiz do git → cwd, no prompt do sistema
Descoberta progressiva de subdiretórios	Durante a sessão	Subdiretórios horizontais que o agente realmente visita, injetados sob demanda

Ambos são protegidos pela mesma varredura de segurança, e nenhum perturba a estabilidade de bytes do prompt do sistema (amigável ao cache de prompt).

Playbook de monorepo: dividindo AGENTS.md em três camadas

O uso natural da cadeia é o empilhamento por granularidade:

# AGENTS.md da raiz do repositório (nível monorepo)
## Convenções compartilhadas
- Todo PR deve passar no CI e no lint
- Mensagens de commit seguem Conventional Commits
- Entradas de changelog vão para CHANGELOG.md

# packages/AGENTS.md (nível de pacote)
## Regras de pacote
- Novos pacotes devem ser registrados no registry
- Dependências entre pacotes passam apenas por APIs públicas

# packages/webapp/AGENTS.md (nível de diretório, mais específico)
## Específico de frontend
- Componentes usam TypeScript em modo estrito
- Estilos usam apenas design tokens — sem cores inline
- Testes ficam em __tests__/, rodam com Vitest

Uma sessão iniciada em packages/webapp/ recebe as três camadas: convenções do repositório como base, regras do pacote por cima e especificidades de frontend por último. Ao mexer em código de frontend, o agente não escreverá commits que violem a política do repositório nem usará cores inline que quebrem o design system.

Dicas de atualização

1. Afunde as convenções do repositório inteiro (branch/commit/CI) em um AGENTS.md na raiz; diretórios profundos devem conter apenas regras que genuinamente pertencem àquela camada — nada de cópia;
2. Não copie o mesmo conteúdo para vários diretórios — a cadeia deduplica, mas “armazenar uma vez” é a resposta certa de qualquer forma;
3. Migrando do Claude Code / Cursor? Renomeie o CLAUDE.md da raiz para AGENTS.md (ou adicione um AGENTS.md) e você ganha a cadeia inteira.

Para ir mais longe na confiabilidade de tarefas longas, veja nosso guia de configuração de tarefas longas e timeouts; os arquivos de contexto combinam bem com as dicas de produtividade. Novo no Hermes Agent? Comece pelo guia de instalação antes de experimentar.

Resumo: organize o AGENTS.md em três camadas — repositório, pacote, diretório — e o Hermes monta o contexto completo do projeto automaticamente no início da sessão: convenções genéricas nunca se perdem, regras específicas naturalmente ficam por último, e tudo acontece com zero esforço.