Arquivos de contexto

O Hermes Agent descobre e carrega sozinho os arquivos de contexto que moldam o comportamento dele. Alguns são locais ao projeto e vêm do seu diretório de trabalho. O SOUL.md agora é global à instância do Hermes e é carregado apenas de HERMES_HOME.

Arquivos de contexto suportados

Arquivo	Para que serve	Descoberta
.hermes.md / HERMES.md	Instruções do projeto (prioridade máxima)	Sobe até a raiz do git
AGENTS.override.md	Sobrescrita pessoal, por diretório, do AGENTS.md (normalmente no gitignore)	CWD na inicialização + subdiretórios, progressivamente
AGENTS.md	Instruções do projeto, convenções, arquitetura	CWD na inicialização + subdiretórios, progressivamente
CLAUDE.md	Arquivos de contexto do Claude Code (também detectados)	CWD na inicialização + subdiretórios, progressivamente
SOUL.md	Personalidade e tom globais desta instância do Hermes	Só HERMES_HOME/SOUL.md
.cursorrules	Convenções de código do Cursor IDE	Só o CWD
.cursor/rules/*.mdc	Módulos de regra do Cursor IDE	Só o CWD

Sistema de prioridade

Só um tipo de contexto de projeto é carregado por sessão (vale a primeira ocorrência): .hermes.md → AGENTS.override.md → AGENTS.md → CLAUDE.md → .cursorrules. O SOUL.md é sempre carregado à parte, como identidade do agente (posição #1).

Se existir um AGENTS.override.md ao lado de um AGENTS.md, a sobrescrita é carregada no lugar do arquivo versionado — mantenha um AGENTS.override.md pessoal (em geral no gitignore) quando quiser instruções diferentes das que estão commitadas no repositório, sem editar o AGENTS.md rastreado.

AGENTS.md

O AGENTS.md é o arquivo de contexto de projeto principal. Ele conta ao agente como o seu projeto está estruturado, quais convenções seguir e quaisquer instruções especiais.

Cadeia de diretórios (raiz do git → diretório de trabalho)

Quando o seu diretório de trabalho fica dentro de um repositório git, o Hermes carrega no início da sessão uma cadeia unificada de arquivos AGENTS.md: primeiro o AGENTS.md da raiz do git, depois o AGENTS.md de cada diretório intermediário até o seu diretório de trabalho. Os arquivos mais profundos aparecem depois no prompt, então a orientação mais específica prevalece. Cada arquivo ganha o próprio cabeçalho de procedência (por exemplo, ## ../../AGENTS.md), e cópias idênticas ao longo da cadeia são removidas.

monorepo/                   (raiz do git, cwd = pacotes/webapp/)
├── AGENTS.md              ← Carregado primeiro (convenções de todo o repositório)
└── pacotes/
    ├── AGENTS.md          ← Carregado em segundo
    └── webapp/
        └── AGENTS.md      ← Carregado por último (o mais específico, prevalece)

Fora de um repositório git, só o próprio diretório de trabalho é verificado — os diretórios pais nunca são consultados, então um AGENTS.md plantado em /tmp ou em $HOME não vaza para sessões sem relação.

Descoberta progressiva de subdiretórios

No início da sessão, o Hermes carrega o AGENTS.md do seu diretório de trabalho no prompt de sistema. Conforme o agente navega para subdiretórios durante a sessão (via read_file, terminal, search_files etc.), ele descobre progressivamente os arquivos de contexto desses diretórios e os injeta na conversa no momento em que passam a ser relevantes.

meu-projeto/
├── AGENTS.md              ← Carregado na inicialização (prompt de sistema)
├── frontend/
│   └── AGENTS.md          ← Descoberto quando o agente lê arquivos de frontend/
├── backend/
│   └── AGENTS.md          ← Descoberto quando o agente lê arquivos de backend/
└── compartilhado/
    └── AGENTS.md          ← Descoberto quando o agente lê arquivos de compartilhado/

Essa abordagem tem duas vantagens sobre carregar tudo na inicialização:

• Nada de prompt de sistema inchado — as dicas de subdiretório só aparecem quando fazem falta
• Preservação do cache de prompt — o prompt de sistema fica estável de um turno para o outro

Cada subdiretório é verificado no máximo uma vez por sessão. A descoberta também sobe pelos diretórios pais, então ler backend/src/main.py descobre o backend/AGENTS.md mesmo que backend/src/ não tenha arquivo de contexto próprio.

informação

Os arquivos de contexto de subdiretório passam pela mesma varredura de segurança que os arquivos de contexto da inicialização. Arquivos maliciosos são bloqueados.

Exemplo de AGENTS.md

# Contexto do projeto

Esta é uma aplicação web em Next.js 14 com um backend Python em FastAPI.

## Arquitetura
- Frontend: Next.js 14 com App Router em `/frontend`
- Backend: FastAPI em `/backend`, usa o ORM SQLAlchemy
- Banco de dados: PostgreSQL 16
- Implantação: Docker Compose em um VPS da Hetzner

## Convenções
- Use o modo estrito do TypeScript em todo o código de frontend
- O código Python segue a PEP 8, use type hints em tudo
- Todos os endpoints da API devolvem JSON no formato `{data, error, meta}`
- Os testes ficam em diretórios `__tests__/` (frontend) ou `tests/` (backend)

## Observações importantes
- Nunca altere os arquivos de migração direto — use os comandos do Alembic
- O arquivo `.env.local` tem chaves de API reais, não faça commit dele
- A porta do frontend é 3000, a do backend é 8000, a do banco é 5432

SOUL.md

O SOUL.md controla a personalidade, o tom e o estilo de comunicação do agente. Veja a página Personalidade para os detalhes completos.

Local:

• ~/.hermes/SOUL.md
• ou $HERMES_HOME/SOUL.md, se você roda o Hermes com um diretório home personalizado

Detalhes importantes:

• O Hermes cria um SOUL.md padrão automaticamente se ainda não existir nenhum
• O Hermes carrega o SOUL.md só de HERMES_HOME
• O Hermes não procura SOUL.md no diretório de trabalho
• Se o arquivo estiver vazio, nada do SOUL.md é acrescentado ao prompt
• Se o arquivo tiver conteúdo, o conteúdo é injetado literalmente depois da varredura e do corte

.cursorrules

O Hermes é compatível com o arquivo .cursorrules e com os módulos de regra .cursor/rules/*.mdc do Cursor IDE. Se esses arquivos existirem na raiz do seu projeto e nenhum arquivo de contexto de prioridade maior (.hermes.md, AGENTS.md ou CLAUDE.md) for encontrado, eles são carregados como o contexto do projeto.

Ou seja: as suas convenções do Cursor já valem automaticamente quando você usa o Hermes.

Como os arquivos de contexto são carregados

Na inicialização (prompt de sistema)

Os arquivos de contexto são carregados por build_context_files_prompt() em agent/prompt_builder.py:

1. Varre o diretório de trabalho — procura .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules (vale a primeira ocorrência)
2. Lê o conteúdo — cada arquivo é lido como texto UTF-8
3. Varredura de segurança — o conteúdo é checado contra padrões de injeção de prompt
4. Corte — arquivos acima do limite de caracteres são cortados pelo meio (70% do começo, 20% do fim, com um marcador no meio). O limite é um context_file_max_chars explícito do config.yaml quando definido; caso contrário, ele escala dinamicamente com a janela de contexto do modelo (piso de 20.000 caracteres, teto de 500.000)
5. Montagem — todas as seções são combinadas sob um cabeçalho # Project Context
6. Injeção — o conteúdo montado é acrescentado ao prompt de sistema

Durante a sessão (descoberta progressiva)

O SubdirectoryHintTracker, em agent/subdirectory_hints.py, observa os argumentos das chamadas de ferramenta em busca de caminhos de arquivo:

1. Extração de caminho — depois de cada chamada de ferramenta, os caminhos de arquivo são extraídos dos argumentos (path, workdir, comandos de shell)
2. Subida pelos ancestrais — o diretório e até 5 diretórios pais são verificados (parando nos diretórios já visitados)
3. Carga da dica — se um AGENTS.md, CLAUDE.md ou .cursorrules for encontrado, ele é carregado (o primeiro de cada diretório)
4. Varredura de segurança — a mesma varredura de injeção de prompt dos arquivos de inicialização
5. Corte — limitado a 8.000 caracteres por arquivo
6. Injeção — anexado ao resultado da ferramenta, para que o modelo o veja no contexto de forma natural

A seção final do prompt fica mais ou menos assim:

# Project Context

The following project context files have been loaded and should be followed:

## AGENTS.md

[Conteúdo do seu AGENTS.md aqui]

## .cursorrules

[Conteúdo do seu .cursorrules aqui]

[Conteúdo do seu SOUL.md aqui]

Repare que o conteúdo do SOUL entra direto, sem texto de embrulho.

Segurança: proteção contra injeção de prompt

Todos os arquivos de contexto são varridos em busca de possível injeção de prompt antes de serem incluídos. O varredor procura:

• Tentativas de sobrescrever instruções: "ignore previous instructions", "disregard your rules"
• Padrões de enganação: "do not tell the user"
• Sobrescritas do prompt de sistema: "system prompt override"
• Comentários HTML escondidos: <!-- ignore instructions -->
• Elementos div escondidos: <div style="display:none">
• Exfiltração de credenciais: curl ... $API_KEY
• Acesso a arquivos de segredo: cat .env, cat credentials
• Caracteres invisíveis: espaços de largura zero, sobrescritas bidirecionais, juntadores de palavra

Se algum padrão de ameaça for detectado, o arquivo é bloqueado:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

aviso

Este varredor protege contra os padrões comuns de injeção, mas não substitui a revisão dos arquivos de contexto em repositórios compartilhados. Sempre valide o conteúdo do AGENTS.md em projetos que não foram você que escreveu.

Limites de tamanho

Limite	Valor
Máximo de caracteres por arquivo	context_file_max_chars quando definido; caso contrário, dinâmico (escala com a janela de contexto do modelo, piso de 20.000, teto de 500.000)
Proporção cortada do começo	70%
Proporção cortada do fim	20%
Marcador de corte	10% (mostra a contagem de caracteres e sugere usar as ferramentas de arquivo)

Quando um arquivo passa do limite configurado, a mensagem de corte é esta:

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

Dicas para arquivos de contexto eficazes

Boas práticas para o AGENTS.md

1. Seja conciso — fique abaixo do seu context_file_max_chars configurado; o agente lê o arquivo a cada turno
2. Estruture com cabeçalhos — use seções ## para arquitetura, convenções e observações importantes
3. Inclua exemplos concretos — mostre os padrões de código preferidos, os formatos de API, as convenções de nomes
4. Diga o que NÃO fazer — "nunca altere os arquivos de migração direto"
5. Liste os caminhos e as portas principais — o agente usa isso nos comandos de terminal
6. Atualize conforme o projeto evolui — contexto velho é pior que contexto nenhum

Contexto por subdiretório

Em monorepos, coloque as instruções específicas de cada subdiretório em arquivos AGENTS.md aninhados:

<!-- frontend/AGENTS.md -->
# Contexto do frontend

- Use `pnpm`, não `npm`, para gerenciar pacotes
- Componentes vão em `src/components/`, páginas em `src/app/`
- Use Tailwind CSS, nunca estilos inline
- Rode os testes com `pnpm test`

<!-- backend/AGENTS.md -->
# Contexto do backend

- Use `poetry` para gerenciar dependências
- Rode o servidor de desenvolvimento com `poetry run uvicorn main:app --reload`
- Todos os endpoints precisam de docstrings OpenAPI
- Os modelos de banco ficam em `models/`, os schemas em `schemas/`

---