🏠 Главная › Документация › Возможности

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

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 Только текущая рабочая директория

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

AGENTS.md

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

Постепенное обнаружение поддиректорий

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

my-project/
├── AGENTS.md              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

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

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

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

Пример AGENTS.md

# 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

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, shell-команды)

  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

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

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

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

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

При обнаружении любого паттерна угрозы файл блокируется:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
Этот сканер защищает от распространённых паттернов инъекций, но не заменяет проверку контекстных файлов в общих репозиториях. Всегда проверяйте содержимое AGENTS.md в проектах, которые вы не создавали.

Ограничения размера

Ограничение Значение
Макс. символов на файл 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.]

Советы по эффективному использованию контекстных файлов

tip Рекомендации по AGENTS.md

  1. Будьте кратки — старайтесь значительно не превышать 20 тыс. символов; агент читает это на каждом шагу

  2. Структурируйте заголовками — используйте секции ## для архитектуры, соглашений, важных заметок

  3. Приводите конкретные примеры — покажите предпочтительные шаблоны кода, формы API, соглашения об именовании

  4. Указывайте, чего НЕ делать — «никогда не изменяйте файлы миграций напрямую»

  5. Перечисляйте ключевые пути и порты — агент использует их для терминальных команд

  6. Обновляйте по мере развития проекта — устаревший контекст хуже, чем его отсутствие

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

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

<!-- 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`

<!-- 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/`