ИИ-агенты читают документацию иначе, чем люди: у них ограниченный контекст, они не умеют «догадываться» по косвенным признакам и плохо справляются с HTML-страницами, которые нужно парсить. Именно под эти ограничения и выстраивается стандарт AI-Friendly — набор соглашений, которые делают проект понятным для машины так же, как README делает его понятным для человека.
Подход делится на три уровня. Первый — документация: самый критичный, потому что объясняет связи и способы использования. Второй — качество кода: принципы SOLID, DRY и KISS работают одинаково хорошо и для человека, и для агента; «плоский», предсказуемый код снижает вероятность ошибок при генерации. Третий — внешние сервисы, которые дополнительно упрощают работу с проектом через агента.
| Инструмент | Уровень | Для кого | Особенность |
|---|---|---|---|
| AGENTS.md | Документация | Все ИИ-агенты | Команды, стиль кода, паттерны в одном файле |
| Правила Cursor (.mdc) | Документация | Cursor IDE | Точечное применение к типам файлов через globs |
| llms.txt / llms-full.txt | Документация | Все ИИ-агенты | Текстовый индекс или полный дамп документации |
| Context7 | Внешний сервис | Cursor, Claude Code, VSCode, Windsurf | MCP-сервер с актуальной документацией в промпте |
| DeepWiki | Внешний сервис | Все пользователи | Автовики по GitHub-репозиторию, запуск без настройки |
Центральный элемент инфраструктуры — файл AGENTS.md. По структуре он напоминает README, но адресован агенту: содержит команды для развёртывания, стиль кода, разрешённые и запрещённые паттерны. Хороший пример — AGENTS.md фреймворка AIR, который позиционируется как «designed for AI to write»: там описаны маршрутизация, шаблонизация, работа с базами данных и общие паттерны — по сути, сжатая документация разработчика в одном файле.
Ключевой инструмент — файл AGENTS.md: сжатая документация для агента с командами, стилем кода и запрещёнными паттернами.
Для пользователей Cursor IDE существует более точечный инструмент — файлы правил в директории .cursor/rules/ с расширением .mdc. Они короче AGENTS.md и применяются к конкретным типам файлов через поле globs. Python-фреймворк FastStream для микросервисов на очередях (Kafka, RabbitMQ, NATS, Redis) уже поставляется с готовым файлом .cursor/rules/faststream.mdc — агент сразу знает, как правильно использовать этот проект.
На уровне навигации по документации работает стандарт llms.txt, разработанный Answer.AI. Это текстовый индекс со списком ссылок на разделы документации — агент сканирует его и решает, что читать дальше. Дополнение — llms-full.txt: весь текст документации в одном файле, который агент загружает один раз и держит в контексте, не обходя десятки страниц. Оба файла стоит размещать на сайте документации; пример реализации — проект django-modern-rest на ReadTheDocs.
Отдельная проблема — устаревание знаний модели. Если библиотека вышла недавно или API изменился, GPT-4o будет предлагать примеры из старой версии. Context7 решает это через MCP (Model Context Protocol): сервер берёт актуальную документацию и подкладывает её в промпт агента. Технически это Node.js-сервер, совместимый с Cursor, Claude Code, VSCode и Windsurf; устанавливается через npx. У сервиса есть собственная система оценки качества документации — разработчики могут отслеживать и улучшать показатели своего проекта.
Более простая альтернатива — DeepWiki от Cognition Labs (команда, создавшая агента Devin). Сервис запустили в апреле 2025 года: достаточно заменить github.com на deepwiki.com в URL репозитория, чтобы получить автоматически сгенерированную вики с диаграммами зависимостей, описанием стека и ИИ-чатом для вопросов по проекту. Функциональность уже, чем у Context7, зато не требует никакой настройки.
В совокупности эти инструменты закрывают разные слои: AGENTS.md и правила Cursor задают декларации для генерации кода, llms.txt ускоряет индексацию документации, а Context7 и DeepWiki дают пользователям и агентам поиск по документации на естественном языке. Переход на этот стандарт не требует переписывать проект — достаточно добавить несколько файлов и подключить сервисы.
