Николай Чикишев world 19 июня 2026, 15:08

Как писать инструкции для ИИ-агентов без «запашка» и не тратить токены

Плохо написанные инструкции для ИИ-агентов могут увеличивать расходы на токены и ухудшать качество их работы. К такому выводу пришли бразильские исследователи.

Оставить комментарий

Как писать инструкции для ИИ-агентов без «запашка» и не тратить токены

Плохо написанные инструкции для ИИ-агентов могут увеличивать расходы на токены и ухудшать качество их работы. К такому выводу пришли бразильские исследователи.

Речь идет о конфигурационных файлах, которые задают поведение ИИ-агентов при работе с кодом. Для Claude такие файлы часто называются CLAUDE.md, а для других агентов — AGENTS.md. В них разработчики описывают правила работы с проектом, требования к стилю, инструменты, ограничения и другие инструкции.

Авторы исследования сравнивают такие проблемы с code smells — признаками плохой структуры кода. По аналогии они называют типичные ошибки в инструкциях для агентов configuration smells — конфигурации «с запашком».

Исследователи изучили около 532 тысяч файлов и собрали датасет из 100 популярных open-source проектов, где использовались AGENTS.md или CLAUDE.md. В 91 из 100 проверенных файлов они нашли хотя бы одну типичную проблему.

Самой распространенной ошибкой стала Lint Leakage. Она встречалась в 62% файлов. Так исследователи называют ситуацию, когда инструкции для ИИ-агента повторяют правила, которые уже проверяются линтерами, форматтерами или инструментами статического анализа. В результате модель тратит токены на правила, которые лучше и надежнее выполняются обычными программными инструментами.

Новый фреймворк снижает расходы на работу ИИ-агентов на 50%

Вторая распространенная проблема — Context Bloat. Она встречалась в 42% файлов. Это чрезмерно длинные и перегруженные инструкции, где разработчики слишком подробно описывают поведение агента. Такие файлы увеличивают расход токенов, повышают стоимость работы агента и могут скрывать действительно важные указания.

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

Еще одна проблема — Skill Leakage. Она встречалась в 35% файлов. Так исследователи называют случаи, когда в основной AGENTS.md добавляют инструкции для редких инструментов или специфических практик, хотя они нужны только в отдельных ситуациях. Из-за этого агент загружает лишний контекст в каждой сессии, даже когда он не нужен.

Исследователи также выделили другие типичные ошибки. Blind References — ссылки на внешние документы без объяснения, когда и зачем их использовать. Init Fossilization — устаревшие инструкции, оставшиеся после инициализации проекта. Conflicting Instructions — противоречивые указания, которые могут сбивать агента с толку.

Главный вывод исследования: в инструкциях принцип «меньше значит лучше» часто работает эффективно. Разработчикам советуют не превращать AGENTS.md и CLAUDE.md в длинные справочники, а оставлять там только минимально необходимые правила.