Ваш CLAUDE.md делает агента тупее. Исследование на 138 репозиториях это доказало

Полгода я собирал идеальный CLAUDE.md. Вычитывал каждую строку: «используй yarn, не npm», «тесты запускай так», «структура проекта вот такая». 200 строк выстраданного контекста.

Потом учёные из ETH Zurich прогнали 5694 pull request’а через четыре модели. Выяснилось, что мои 200 строк увеличивают расходы на 20% и снижают success rate (долю успешно решённых задач) на 3%.

Три процента в минус.

Собственно, исследование

В феврале 2026-го Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev и Martin Vechev опубликовали «Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?» (ETH Zurich и LogicStar.ai). Я нашёл её на arXiv, прочитал целиком, полез в данные.

138 реальных Python-репозиториев. 5694 PR. Четыре модели: Claude Sonnet 4.5, Codex GPT-5.2, GPT-5.1 Mini и Qwen3-30B (Qwen Code).

Два сценария. Первый — SWE-Bench Lite, 300 задач с LLM-сгенерированными контекстными файлами (те, что делает /init в Claude Code или аналоги в Codex). Второй — собственный AgentBench, 138 задач из нишевых репозиториев, которых модели точно не видели в обучающих данных. Там стояли человеческие AGENTS.md от реальных мейнтейнеров.

Результаты:

LLM-сгенерированные файлы (/init): success rate упал на 3% в среднем. Inference cost (стоимость вычислений при генерации ответа) вырос на 20%+. Платишь больше за худший результат.

Человеческие файлы: success rate вырос на 4%. Но inference cost тоже вырос — на 19%. Четыре процента улучшения за двадцать процентов переплаты.

И вот что совсем обидно: агенты с контекстными файлами не находили нужные файлы быстрее. Вообще. Те самые секции «Project Structure» и «Directory Overview» — агент их читал, тратил токены, а потом всё равно шёл grep’ать по репозиторию.

Подождите, но есть же другое исследование

Да. Lulla et al., январь 2026-го — «On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents». Результаты прямо противоположные: с AGENTS.md агент работает на 28.64% быстрее (медиана: 70.34 секунды вместо 98.57) и тратит на 16.58% меньше токенов (2440 вместо 2925).

Звучит убедительно. Но есть нюансы.

Тестировали только Codex. Один агент. 10 репозиториев. 124 PR. Задачи — до 100 строк кода, до 5 файлов. Из 89 репозиториев с AGENTS.md отфильтровали до 26, потом до 10. Выборка не то чтобы репрезентативная.

И — внимание — не мерили качество результата. «Manual sanity checks on 50 tasks» — дословная цитата. Авторы сами пишут: это «does not constitute a full correctness evaluation».

Агент с AGENTS.md быстрее. Но никто не проверил, что именно он сделал. Может, он быстрее потому, что пропустил половину работы. Может, увидел «используем pytest» и побежал, не разбираясь в деталях. Мы не знаем.

ETH Zurich мерили success rate. И он упал.

Хотя, возможно, для маленьких задач (до 100 строк) контекстный файл реально ускоряет, а на сложных — мешает. Было бы здорово проверить на одном датасете. Но пока — нет.

Почему «описание структуры» бесполезно

Самый контринтуитивный вывод: codebase overviews и directory listings не помогают агентам навигировать. Вообще.

Я потратил час на секцию «Архитектура проекта». Красиво расписал: вот тут модели, вот тут роуты, вот тут утилиты, а сюда не лезь. Перечитал, подправил.

Исследование говорит: агент это прочитал, потратил reasoning tokens (токены на внутренние рассуждения модели), а потом пошёл и нашёл всё через grep и glob. Потому что он и так это умеет. У него нет усталости, он не пропускает файлы.

Addy Osmani сформулировал фильтр в одну строку:

Can the agent discover this on its own by reading your code? If yes, delete it.

«Архитектура проекта» — агент узнает за 3 секунды. «Используемые технологии: Python 3.11, FastAPI, PostgreSQL» — видно в pyproject.toml. «Стиль кода: используем black и ruff» — конфиги в корне.

Всё это — шум.

Что GPT-5.1 Mini делал с контекстом

Деталь, от которой я сначала не поверил. GPT-5.1 Mini, получив контекстный файл, начинал его перечитывать. Не один раз — несколько. Тратил дополнительные шаги на повторное чтение уже загруженной информации. Reasoning tokens для GPT-моделей выросли на 14–22%.

Все четыре модели с контекстными файлами делали больше шагов: больше тестов, больше grep’ов, больше обходов файлов. Исследователи пишут деликатно: «agents followed instructions in context files, resulting in more thorough approach.» И дальше: «often unnecessary for resolving the specific task at hand.»

Модель читает «всегда запускай тесты после изменений» — и послушно запускает тесты на задаче, где тесты не нужны. Читает «проверяй зависимости» — и проверяет их там, где ты просто переименовываешь переменную. Когда в контекстном файле упоминались специфичные инструменты, их использование прыгало с 0.05 до 2.5 вызовов в среднем. Агент дёргал инструмент просто потому, что ему про него рассказали.

На HN разработчик avhception рассказал: его агент, начитавшись контекстного файла, решил заменить SQLite на MariaDB. В контексте было написано «для продакшена используем MariaDB». Агент интерпретировал это как инструкцию к действию. Несколько строк с прямым «не трогай базу данных» — не помогли.

Три файла, два формата, один бардак

Отступление, но бесит.

Сейчас у нас: CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, CLAUDE.local.md. Пять файлов для одной цели — сказать AI-агенту, как работать с проектом.

На GitHub висит issue (#34235) с просьбой, чтобы Claude Code читал AGENTS.md нативно. Люди ведут один файл — и копируют из него в три разных формата. Кто-то в комментариях назвал корень репозитория «markdown museum for confused bots». Точнее не скажешь.

И каждый из этих файлов жрёт контекстное окно при каждом запросе. Даже когда ты спрашиваешь «переименуй переменную» — агент сначала прочитает все инструкции, потому что они загружаются автоматически.

Так что, удалить?

Нет. Но радикально сократить.

Anthropic: «keep it short and human-readable.» Fowler: начинать постепенно, не фронтлоадить (не загружать всё заранее). Консенсус: меньше 300 строк, а лучше — меньше 60.

По данным исследования + Osmani + Fowler:

Оставить:

• Команду для запуска тестов (если нестандартная)
• Пакетный менеджер, если не очевидно (pnpm, не npm)
• Кастомные линтеры с неочевидными настройками
• Специфичные скрипты и инструменты
• Конвенции именования, если не выводятся из кода

Удалить:

• Описание структуры проекта
• Используемые языки и фреймворки
• Общие паттерны кодирования
• Архитектурные обзоры
• Всё, что генерирует /init

pamelafox на HN: «I only add information to AGENTS.md when the agent has failed at a task… then revert and rerun to test improvement.» Не описывать проект заранее, а фиксировать ошибки. CLAUDE.md как баг-трекер для AI, а не как README для человека.

Мой файл до и после

Перешёл от 200 строк к 47. Убрал «Архитектуру проекта» (40 строк), «Используемые технологии» (15 строк), «Стиль кода» — есть .editorconfig и ruff.toml, агент их и так читает. Убрал описание API-эндпоинтов — агент и так заглядывает в docs/.

Оставил три команды, одну строку про пакетный менеджер, пять строк про деплой-специфику и ссылку на .env.example.

Формально разницу не мерил. Может, делаю ту же ошибку, что Lulla — субъективно кажется лучше. Но 47 строк я реально готов поддерживать. 200 строк устаревали быстрее, чем я успевал обновлять.

Чего не мерили

Исследование ETH Zurich тоже не идеальное. Мерили success rate — решил задачу или нет. Бинарно. Не мерили качество кода, maintainability (удобство поддержки), следует ли агент конвенциям проекта.

rmunn на HN это подметил: стилистическая консистентность, правильные абстракции, следование паттернам — невозможно измерить бинарно.

Может оказаться, что агент без CLAUDE.md решает задачу чаще (не отвлекается), но в стиле, который не вписывается в проект. А с CLAUDE.md — решает реже, но результат лучше интегрируется. Этого пока никто не проверил.

vidarh: «Without measuring quality of output, this seems irrelevant to me. Performance is not a consideration.» Жёстко, но логика есть. Если нужно 5 попыток вместо 3, но каждая попытка чище — success rate на первой попытке не так важен.

Хотя, может, я просто оправдываю свои 47 строк.

Один файл, чтобы править всеми

Зацепило не сами числа. А скорость, с которой мы превратили простую идею в индустрию.

Год назад CLAUDE.md не существовал. Потом Anthropic добавил поддержку. Появились гайды, шаблоны, генераторы шаблонов, исследования о том, что шаблоны не работают, гайды о том, как интерпретировать исследования.

Мы написали больше markdown’а про то, как разговаривать с AI, чем кода с его помощью.

sensanaty на HN напомнил: «thinking blocks are illusions — just tokens in sequence, not privileged reasoning layers.» Thinking blocks (блоки рассуждений модели, которые она выводит перед ответом) — не особый слой мышления, а просто токены в последовательности. Мы антропоморфизируем модели. Пишем им инструкции как стажёру. А они — статистические машины, предсказывающие следующий токен. 200 строк контекста — это 200 строк токенов, которые сдвигают распределение вероятностей. Иногда в лучшую сторону. Иногда нет.

Fowler предупреждает: несмотря на слово «engineering» в «context engineering» (управление контекстом, подаваемым модели), исполнение остаётся вероятностным. Нельзя сказать «ensure it does X». Можно — «make it more likely to do X». И чем больше инструкций, тем выше вероятность конфликта между ними.

UPD: перечитал и понял, что сам грешу тем же. Мой CLAUDE.md на 47 строк я не тестировал. Не прогонял с ним и без него одни и те же задачи. Просто «чувствую, что лучше». Может, pamelafox права, и единственный честный подход — A/B тест на каждую строку. Но кто из нас это реально делает?