Контекстные файлы

Агент Гермес автоматически обнаруживает и загружает контекстные файлы, которые определяют его поведение. Некоторые из них локальны для проекта и находятся в вашем рабочем каталоге. SOUL.md теперь доступен для экземпляра Hermes и загружается только из HERMES_HOME.

Поддерживаемые контекстные файлы

Файл Назначение Обнаружение
.hermes.md / HERMES.md Инструкции проекта (наивысший приоритет) Поднимается до прихода git
AGENTS.md Инструкции проекта, соглашения, архитектура Текущий рабочий каталог при запуске + подкаталоги прогрессивно
CLAUDE.md Контекстные файлы Claude Code (также обнаруживаются) Текущий рабочий каталог при запуске + подкаталоги прогрессивно
ДУША.md Глобальная настройка личности и тона для этого экземпляра Hermes Только HERMES_HOME/SOUL.md
.cursorrules поворот по коду из Cursor IDE Только текущий рабочий каталог
.cursor/rules/*.mdc Модули правил Курсор IDE Только текущий рабочий каталог
За сессию загружается только один тип контекста проекта (первое совпадение выигрывает): .hermes.mdAGENTS.mdCLAUDE.md.cursorrules. SOUL.md всегда загружается независимо от идентичности агента (слот №1).
##AGENTS.md

AGENTS.md — это основной файл контекста проекта. Он сообщает агенту, как структурирован ваш проект, какие соглашения соблюдаются и какие специальные инструкции.

Прогрессивное обнаружение подкаталогов

При запуске сессии Hermes загружает AGENTS.md из вашего рабочего каталога в системный запрос. Когда агент перемещается в подкаталоги во время сеанса (через read_file, terminal, search_files и т.д.), он прогрессивно обнаруживает контекстные файлы в этих каталогах и включает их в разговор в тот момент, когда они становятся актуальными.

my-project/
├── AGENTS.md              ← Загружается при запуске (системный промпт)
├── frontend/
│   └── AGENTS.md          ← Обнаруживается, когда агент читает файлы frontend/
├── backend/
│   └── AGENTS.md          ← Обнаруживается, когда агент читает файлы backend/
└── shared/
    └── AGENTS.md          ← Обнаруживается, когда агент читает файлы shared/

Такой подход имеет два преимущества перед загрузкой сразу при запуске: - Нет раздувания системного промпта — подсказки подкаталогов механических устройств только тогда, когда это необходимо - Сохранение кэша промптов — системный запрос остается стабильным между шагами.

Каждый подкаталог теперь появляется не более одного раза за сессию. Обнаружение также поднимается по родительским каталогам, так что чтение backend/src/main.py приводит к backend/AGENTS.md, если даже в backend/src/ нет собственного контекстного файла.:::информация Файлы контекста подкаталогов передают ту же проверку безопасности, что и файлы при запуске. Вредоносные файлы блокируются.

Пример AGENTS.md

# Контекст проекта

Это веб-приложение Next.js 14 с бэкендом на Python FastAPI.

## Архитектура
- Фронтенд: Next.js 14 с App Router в `/frontend`
- Бэкенд: FastAPI в `/backend`, использует SQLAlchemy ORM
- База данных: PostgreSQL 16
- Развёртывание: Docker Compose на VPS Hetzner

## Соглашения
- Используйте строгий режим TypeScript для всего кода фронтенда
- Код Python следует PEP 8, используйте подсказки типов везде
- Все конечные точки API возвращают JSON в формате `{data, error, meta}`
- Тесты находятся в каталогах `__tests__/` (фронтенд) или `tests/` (бэкенд)

## Важные замечания
- Никогда не изменяйте файлы миграций напрямую — используйте команды Alembic
- В файле `.env.local` находятся реальные ключи API, не коммитьте его
- Порт фронтенда 3000, бэкенда 8000, БД 5432

ДУША.md

SOUL.md управляет идентификацией, тоном и стилем общения агента. См. страница Личность для полной информации.

Расположение:

Важные детали:

.cursorrules

Hermes совместим с файлом .cursorrules из Cursor IDE и модулями правил .cursor/rules/*.mdc. Если эти файлы существуют в корне вашего проекта и не найден контекст файла с более низким приоритетом (.hermes.md, AGENTS.md или CLAUDE.md), они загружаются как контекст проекта.

Это означает, что курсор вашего временного соглашения автоматически применяется при использовании Hermes.

Как загружаются контекстные файлы

При запуске (системный запрос)

Контекстные файлы загружаются с помощью build_context_files_prompt() в agent/prompt_builder.py:

  1. Сканирование рабочего каталога — последнее наличие .hermes.mdAGENTS.mdCLAUDE.md.cursorrules (первое совпадение выигрывает)
  2. Чтение оценки — каждый файл читается как текст UTF-8.
  3. Проверка безопасности — традиционное наличие шаблонов инъекций промптов
  4. Усечение — размеры, превышающие 20 000 символов, усекаются по голове/хвосту (70% головы, 20% хвоста, с маркером посередине)
  5. Сборка — все разделы объединяются под заголовком #Project Context
  6. Внедрение — собранное правило добавляется в системный запрос.

Во время сессии (прогрессивное обнаружение)

SubdirectoryHintTracker в agent/subdirectory_hints.py отслеживает аргументы вызовов инструментов на предметных путях к файлам:

  1. Извлечение пути — после каждого вызова инструмента из аргументов извлекаются пути к файлам (path, workdir, команды обработки)
  2. Обход предков — проверяются каталог и до 5 родительских каталогов (останавливаясь на уже посещённых каталогах)
  3. Загрузка подсказки — если найдены AGENTS.md, CLAUDE.md или .cursorrules, он загружается (первое совпадение в каталоге)
  4. Проверка безопасности — та же проверка обновлений, подсказок и файлов при запуске.
  5. Усечение — ограничено 8 000 символов в файле.
  6. Внедрение — добавляется к результату инструмента, так что модель видит его в нескольких вариантах.

Заключительный раздел-промпта выглядит примерно так:

# Project Context

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

## AGENTS.md

[Содержимое вашего AGENTS.md здесь]

##.cursorrules

[Содержимое вашего.cursorrules здесь]

[Содержимое вашего SOUL.md здесь]

Обратите внимание, что критерий SOUL вставляется напрямую, без дополнительных текст-обёрток.

Защита: предотвращение инъекций

Все контекстные файлы сканируются на предмет возможных инъекций перед включением. Сканер на днях:

Если обнаружен какой-либо опасный шаблон, файл блокируется:

[ЗАБЛОКИРОВАНО: AGENTS.md содержит потенциальную инъекцию промпта (prompt_injection). Содержимое не загружено.]
```:::предупреждение
Этот сканер защищает от распространённых шаблонов инъекций, но не заменяет проверку контекстных файлов в базовых репозиториях. Всегда проверяйте критерии AGENTS.md в проектах, которые вы не создали.</div>
## Ограничения по размеру

| Лимит | Значение |
|-------|---------|
| Макс. символы в файле | 20 000 (~7 000 токенов) |
| Соотношение усечения головы | 70% |
| Соотношение усечения хвоста | 20% |
| Маркер усечения | 10% (показывает количество символов и предлагает использовать финансовые инструменты) |

Когда файл накапливает 20 000 символов, сообщение об усечении выглядит так:

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

## Советы по эффективным контекстным файлам<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p> Лучшие практики для AGENTS.md
1. **Будьте кратки**  оставайтесь значительно ниже 20 тыс. символов; агент читает каждый его шаг
2. **Структурируйте с заголовками**  воспользуйтесь разделами `##` для структур, соглашений, важных замечаний.
3. **Включите конкретные примеры**  показывайте постоянные шаблоны кода, формы API, соглашения об именовании.
4. **Упоминайте, чего НЕ делать**  «никогда не изменяйте файлы миграции напрямую»
5. **Перечислите ключевые пути и порты**  агент использует их для терминальных команд.
6. **Обновляйте меньшую степень развития проекта**  контекстный контекст хуже, чем его отсутствие</div>
### Контекст для каждого подкаталога

Для монорепозиториев вставьте инструкции для определенных подкаталогов во вложенные файлы AGENTS.md:
```markdown
<!-- frontend/AGENTS.md -->
# Контекст фронтенда

- Используйте `pnpm`, а не `npm` для управления пакетами
- Компоненты находятся в `src/components/`, страницы в `src/app/`
- Используйте Tailwind CSS, никогда не используйте встроенные стили
- Запускайте тесты с помощью `pnpm test`
<!-- backend/AGENTS.md -->
# Контекст бэкенда

- Используйте `poetry` для управления зависимостями
- Запускайте сервер разработки с помощью `poetry run uvicorn main:app --reload`
- Все конечные точки должны иметь docstrings OpenAPI
- Модели базы данных находятся в `models/`, схемы в `schemas/`