Files

На этой странице

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

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

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

Система приоритетов

За сессию загружается только один тип контекста проекта (побеждает первый найденный): .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. SOUL.md всегда загружается независимо как идентичность агента (слот #1).

AGENTS.md​

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

Последовательное обнаружение в поддиректориях​

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

[code]

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

[/code]

Такой подход имеет два преимущества перед загрузкой всего сразу при запуске:

• Нет раздувания системного промпта — подсказки для поддиректорий появляются только когда нужны
• Сохранение кеша промптов — системный промпт остаётся стабильным от шага к шагу

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

info

Контекстные файлы поддиректорий проходят ту же проверку безопасности, что и контекстные файлы запуска. Вредоносные файлы блокируются.

Пример AGENTS.md​

[code]

# Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

## Architecture  
- Frontend: Next.js 14 with App Router in `/frontend`  
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM  
- Database: PostgreSQL 16  
- Deployment: Docker Compose on a Hetzner VPS

## Conventions  
- Use TypeScript strict mode for all frontend code  
- Python code follows PEP 8, use type hints everywhere  
- All API endpoints return JSON with `{data, error, meta}` shape  
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

## Important Notes  
- Never modify migration files directly — use Alembic commands  
- The `.env.local` file has real API keys, don't commit it  
- Frontend port is 3000, backend is 8000, DB is 5432

[/code]

SOUL.md​

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

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

• ~/.hermes/SOUL.md
• или $HERMES_HOME/SOUL.md, если вы запускаете Hermes с пользовательской домашней директорией

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

• Hermes автоматически создаёт SOUL.md по умолчанию, если файл ещё не существует
• Hermes загружает SOUL.md только из HERMES_HOME
• Hermes не ищет SOUL.md в рабочей директории
• Если файл пуст, содержимое из SOUL.md не добавляется в промпт
• Если файл содержит текст, он вставляется дословно после проверки и обрезки

.cursorrules​

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

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

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

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

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

1. Сканирование рабочей директории — проверяет наличие .hermes.md → AGENTS.md → CLAUDE.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. Внедрение — добавляется к результату инструмента, так что модель видит это в контексте естественным образом

Итоговый раздел промпта выглядит примерно так:

[code]

# Project Context

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

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

[/code]

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

Безопасность: защита от инъекций в промпт​

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

• Попытки переопределения инструкций: «ignore previous instructions», «disregard your rules»
• Паттерны обмана: «do not tell the user»
• Переопределения системного промпта: «system prompt override»
• Скрытые HTML-комментарии: <!-- ignore instructions -->
• Скрытые элементы div: <div style="display:none">
• Кража учётных данных: curl ... $API_KEY
• Доступ к секретным файлам: cat .env, cat credentials
• Невидимые символы: пробелы нулевой ширины, двунаправленные переопределения, соединители слов

Если обнаружен какой-либо из угрожающих паттернов, файл блокируется:

[code]

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

[/code]

warning

Этот сканер защищает от распространённых паттернов инъекций, но не заменяет проверку контекстных файлов в общих репозиториях. Всегда проверяйте содержимое AGENTS.md в проектах, которые вы не создавали.

Ограничения по размеру​

Ограничение	Значение
Максимальное количество символов на файл	20 000 (~7 000 токенов)
Доля обрезки начала	70%
Доля обрезки конца	20%
Маркер обрезки	10% (показывает количество символов и предлагает использовать файловые инструменты)

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

[code]

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

[/code]

Советы по эффективным контекстным файлам​

Лучшие практики для AGENTS.md

1. Будьте краткими — оставайтесь значительно ниже 20 000 символов; агент читает это на каждом шаге
2. Используйте заголовки — применяйте секции ## для архитектуры, соглашений, важных заметок
3. Включайте конкретные примеры — показывайте предпочитаемые паттерны кода, структуру API, соглашения об именовании
4. Указывайте, что НЕ нужно делать — «никогда не изменяйте файлы миграций напрямую»
5. Перечисляйте ключевые пути и порты — агент использует их для команд в терминале
6. Обновляйте по мере развития проекта — устаревший контекст хуже, чем его отсутствие

Контекст для поддиректорий​

Для монорепозиториев помещайте инструкции для конкретных поддиректорий во вложенные файлы AGENTS.md:

[code]

<!-- frontend/AGENTS.md -->  
# Frontend Context

- Use `pnpm` not `npm` for package management  
- Components go in `src/components/`, pages in `src/app/`  
- Use Tailwind CSS, never inline styles  
- Run tests with `pnpm test`

[/code]

[code]

<!-- backend/AGENTS.md -->  
# Backend Context

- Use `poetry` for dependency management  
- Run the dev server with `poetry run uvicorn main:app --reload`  
- All endpoints need OpenAPI docstrings  
- Database models are in `models/`, schemas in `schemas/`

[/code]

• Поддерживаемые контекстные файлы
• AGENTS.md
• Последовательное обнаружение в поддиректориях
• Пример AGENTS.md
• SOUL.md
• .cursorrules
• Как загружаются контекстные файлы
• При запуске (системный промпт)
• В ходе сессии (последовательное обнаружение)
• Безопасность: защита от инъекций в промпт
• Ограничения по размеру
• Советы по эффективным контекстным файлам
• Контекст для поддиректорий