Современные технологии искусственного интеллекта стремительно меняют подходы к разработке программного обеспечения. В таких условиях качественная и адаптированная документация становится ключевым ресурсом как для профессионалов, так и для новичков. Компания Freestyle, облачный сервис для управления кодом, написанным AI-агентами, подошла к задаче обновления своей документации с особым вниманием к потребностям AI-разработчиков. Рассмотрим подробно, как и почему был реализован этот масштабный ребрендинг и какие инновационные решения помогли повысить качество взаимодействия между пользователями, AI и документацией. Freestyle — это платформа, позволяющая запускать и управлять кодом, написанным искусственным интеллектом, с особенными инструментами для решения новых проблем, связанных с небезопасным и непроверенным кодом.
Такой уникальный подход требует особого внимания к тому, как пользователи получают знания и помощь по продукту. В ходе проведения регулярных встреч и хакатонов с клиентами команда заметила важный сдвиг. Пользователи перестали активно читать традиционные мануалы и перешли к использованию AI для запросов по документации. Однако AI часто давал ошибочные ответы, включая устаревшую информацию, упоминания о конкурентах и фигуры, не существующие в текущем API. Эти вызовы стали сигналом к необходимости кардинального обновления документов.
Первым значительным шагом к адаптации документов под AI стало создание специальных файлов llms.txt и llms-full.txt, которые можно использовать AI-моделями для получения структурированной информации. Однако изначально допущенные ошибки, такие как использование относительных URL, снижали эффективность их применения. Модели не могли нормально получить доступ к нужным данным, и многие инструменты для извлечения данных из документации не справлялись с такими ссылками.
После исправлений была решена и проблема с отображением информации. Документация изначально содержала комплексные веб-страницы с вкладками и элементами на JavaScript, что приводило к тому, что AI-читалки получали лишь частичную информацию, например, только для JavaScript, и не видели сопутствующие описания для Python или других языков. Решением стала повторная экспортировка всех страниц с расширением .md, позволяющая получить чистый Markdown-контент. Именно этот формат позволяет AI моделям легко и полноценно анализировать текст без лишнего HTML и стилей.
Такой подход облегчил парсинг и дал возможность пользователям и AI получать содержательные и релевантные данные. Для повышения удобства использования создали так называемые AI Buttons — специальные кнопки копирования, расположенные в верхней части страниц документации. Эта идея была вдохновлена распознаваемым интерфейсом Mintlify. Копирование осуществляется в удобном виде, чтобы добавлять данные напрямую в контекст диалогов с AI, таких как ChatGPT или Claude. Упрощение интеграции с AI-инструментами позволило пользователям напрямую отправлять ключевые фрагменты документации в чат и получать мгновенный ответ.
Однако интеграция с AI потребовала и тонкой настройки. Прямое копирование всего контента страниц в ссылках приводило к ошибкам из-за ограничений длины URL. Компания Freestyle оптимизировала процесс, внедрив специальные инструкции для AI-компаньонов — например, у ChatGPT теперь есть ссылка на поиск по содержанию Markdown-документов, а Claude получил возможность напрямую загружать .md файлы с документами. Т3 Chat, напротив, был ограничен, и для него пришлось встроить полные тексты в URL — менее эффективное решение, но единственно возможное.
Особое внимание было уделено взаимодействию AI-агентов с документацией через MCP (Modular Cognitive Platform). Созданы инструменты listDocs и getDocById, которые позволяют AI запрашивать список всех документов и получать конкретные страницы по идентификаторам. Отметив, что изначальные дескрипции функций были слишком общими и не мотивировали AI их использовать, была проделана работа по напиcанию более целевых и актуальных описаний. Теперь AI получает инструкции об обязательном использовании инструментов документации при любых затруднениях в работе с Freestyle. Результат этого изменения оказался впечатляющим: AI стал активнее обращаться к документации, что существенно повысило качество помощи и диагностики ошибок у конечных пользователей.
Для тех, кто предпочитает работать в наиболее комфортных средах, в интерфейс добавили ссылки для быстрой установки MCP в платформы Cursor и VSCode. Этот момент позволил разработчикам и AI-агентам беспрепятственно интегрироваться с документацией, не покидая привычные среды разработки и общения. Отдельно стоит отметить внедрение AI-чата непосредственно в сайт документации. Вопреки сложным интеграциям с дорогими провайдерами, Freestyle быстро разработала собственное приложение на базе Gemini-2.5-Flash и интегрировала его с MCP.
Теперь AI-чат при ответах автоматически обращается к актуальным документам, указывая пользователю ссылки на релевантные разделы. Такой подход не только облегчает поиск информации, но и повышает прозрачность и доверие пользователей к полученным рекомендациям. Freestyle активно развивается и не останавливается на достигнутом. В планах — создание MCP для DevOps, который позволит AI-агентам анализировать логи проектов пользователей, что особенно важно при возникновении ошибок деплоя. Запуск новых инструментов, например askQuestion, даст возможность AI более точно понимать контекст запросов, прослеживать взаимосвязь между языками программирования, технологиями и задачами разработчиков.
Также надвигается escalatIssue — функциональность, позволяющая AI автоматически сообщать о проблемах разработчикам Freestyle, ускоряя процесс реакции и улучшая качество сервиса. В улучшения входит и дальнейшая кастомизация интерфейса AI-чата, где он сможет рекомендовать пользователю присоединятся к дискорду, заходить на дашборд или выполнять иные полезные действия, облегчающие работу с платформой. Работа над созданием подробных гайдлайнов и примеров использования также занимает важную позицию. Практический, пошаговый подход помогает и AI, и самим пользователям лучше понимать возможности платформы и интеграции различных инструментов. Не обходится и без попыток автоматической генерации SDK документации, однако на данный момент успехи в этой области ограничены и требуют значительных ресурсов и времени.
