Skip to main content

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

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

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

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

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

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

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

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