Короче, новая рубрика "Клод сказал".

Вопрос:

Есть хоть какие-то исследования, которые подтверждают, что встроенная в код документация - это топ для агентской разработки?

Ответ:

Коротко: прямого подтверждения «это топ» нет — есть смешанная картина, причём с важными нюансами. Что реально есть в литературе:

За. Исследование MITRE: рост числа комментариев улучшает понимание кода LLM (проверяли через quiz-точность), причём мелкие неточности в комментариях почти не вредят, а грубые — существенно деградируют понимание. Эмпирическое исследование по автоматическому багфиксу прямо рекомендует не удалять комментарии из данных и тщательно документировать код, чтобы лучше использовать LLM для исправления багов. [arxiv](https://arxiv.org/pdf/2601.23059) По тестам: Javadoc-комментарии сами по себе давали сопоставимую или лучшую точность генерации тестовых оракулов, чем реализация метода, а подход только на Javadoc находил на 19–94% больше реальных багов в Defects4J. [arxiv](https://arxiv.org/pdf/2412.09360)

Против. Обзор контрпримеров: в одном исследовании включение комментариев не дало статистически значимого эффекта; в бенчмарке RepoQA удаление комментариев у большинства моделей *улучшало* результаты; ещё одна работа показала, что исключение комментариев повышало точность суммаризации кода. [arxiv](https://arxiv.org/pdf/2512.16790)

Про агентские контекст-файлы (AGENTS.md/CLAUDE.md) — самое релевантное для тебя. ETH Zurich (AGENTbench, февраль 2026): LLM-сгенерированные контекст-файлы улучшали результат лишь на 2,7% и только когда из репозитория удаляли остальную документацию — они в основном пересказывают README; а доминирующий паттерн «всеобъемлющий, сгенерированный LLM, тяжёлый по архитектуре» добавляет стоимость и снижает корректность. Помогали именно написанные разработчиком файлы с узко скоуплеными требованиями. [Notchrisgroves](https://notchrisgroves.com/when-agents-md-backfires/) Другая работа: наличие корневого AGENTS.md ассоциировано с меньшим расходом токенов и более быстрым завершением задач, но корректность и соответствие интенту там не измеряли.

Честный вывод: подтверждается более слабый тезис — *точная* документация рядом с кодом помогает, *неточная* активно вредит (хуже, чем её отсутствие), а избыточная дублирующая — жрёт контекст без пользы. Это скорее аргумент за твою ATDD-логику: исполняемая спецификация (тесты) не устаревает, в отличие от комментариев.