Anthropic وETH Zurich: ملف CLAUDE.md الطويل يضعف أداء الوكيل ويرفع التكاليف

CLAUDE.md и AGENTS.md задумывались как быстрый способ объяснить агенту правила проекта, но новое исследование показывает: длинный контекст чаще вредит, чем помогает. На выборке из 138 Python-репозиториев исследователи ETH Zurich увидели падение success rate и рост расходов, особенно у автоматически сгенерированных файлов.

Что показало исследование

Авторы работы Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? взяли 138 реальных репозиториев, собрали 5694 pull request и прогнали задачи через четыре модели: Claude Sonnet 4.

5, Codex GPT-5.2, GPT-5.1 Mini и Qwen3-30B.

Они сравнили сценарии без специальных файлов, с LLM-сгенерированными инструкциями и с AGENTS.md, которые поддерживали люди. Это важный момент: исследование смотрело не на абстрактные демо, а на реальные задачи из живых кодовых баз.

Главный вывод для автоматически созданных файлов получился неприятным. Success rate в среднем снизился на 3%, а inference cost вырос более чем на 20%. Человеческие файлы показали себя лучше: они подняли успех примерно на 4%, но цена тоже выросла почти на 19%.

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

Почему длинный файл мешает

Самое контринтуитивное наблюдение из статьи: описания структуры проекта почти не помогают агенту ориентироваться. Разделы про папки, архитектуру и стек выглядят полезно для человека, но агент часто и так находит всё через grep, glob и чтение файлов. Если информация уже лежит в pyproject.toml, package.json, конфиге линтера или в самой структуре репозитория, длинное объяснение лишь дублирует то, что модель способна быстро обнаружить сама.

Если агент может узнать это из кода сам, лучше удалить это из инструкции.

Исследователи также заметили, что модели с контекстными файлами делают больше действий, чем нужно для конкретной задачи. Они чаще перечитывают инструкции, лишний раз гоняют тесты и активнее вызывают инструменты, которые были упомянуты в файле. В статье отдельно отмечен рост reasoning tokens у GPT-моделей. Иначе говоря, инструкция не просто добавляет знания, а меняет поведение агента: он начинает следовать правилам даже там, где они не помогают решить текущую задачу.

Что стоит оставить Полный отказ от CLAUDE.md или AGENTS.md из исследования не следует.

Скорее вывод в другом: такие файлы должны быть короткими и содержать только то, что агент не сможет надёжно вывести сам из кода или конфигов. Чем меньше декоративного текста, тем ниже риск, что модель зациклится на лишних ритуалах вместо выполнения конкретного запроса.

• Нестандартную команду запуска тестов Пакетный менеджер, если он неочевиден Кастомные скрипты, тулзы и деплой-особенности Правила именования, если их нельзя быстро вывести из кода Ссылку на .env.example или другой критичный файл входа На картину накладывается и другое исследование, где Codex с AGENTS.md показывал ускорение и меньший расход токенов. Но там выборка была намного меньше, а корректность результата оценивалась ограниченно. Поэтому общий вывод пока осторожный: короткий и прикладной контекст иногда помогает, а длинный файл с обзором архитектуры, стека и общих правил легко превращается в дорогой балласт. ETH Zurich также почти не затрагивает поддерживаемость кода и соответствие стилю проекта, так что спор о пользе таких файлов ещё не закрыт.

Что это значит

Практический вывод простой: относиться к CLAUDE.md как к списку исправленных ошибок агента, а не как к энциклопедии проекта. Если инструкция не помогает избежать конкретного сбоя, не описывает нестандартную команду и не добавляет уникального контекста, её лучше убрать. Для команд, которые активно используют coding-агентов, это прямой повод сократить файлы контекста, снизить расход токенов и проверить на своих задачах, какие строки реально улучшают результат, а какие только создают дорогой шум.