Встроенная документация в код против MD-файлов: что выбирают ИИ-агенты? Результаты эксперимента.

Мы провели эксперимент, чтобы выяснить, какой тип документации лучше подходит для ИИ-агентов: отдельные MD-файлы с оглавлением в agents.md или встроенная в код документация, применяемая в проекте GRACE.

Встроенные в код описания (Doxygen, JavaDoc) давно зарекомендовали себя в корпоративных проектах, а с появлением ИИ этот подход переживает новый взлёт: активно разрабатываются AI Friendly карточки контрактов и теговые описания, как в GRACE.

Для теста был собран небольшой учебный пример на VPS: бэкенд на Python (SQLite + OpenAPI) и React SPA с дополнительной функциональностью, показанной на скриншоте. Встроенная разметка не использовалась — вместо неё создавалась папка с MD-файлами, где агенты по сессиям формировали документацию в режиме Ad Hoc. Оглавление хранилось в agents.md.

Пока приложение было простым, отсутствие встроенной документации не имело значения, но и MD-файлы не помогали — агенты их просто игнорировали. Когда проект расширил сетевые функции, ситуация изменилась.

Диагностика требовала около 100 тысяч токенов на переконфигурирование, что указывало на нетривиальность операций. Даже сталкиваясь с проблемами, агенты без прямого указания отказывались заглядывать в MD-файлы с вероятностью около 50%. Подключенный MCP Context7 игнорировался полностью. При этом поиск через Tavily агенты использовали охотно — стандартная траектория включает паттерн «надо погуглить», но это не равно «пойду читать документацию».

Таким образом, MCP с типовой документацией (Context7) полностью игнорируется, а MD-файлы дают результат «то читают, то нет» — 50/50.

При дальнейшем усложнении сетевых функций начался коллапс: даже небольшое число MD-файлов путало агентов. Анализ показал, что традиция создавать MD-файл в конце сессии даёт лишь семантический снимок приложения в конкретный момент. Сессии имеют разные цели, и стабильное целевое выравнивание критично. Хуже того, ворох snapshot-отчётов Markdown уже описывал не существующее приложение, а историю его создания, порождая у агентов неверные гипотезы.

Эксперимент демонстрирует: документация в виде отчётов о сессиях непригодна для долгосрочной работы агентов и требует постоянной переработки. Агенты нестабильны в её чтении — вероятно, наблюдая такой бардак в процессе обучения с подкреплением (Reinforcement Learning), они предпочитают не читать документацию, если считают проблему простой (хотя это не всегда так).

Встроенная в код документация избавлена от этих недостатков: она всегда актуальна, меняется вместе с кодом и гарантированно считывается агентами, потому что у них просто нет выбора.