Эффективность вайбкодинга: статистика чтения документации ИИ-агентом в реальных условиях
Анализ логов проекта за пять недель показывает, что ИИ-агенты в режиме «вайбкодинга» практически игнорируют документацию, если она не указана явно в точках входа. Исследование, проведенное разработчиком на основе журналов Claude Code, выявляет, что файлы без прямой ссылки открываются агентам в среднем менее двух раз, в то время как документация, назначенная в начальных инструкциях, становится основным контекстом для решения задач.
# Эффективность вайбкодинга: статистика чтения документации ИИ-агентом в реальных условиях
В эпоху, когда искусственный интеллект берет на себя значительную часть написания кода, возникает закономерный вопрос: как именно агенты воспринимают и используют техническую документацию? Традиционная модель разработки предполагает, что разработчик изучает мануалы, когда они ему требуются. Однако при использовании ИИ-агентов этот процесс трансформируется: агент получает контекст в начале сессии и работает с ним, редко иницируя самостоятельный поиск информации.
Недавние эксперименты и статистические данные, полученные из реальных логов работы Claude Code, демонстрируют поразительную экономию внимания алгоритмов. Оказывается, что «бесхозная» документация, лежащая в репозитории без явных указаний, игнорируется системой с высокой точностью. В этом материале мы разберем основные выводы анализа, методику подсчета и практические рекомендации для оптимизации процессов автоматизированной разработки.
Методология анализа: пять недель логов
Данные для исследования были собраны за период в пять недель. За это время в проекте было совершено 584 запуска субагентов и проведено 112 сессий разработки. Разработчик провел детальный анализ файловых журналов (jsonl), хранящихся локально в директории проекта. Скрипт, использованный для обработки данных, учитывал вызовы инструментов чтения файлов, включая прямые вызовы Read и команды оболочки cat, head, tail, sed, выполняемые через Bash.
Важно отметить, что подсчет велся с учетом путей к файлам относительно корня репозитория, что позволило корректно агрегировать статистику для файлов с одинаковыми именами в разных папках. Общее количество markdown-файлов в проекте составило 162, а их суммарное открытие агентом за рассматриваемый период достигло 898 раз. Для классификации документов была выделена «точка входа» — это файлы команд (в .claude/commands) и описания субагентов (в .claude/agents), которые служат стартовым контекстом для запуска агентом конкретной задачи.
Ключевые метрики открытий
Результаты анализа показали четкую иерархию использования документации:
1. Документация, назначенная в точке входа: таких файлов было 53. Агент открывал их в среднем 12,3 раза на сессию. Это самые активные документы, которые служат руководством к действию. 2. Сами файлы команд и субагентов: всего 15 файлов, но их среднее количество открытий составило 7,2 раза. 3. Файлы в оглавлении CLAUDE.md: их было всего 5, и среднее число открытий составляло 3,0. 4. Файлы без входящей ссылки: группа из 88 файлов, на которые никто не ссылается в точках входа. Их среднее количество открытий — всего 1,2 раза.
Ситуация с «безссылочными» документами становится еще более показательной при детальном рассмотрении: 57 из 88 таких файлов не были открыты агентом ни разу за весь пятинедельный период. Агент просто не «видит» их как релевантные источники информации, если они не вызваны явным указанием в контексте запуска.
Почему агенты не читают «на всякий случай»
Поведение ИИ-агентов в этом аспекте кардинально отличается от человеческого. Человек склонен просматривать документацию, когда возникает ошибка или необходимость глубже понять архитектуру. Агент же начинает каждую работу с «чистого листа» контекста, зная лишь то, что было загружено в начало сессии.
Если документация не подгружена автоматически (например, через файл CLAUDE.md, который загружается целиком, но имеет ограничения по объему) и не упомянута в явных точках входа, агент не предпринимает попыток ее поиска. Он следует инструкциям. Инструкция, содержащая путь к файлу, работает как триггер для контекстной загрузки. Без этого триггера файл остается статичным артефактом в системе контроля версий.
Есть и исключения из общего правила. Среди файлов, не упомянутых в точках входа, нашлись три документа, которые агент открывал довольно часто — 15, 11 и 11 раз соответственно. Анализ показывает, что эти файлы имели в названии прямые указания на конкретную задачу. Вероятнее всего, агент находил их по имени файла в ходе выполнения инструкций, но в логах это отражалось как прямое обращение к файлу, а не как поиск по контексту документации.
Влияние на эффективность и стоимость
Использование ИИ для документирования само по себе — отдельная тема. Исследования, включая данные из ETH Zürich, показывают противоречивые результаты относительно использования файлов типа AGENTS.md. Где-то использование таких файлов снижает время решения задачи на почти 29%, в других случаях рост стоимости вычислений перевешивает пользу, а скорость работы не меняется существенно.
Общее схождение мнений заключается в том, что агенты эффективно исполняют четкие инструкции, но обзор репозитория или «общее понимание» проекта не ускоряет их работу. Попытка заставить модель описать репозиторий часто приводит к тому, что она генерирует поверхностный отчет, который в реальности не использовался для решения задач.
Рекомендации по организации контекста
Основываясь на полученных данных, разработчики могут оптимизировать свои рабочие процессы:
* Короткий `CLAUDE.md`: Этот файл должен содержать только критически важную информацию без которой агент ошибется. Рекомендуется держать его в пределах 200 строк, чтобы не перегружать контекст на каждой сессии. * Явные ссылки в точках входа: Для специфической документации используйте файлы команд и описания субагентов. Указание пути в тексте («прочитай docs/visuals.md») гарантирует, что файл будет прочитан в необходимом контексте. * Мониторинг логов: Не удаляйте документацию сразу, если она не использовалась. Рекомендуется ежемесячно прогонять скрипт анализа (логирование обычно хранится 30 дней по умолчанию), чтобы выявить файлы, которые агент игнорирует. Если файл открывался много раз только из-за имени, его правильнее закрепить за конкретной командой. * Внешние библиотеки: Документацию сторонних инструментов подавайте в момент вызова функции или инструмента. Некоторые платформы (например, Context7) уже поддерживают отправление такого контекста модели в формате llms.txt.
Как отмечает автор исследования, корреляция между наличием ссылок и открытием файлов очевидна. Те файлы, которые называются в точках входа, действительно необходимы для текущей задачи. Это подтверждает гипотезу о том, что вайбкодинг строится не на широком исследовании кода, а на точном управлении контекстом.
ИИ-агент в режиме автоматизированной разработки — это не исследователь, а исполнитель. Он берет на себя объем рутинной работы, но ему нужны четкие ориентиры. Передача документации в «руки» агента без указания направления движения — аналогична тому, если дать человеку карту страны, но не сказать, в какой город его отправить. Он просто не начнет путь, пока не получит команду.
Таким образом, эффективное использование ИИ в разработке требует смещения фокуса с написания обширной документации «на будущее» на создание точных ссылок и инструкций в начале каждого цикла работы. Это снижает затраты на вычисления и повышает предсказуемость результата автоматизированных сессий.