🏠 Главная › User Guide › context files

sidebar_position: 8 title: "Context Files" description: "Project context files — .hermes.md, AGENTS.md, CLAUDE.md, global SOUL.md, and .cursorrules — automatically injected into every conversation" lang: ru

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

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

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

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

:::информация Система приоритетов За сеанс загружается только один тип контекста проекта (выигрывает первое совпадение): .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

ДУША.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.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. Усечение — ограничение до 8000 символов на файл.
  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/`