> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Правила ведения инструкций для агентов

> Критерии размещения устойчивых ограничений проекта в файлах AGENTS.md, документации, проверках и комментариях к коду.

# Правила ведения инструкций для агентов

Файлы `AGENTS.md` должны помогать агенту быстро увидеть устойчивые ограничения той части репозитория, которую он изменяет. Они не заменяют техническую документацию, автоматические проверки и комментарии, объясняющие локальные решения.

## Уровни инструкций

Корневой `AGENTS.md` содержит только правила, которые относятся сразу к нескольким частям системы или предотвращают особенно опасную и труднообратимую ошибку. К таким правилам относятся границы владения данными между Nerve и Велесом, хранение секретов, сетевые и файловые границы, а также меры защиты базы векторной памяти.

Файл `nerve/AGENTS.md` содержит устойчивые правила интерфейса и клиентского промежуточного слоя. Файл `veles/AGENTS.md` содержит устойчивые правила шлюза, среды выполнения, памяти и встроенных навыков. Более узкое правило следует размещать ещё ближе к соответствующему модулю только тогда, когда оно действительно нужно при большинстве изменений в этом модуле.

## Что не следует добавлять

В инструкции не следует переносить:

* историю отдельной неисправности;
* точный текст исключения или прежнего сообщения об ошибке;
* название вспомогательной функции, если требование уже выражено проверяемым поведением;
* подробный алгоритм одной возможности;
* временные значения задержек и попыток, которые уже заданы в коде;
* последовательность событий одной гонки состояний;
* сведения об исследовании сторонней документации.

Такое поведение закрепляется автоматической проверкой. Причина необычного локального решения описывается рядом с кодом. Большая архитектурная схема или протокол размещаются в документации для разработчиков либо в скрытом разделе исследований и планов.

## Критерии нового правила

Новое правило стоит добавлять, только если одновременно выполняются следующие условия:

1. Оно с высокой вероятностью понадобится при будущих изменениях в области действия файла.
2. Его нельзя быстро и однозначно вывести из типов, схемы, соседнего кода или существующей проверки.
3. Его нарушение приводит к потере данных, утечке секрета, несовместимости между компонентами или повторению дорогой архитектурной ошибки.
4. Формулировка описывает устойчивый результат, а не текущий способ реализации.

Если правило перестало соответствовать этим критериям, его следует удалить, перенести ближе к затрагиваемому модулю или заменить ссылкой на техническую документацию.