AI-friendly и AI-first: как адаптировать ИТ-проекты под эру LLM

Последние полгода стало модно создавать новые и переводить старые проекты на рельсы AI-First (или AI-Friendly) стандарта. Уже появляются проекты, которые декларируются как «designed for AI to write». Например, AIR ^[1] — AI-First веб-фреймворк на Python.

В этой статье я хочу рассказать о том, как сделать свой проект дружелюбным для ИИ и тем самым повысить его юзабилити и помочь пользователям быстрее начать им пользоваться. ИИ-агенты стали новыми потребителями вашего кода. У них своя экономика токенов, свои требования к проекту и его документации. Хорошая новость в том, что настроить все можно за несколько часов — будь то забытый корпоративный микросервис или новый opensource-проект.

Это может пригодиться как создателям открытых проектов, так и разработчикам внутренних корпоративных проектов. Итак, начнем с матчасти.

AI-Friendly и AI-First на практике

Понятия AI-friendly и AI-first практически равнозначны. AI-Friendly означает проект, который можно использовать через ИИ-агента без лишних сложностей. AI-First — когда проект с самого начала проектируется с учетом удобства использования через ИИ. Разница состоит в усилиях и позиционировании проекта, хотя суть остается той же: проект должен быть понятен машине.

Можно выделить три уровня «дружелюбного к ИИ» проекта:

На схеме они расположены по порядку.

Уровень документации — самый важный, потому что именно он объясняет связи, взаимодействие и использование проекта. Здесь играет роль экономия токенов: «плоские» файлы легче анализировать, чем парсить документацию с сайта. Какие файлы нужно создать, рассмотрим ниже.

Уровень кода — не менее важен. Как гласит дзен питона, простое лучше сложного, а сложное лучше запутанного. Код должен быть понятным, а связи — легко угадываемыми. Здесь стоит следовать принципам SOLID, DRY и KISS. Человекочитаемый код читаем и для ИИ-агента. Желательно, чтобы существовал один способ сделать что-то — это помогает и человеку, и ИИ-агенту, снижая вероятность ошибок. Чистая архитектура здесь не имеет радикальных отличий именно для ИИ-агентов.

Уровень внешних сервисов — дополнительный слой, который дает удобство в использовании проекта. Ниже приведу примеры сервисов, помогающих сделать проект удобнее для работы через ИИ-агентов.

Давайте перейдем непосредственно к практике.

Инфраструктура AI-Friendly/AI-First проекта

Любая база не работает без инфраструктуры, которая выступает как указатели для ИИ-агентов. Поскольку это связано с обработкой естественного языка, логично ^[2] предположить, что главное для агента — качественная документация, описывающая работу с проектом. Причем не только пользовательская, но и специализированные форматы для ИИ.

AGENTS.md

AGENTS.md — открытый формат для направления ИИ-агента в нужную сторону. Это как README, но для агентов: содержит команды для развертывания приложений, стиль кода, запрещенные и разрешенные паттерны.

 # AGENTS.md
 
 ## Setup commands
 - Install deps: pnpm install
 - Start dev server: pnpm dev
 - Run tests: pnpm test
 
 ## Code style
 - TypeScript strict mode
 - Single quotes, no semicolons
 - Use functional patterns where possible

Можете рассмотреть реально существющий пример — AGENTS.md ^[3] из AIR ^[4] — веб-фреймворк на Python, который заявляется как «designed for AI». Он содержит инструкции по работе с HTML-макетами, код минимального приложения, правила маршрутизации, шаблонизации, формы, SSE, базы данных, общие паттерны, структуру, зависимости и многое другое. Это сжатая документация для разработчика с заметками и стилем кода — нечто среднее между CONTRIBUTING.md ^[5], README.md ^[6] и документацией.

Правила Cursor IDE

Правила Cursor (Rules) — это постоянные инструкции для ИИ-агента: стиль кода, архитектура, соглашения по проекту. Без них модель не знает ваших конвенций и может предлагать лишнее или не в том формате. В Cursor правила находятся в директории .cursor/rules/ в виде файлов .mdc.

Отличие от AGENTS.md ^[3] — в точечном применении именно в AI-IDE Cursor. Само правило короче чем AGENTS.md ^[3], так как содержит код именно по использованию.

Разберем на примере проекта FastStream ^[7], Python-фреймворка для микросервисов на очередях (Kafka, RabbitMQ, NATS, Redis) — он работает с любым брокером. FastStream автоматически генерирует документацию на основе аннотаций типов. Вы пишете обработчик с Pydantic-моделью — фреймворк сам понимает, какие поля ожидать, и создает OpenAPI-схему. Также он имеет заготовленный файл .cursor/rules/faststream.mdc ^[8], который содержит основные правила использования этого проекта.

То есть по факту это тот же markdown с небольшой надстройкой:

 ---
 description: Python code style for this project
 globs: *.py
 ---
 
 Always use type hints. Never use except: without an exception class. Prefer dataclasses over plain dicts for structured data. Use f-strings, not .format() or %.

Поле globs указывает, к каким файлам применять правило. .py — ко всем Python-файлам. Можете сделать правило только для tests/.py или для examples/.

AI-навигация через llms.txt

Это свежий стандарт от Answer.AI ^[9], созданный с простой идеей: дать агентам карту документации. llms.txt — индекс в виде обычного текстового файла со списком ссылок. Агент сканирует его и решает, что читать дальше.

 # Documentation index for MyLibrary
 
 ## Getting started
 - https://mylib.dev/docs/installation.md
 - https://mylib.dev/docs/quickstart.md
 
 ## Core API
 - https://mylib.dev/docs/api/client.md
 - https://mylib.dev/docs/api/auth.md
 
 ## Examples
 - https://mylib.dev/docs/examples/basic.md
 - https://mylib.dev/docs/examples/advanced.md

llms-full.txt — полный текст документации в одном файле. Агент может скачать его один раз и держать в контексте, не ходя по двадцати ссылкам. Чтобы сгенерировать llms-full.txt, нужно склеить все страницы документации в один файл (markdown, rST или другой похожий формат).

Эти файлы стоит размещать на сайте документации — как, например, в проекте django-modern-rest ^[10]: https://django-modern-rest.readthedocs.io/llms.txt ^[11] и https://django-modern-rest.readthedocs.io/llms-full.txt ^[12].

Здесь важна экономия: агенты ограничены по токенам, и им выгоднее прочитать один файл, чем ходить по множеству ссылок и парсить HTML. Этот стандарт помогает как в навигации, так и в самом чтении документации.

Внешние сервисы

Эта тема связана немного косвенно, но также важна для удобства конечных пользователей.

Context7

Проблема многих LLM в том, что они знают только то, что было в тренировочных данных. Если вашу библиотеку выпустили вчера, GPT-4 про нее не слышал. А если слышал, примеры кода будут из прошлогодней версии, где API уже изменился.

Context7 решает это через MCP (Model Context Protocol). Сервер берет актуальную документацию и кладет ее в промпт агента.

Вот, например, как выглядит главное окно проекта в Context7:

Он имеет свою систему бенчмарков документации, так что вы всегда можете улучшать документацию своего проекта:

Также вы можете добавить ИИ-чат прямо на сайт документации.

Технически Context7 — это MCP-сервер, который работает с Cursor, Claude Code, VSCode, Windsurf. Он написан на Node.js 18+. Установка через npx, настройка через конфиг MCP-клиента. Пара нажатий — и по вашей документации можно искать через естественный язык и строить сложные запросы.

DeepWiki: генерация вики по проекту

Cognition Labs (команда, создавшая Devin AI) запустила DeepWiki в апреле 2025 года. Идея проста: берете любой публичный репозиторий на GitHub, заменяете в URL github.com ^[13] на deepwiki.com ^[14] — и получаете полноценную вики с диаграммами и AI-ассистентом.

DeepWiki генерирует описание проекта, его стек, версии, зависимости, структуру файлов, интерактивные схемы и диаграммы, а также предоставляет AI-чат для вопросов по проекту. Это более простая альтернатива Context7, но также полезная.

Итак, AGENTS.md ^[3] и правила Cursor создают декларации для ИИ-агента о паттернах генерации кода. llms.txt реализует быструю индексацию документации. Context7 и DeepWiki предлагают пользователям и агентам документацию с поиском на естественном языке и MCP-сервером.

Уровень кода опущен здесь потому, что важно само качество, а не его конкретная оптимизация только под ИИ. AI-friendly ваш проект или нет, код должен оставаться читаемым и чистым.

Пошаговая инструкция

Теперь самое время упорядочить то, что мы узнали, и объединить все в понятный список действий.

1. Положите в корень AGENTS.md ^[3].

• Опишите проект, структуру репозитория, ключевые файлы.

• А также можете позаимствовать советы по работе с ИИ от Андрея Карпаты по ссылке ^[15] (всего 65 строк, четыре принципа: думай и спрашивай перед кодингом, упрощай, меняй только то, что просят, работай над четкой целью).

2. Добавьте llms.txt и llms-full.txt.

• Если у вас есть сайт с документацией — положите файлы в корень. Если нет — создайте папку docs и сгенерируйте эти файлы из README и докстрингов. Агент скажет спасибо. Ну или можете создать issue в своем проекте и подождать, когда другой человек захочет помочь.

3. Проверяйте код через анализаторы типов, линтеры и тесты.

• Этот совет применим не только к AI-Friendly проектам и является универсальным для всех. Иногда 100% покрытие тестами и политика zero-warnings делают библиотеку невероятно стабильной, а ее API — понятным и для человека, и для машины.

4. Подключите сторонние сервисы.

• Добавьте проект в Context7 — это бесплатно и занимает пару минут. Убедитесь, что DeepWiki видит ваш репозиторий (обычно достаточно, чтобы он был публичным).

5. Напишите AI_POLICY.md в папку .github.

• Это полезная дополнительная вещь, которая позволит отгородить проект от «нейрослопа». Это не панацея, но напомнит потенциальным контрибьюторам, что ответственность несет человек. Пример такой политики можно посмотреть у astral-sh ^[16].

Вот и все. Пять действий, два-три часа работы. После этого ваш проект станет понятнее для агентов — а значит, для тысяч разработчиков, которые работают через агентов. Это не дополнительная нагрузка, а новый стандарт поддержки, как Community Guidelines десять лет назад.

AI-friendly не означает зеленый свет для «нейрослопа». Наоборот, это повод задуматься об инженерном опыте ^[17] и ответственности. Если ваш код понятен агенту — он почти наверняка понятен и человеку. Чистые имена, явная типизация, отсутствие магии, качественная документация — это то, что нужно всем.

Пробуйте, ломайте, улучшайте. И пусть ваш код читают не только люди.