Полгода я собирал идеальный 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», которые я заботливо описывал - агент их читал, тратил на это токены, а потом всё равно шёл грепать по репозиторию.

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

Да, есть. 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).

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

Lulla тестировали только 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. И он упал.

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

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

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

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

Исследование говорит: агент это прочитал, потратил 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». Агент интерпретировал это как инструкцию к действию. Несколько строк в AGENTS.md, явно говорящих «не трогай базу данных» - не помогли.

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

Тут надо отступление. Не совсем по теме, но бесит.

У нас сейчас: 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.» Мы антропоморфизируем модели. Пишем им инструкции как стажёру. А они - статистические машины, предсказывающие следующий токен. Наши 200 строк контекста - это 200 строк токенов, которые сдвигают распределение вероятностей. Иногда в лучшую сторону. Иногда нет.

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

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