AI coding agents: исследование о «грязных» конфиг-файлах Agents.md и Claude.md

Первый предложенный каталог «configuration smells» показывает распространённые проблемы — context bloat, skill leakage и conflicting instructions — из-за которых coding agents становятся менее надёжными и более дорогими.

AI coding agents становятся критически важными для разработки ПО, но конфигурационные файлы, которые ими управляют, такие как Agents.md или Claude.md, могут быть «грязными».

Это означает, что в них встречаются структурные дефекты, избыточность или контрпродуктивные рабочие процессы, которые раздувают контекст, тратят токены и делают coding agents менее надёжными.

Исследователи из факультета компьютерных наук Федерального университета Минас-Жерайс в Бразилии надеются пролить свет на эту проблему, представив то, что они называют «первым каталогом запахов» для конфигурационных файлов coding agents. Самые заметные проблемы — lint leakage, skill leakage, context bloat и conflicting instructions.

«Наши результаты показывают, что эти запахи широко распространены на практике», — написали исследователи. Следовательно, они «могут напрямую влиять на то, как coding agents интерпретируют соглашения проекта, расставляют приоритеты в инструкциях и выполняют задачи разработки».

Грязные конфиги в harness заставляют модели вести себя неправильно

Такие агенты, как Claude Code, Codex, Cursor и Gemini, всё чаще берут на себя задачи программной инженерии: генерацию кода и его ревью, создание тестов, исправление ошибок, миграцию ПО и написание документации.

По сути, это сочетание large language model (LLM) и harness; модель выступает «мозгом», а harness обеспечивает цикл, который выполняет действия и позволяет агентам вызывать нужные инструменты для выполнения задачи. Это могут быть поисковые системы, системы трекинга задач и тестовые раннеры.

Поведение агентов задают конфигурационные файлы вроде Agents.md и Claude.md, которые содержат инструкции по рабочим процессам проекта, требованиям к тестированию и знаниям о предметной области. Это помогает поддерживать единообразие между разными задачами и сессиями. Обычно такие файлы загружаются в начале сессии как часть prompt и остаются в контексте на протяжении всей задачи.

Но исследователи обнаружили, что эти конфигурации буквально пронизаны smells: по крайней мере один smell был найден в 91 из 100 популярных open source-репозиториев, где есть файлы Agent.md или Claude.md.

Шесть самых сильных «запахов»:

• Lint leakage (встречается в 62% файлов)
• Context bloat (42%)
• Skill leakage (35%)
• Conflicting instructions (28%)
• Init fossilization (24%)
• Blind reference (16%)

Запах перерасхода

Lint leakage возникает, когда инструкции в конфиг-файлах излишне включают правила, которые уже контролируются инструментами анализа, такими как code formatters или linters; они отсекают баги, уязвимости, несоответствия и программные ошибки, например за счёт повторения общих рекомендаций стиля, правил форматирования, ограничений по длине строки, соглашений об именовании или порядка импортов.

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

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

При skill leakage редко используемые или специфичные для задачи инструкции без необходимости включаются в конфигурацию вместо того, чтобы храниться в отдельных специализированных skill- или task-файлах. Эти узкоспециализированные знания затягиваются в каждую сессию, даже когда модели они не нужны для выполнения задачи. В результате контекстное окно становится больше, дороже и сложнее в сопровождении, отмечают исследователи.

«Кроме того, такие правила могут конкурировать за внимание с правилами, которые действительно критичны для проекта», — пишут они.

Как и следует из названия, conflicting instructions означает, что правила в файле противоречат друг другу, создавая неоднозначность; модель по сути «путается» и должна выбирать произвольно. Это может приводить к непоследовательности и нестабильным результатам.

Init fossilization возникает, когда файлы создаются один раз, но затем больше не пересматриваются и не редактируются, из-за чего в них остаются устаревшие или неактуальные правила, не отражающие изменения в codebase. «В результате конфигурация склонна накапливать шум, увеличивать потребление контекста и со временем снижать общую эффективность агента», — поясняют исследователи.

Наконец, blind references указывают на файлы или документацию без объяснения их назначения. В итоге agent может просто проигнорировать их, что создаёт проблемы, если они критичны для задачи, либо загрузить лишние материалы для сбора контекста, тратя токены и место, либо не расставить приоритеты для важной информации.

Кроме того, исследователи обнаружили, что smells часто встречаются в одном и том же файле и провоцируют появление друг друга; например, skill leakage и conflicting instructions могут увеличить вероятность context bloat на 83%, потому что они добавляют лишнюю или нерелевантную информацию.

Как проветрить запахи

Хотя эти smells «широко распространены на практике», существуют способы их устранить.

Например, чтобы уменьшить lint leakage, из prompt следует убрать стилистические ограничения, такие как форматирование и порядок импортов. Пусть этим занимаются программные инструменты; тратить бюджет на правила стиля — пустая трата, отмечают исследователи.

Чтобы снизить context bloat, файлы Claude.md и Agents.md должны оставаться краткими и содержать guidance, специфичный для проекта. Например, Anthropic рекомендует держать Claude.md короче 200 строк.

Чтобы ограничить skill leakage, разработчики должны давать в конфиг-файлах конкретные инструкции о сборке проекта, запуске тестов, соглашениях по коду и другом важном контексте. Инструкции, относящиеся к отдельным задачам, следует хранить в отдельных markdown-файлах с понятными названиями, советуют исследователи.

Кроме того, чтобы избежать conflicting instructions, создателям следует периодически пересматривать конфиг-файлы и удалять противоречивые или устаревшие инструкции. Аналогично, борьба с init fossilization требует постоянного обновления файлов, поясняют исследователи. Это особенно важно, если агент дважды подряд делает одну и ту же ошибку, code review выявляет деталь, которую агент уже должен был знать, или разработчикам приходится повторно вносить исправления и уточнения, которые уже обсуждались в предыдущей сессии.

Наконец, чтобы минимизировать blind references, разработчики должны объяснять агентам, когда и зачем читать файлы, и добавлять ссылки с кратким пояснением роли документа, содержащейся в нём информации и сценариев, когда его следует использовать. Например, текст может ссылаться на внешнюю зависимость, включать ссылку на её GitHub repository и кратко объяснять её назначение. «Тогда agent может понять роль зависимости, не загружая и не проверяя внешний repository напрямую», — поясняют исследователи.

В итоге они пришли к выводу, что конфигурационные файлы — это «ключевые артефакты» в agentic software development, и когда они становятся «грязными», это проблема. Поэтому «их качество заслуживает усилий и внимания».

Материал — перевод статьи с английского.

Оригинал: AI coding agents may be getting bad instructions from ‘smelly’ config files