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

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

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

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

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

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

AGENTS.md

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

Прогрессивный поиск в поддиректориях

При запуске сессии VibeOS загружает 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

SOUL.md

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

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

~/.vibeos/SOUL.md
или $VIBEOS_HOME/SOUL.md, если вы запускаете VibeOS с пользовательской домашней директорией

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

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

.cursorrules

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

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

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

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

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

Сканирование рабочей директории — проверяет .vibeos.md → AGENTS.md → CLAUDE.md → .cursorrules (первый найденный выигрывает)
Чтение содержимого — каждый файл читается как текст в кодировке UTF-8
Проверка безопасности — содержимое проверяется на наличие шаблонов инъекций в промпт
Усечение — файлы, превышающие context_file_max_chars символов (по умолчанию 20 000), усекаются по принципу «начало/конец» (70% начало, 20% конец, с маркером посередине)
Сборка — все разделы объединяются под заголовком # Project Context
Внедрение — собранное содержимое добавляется в системный промпт

Во время сессии (прогрессивный поиск)

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

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

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

# Project Context

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

## AGENTS.md

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

## .cursorrules

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

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

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

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

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

Попытки переопределить инструкции: «игнорируй предыдущие инструкции», «отмени свои правила»
Шаблоны обмана: «не говори пользователю»
Переопределение системного промпта: «переопределение системного промпта»
Скрытые HTML-комментарии: 
Скрытые элементы div: <div style="display:none">
Кража учётных данных: curl ... $API_KEY
Доступ к секретным файлам: cat .env, cat credentials
Невидимые символы: пробелы нулевой ширины, двунаправленные переопределения, соединители слов

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

[ЗАБЛОКИРОВАНО: AGENTS.md содержит потенциальную инъекцию в промпт (prompt_injection). Содержимое не загружено.]

предупреждение

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

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

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

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

[...усечено AGENTS.md: сохранено 14000+4000 из 25000 символов. Используйте файловые инструменты для чтения полного файла.]

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

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

Будьте кратки — укладывайтесь в настроенный context_file_max_chars; агент читает его на каждом шаге
Структурируйте с помощью заголовков — используйте разделы ## для архитектуры, соглашений, важных замечаний
Включайте конкретные примеры — показывайте предпочтительные шаблоны кода, формы API, соглашения об именовании
Указывайте, чего НЕ делать — «никогда не изменяйте файлы миграций напрямую»
Перечисляйте ключевые пути и порты — агент использует их для команд в терминале
Обновляйте по мере развития проекта — устаревший контекст хуже, чем его отсутствие

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

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

<!-- frontend/AGENTS.md -->
# Контекст фронтенда

- Используйте `pnpm`, а не `npm` для управления пакетами
- Компоненты находятся в `src/components/`, страницы — в `src/app/`
- Используйте Tailwind CSS, никогда не используйте инлайн-стили
- Запускайте тесты командой `pnpm test`

<!-- backend/AGENTS.md -->
# Контекст бэкенда

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

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

AGENTS.md​

Прогрессивный поиск в поддиректориях​

Пример AGENTS.md​

SOUL.md​

.cursorrules​

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

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

Во время сессии (прогрессивный поиск)​

Защита от инъекций в промпт​

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

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

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