Разбираем, как правильно составлять файлы AGENTS.md и CLAUDE.md. Почему перегрузка контекста вредит производительности агентов и как условные блоки помогают управлять их поведением.
2 мин
В современной разработке с использованием искусственного интеллекта стандартом становятся файлы инструкций — AGENTS.md или CLAUDE.md. Это документы, которые предварительно загружаются в контекст модели до начала диалога. Они дополняют базовый системный промпт (system prompt) от разработчиков модели вашими личными правилами. Однако подход к их составлению претерпел изменения.
Изначально разработчики предполагали, что в такие файлы нужно помещать максимум информации: описание используемого технологического стека, список ключевых файлов, архитектурные особенности проекта. Идея заключалась в создании своеобразной мини-карты для агента, чтобы он быстрее ориентировался в кодовой базе.
Недавние исследования показали ошибочность этого подхода. Перегрузка стартового файла инструкций техническими деталями снижает производительность агента и увеличивает затраты на токены примерно на 20 процентов. Современные агенты способны самостоятельно и очень быстро проанализировать стек технологий, найти нужные файлы и понять архитектуру приложения.
Изображение из источника
Вместо подробной документации файл AGENTS.md должен оставаться максимально лаконичным. Его главная задача — задавать ваши личные предпочтения и корректировать поведение модели. Например, можно указать агенту всегда тестировать код в браузере перед отправкой ссылки, использовать конкретный инструмент для веб-поиска или сохранять файлы планирования в строго определенную директорию.
Эффективным методом управления контекстом стало использование условных блоков. Оборачивая инструкции в теги, похожие на XML (например, <important if="simple web page">), вы помогаете агенту применять правила только тогда, когда они действительно нужны. Это избавляет от ситуаций, когда ИИ начинает писать избыточные спецификации для простейшего лендинга.
Еще одна важная практика — иерархическое распределение файлов инструкций. AGENTS.md загружаются динамически по мере навигации агента по папкам. В корне проекта может лежать базовый набор правил, а в папке с документацией — специфический файл, который активируется только при работе с текстами.
По мере развития платформ для программирования с ИИ, фокус смещается с ручного управления контекстом на настройку высокоуровневого поведения. Чем автономнее становятся системы, тем важнее давать им правильные поведенческие ориентиры, а не пытаться выполнить за них работу по анализу кода.
Файлы инструкций для ИИ-агентов должны содержать поведенческие правила и предпочтения пользователя, а не техническую документацию проекта.
Избыточная помощь со стороны разработчика в виде подробных карт проекта только сбивает ИИ с толку. Чем умнее агент, тем меньше вводных данных о структуре кода ему требуется.
