Привет, Хабр! Последние полгода стало модно создавать новые и переводить старые проекты на рельсы AI-First (или AI-Friendly) стандарта. Уже появляются проекты, которые декларируются как «designed for AI to write». Например, AIR — AI-First веб-фреймворк на Python.
В этой статье я хочу рассказать о том, как сделать свой проект дружелюбным для ИИ и тем самым повысить его юзабилити и помочь пользователям быстрее начать им пользоваться. ИИ-агенты стали новыми потребителями вашего кода. У них своя экономика токенов, свои требования к проекту и его документации. Хорошая новость в том, что настроить все можно за несколько часов — будь то забытый корпоративный микросервис или новый opensource-проект.
Это может пригодиться как создателям открытых проектов, так и разработчикам внутренних корпоративных проектов. Итак, начнем с матчасти.
AI-Friendly и AI-First на практике
Понятия AI-friendly и AI-first практически равнозначны. AI-Friendly означает проект, который можно использовать через ИИ-агента без лишних сложностей. AI-First — когда проект с самого начала проектируется с учетом удобства использования через ИИ. Разница состоит в усилиях и позиционировании проекта, хотя суть остается той же: проект должен быть понятен машине.
Можно выделить три уровня «дружелюбного к ИИ» проекта:
На схеме они расположены по порядку.
Уровень документации — самый важный, потому что именно он объясняет связи, взаимодействие и использование проекта. Здесь играет роль экономия токенов: «плоские» файлы легче анализировать, чем парсить документацию с сайта. Какие файлы нужно создать, рассмотрим ниже.
Уровень кода — не менее важен. Как гласит дзен питона, простое лучше сложного, а сложное лучше запутанного. Код должен быть понятным, а связи — легко угадываемыми. Здесь стоит следовать принципам SOLID, DRY и KISS. Человекочитаемый код читаем и для ИИ-агента. Желательно, чтобы существовал один способ сделать что-то — это помогает и человеку, и ИИ-агенту, снижая вероятность ошибок. Чистая архитектура здесь не имеет радикальных отличий именно для ИИ-агентов.
Уровень внешних сервисов — дополнительный слой, который дает удобство в использовании проекта. Ниже приведу примеры сервисов, помогающих сделать проект удобнее для работы через ИИ-агентов.
Давайте перейдем непосредственно к практике.
Инфраструктура AI-Friendly/AI-First проекта
Любая база не работает без инфраструктуры, которая выступает как указатели для ИИ-агентов. Поскольку это связано с обработкой естественного языка, логично предположить, что главное для агента — качественная документация, описывающая работу с проектом. Причем не только пользовательская, но и специализированные форматы для ИИ.
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 из AIR — веб-фреймворк на Python, который заявляется как «designed for AI». Он содержит инструкции по работе с HTML-макетами, код минимального приложения, правила маршрутизации, шаблонизации, формы, SSE, базы данных, общие паттерны, структуру, зависимости и многое другое. Это сжатая документация для разработчика с заметками и стилем кода — нечто среднее между CONTRIBUTING.md, README.md и документацией.
Правила Cursor IDE
Правила Cursor (Rules) — это постоянные инструкции для ИИ-агента: стиль кода, архитектура, соглашения по проекту. Без них модель не знает ваших конвенций и может предлагать лишнее или не в том формате. В Cursor правила находятся в директории .cursor/rules/ в виде файлов .mdc.
Отличие от AGENTS.md — в точечном применении именно в AI-IDE Cursor. Само правило короче чем AGENTS.md, так как содержит код именно по использованию.
Разберем на примере проекта FastStream, Python-фреймворка для микросервисов на очередях (Kafka, RabbitMQ, NATS, Redis) — он работает с любым брокером. FastStream автоматически генерирует документацию на основе аннотаций типов. Вы пишете обработчик с Pydantic-моделью — фреймворк сам понимает, какие поля ожидать, и создает OpenAPI-схему. Также он имеет заготовленный файл .cursor/rules/faststream.mdc, который содержит основные правила использования этого проекта.
То есть по факту это тот же 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, созданный с простой идеей: дать агентам карту документации. 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.mdllms-full.txt — полный текст документации в одном файле. Агент может скачать его один раз и держать в контексте, не ходя по двадцати ссылкам. Чтобы сгенерировать llms-full.txt, нужно склеить все страницы документации в один файл (markdown, rST или другой похожий формат).
Эти файлы стоит размещать на сайте документации — как, например, в проекте django-modern-rest: https://django-modern-rest.readthedocs.io/llms.txt и https://django-modern-rest.readthedocs.io/llms-full.txt.
Здесь важна экономия: агенты ограничены по токенам, и им выгоднее прочитать один файл, чем ходить по множеству ссылок и парсить 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 на deepwiki.com — и получаете полноценную вики с диаграммами и AI-ассистентом.
DeepWiki генерирует описание проекта, его стек, версии, зависимости, структуру файлов, интерактивные схемы и диаграммы, а также предоставляет AI-чат для вопросов по проекту. Это более простая альтернатива Context7, но также полезная.
Итак, AGENTS.md и правила Cursor создают декларации для ИИ-агента о паттернах генерации кода. llms.txt реализует быструю индексацию документации. Context7 и DeepWiki предлагают пользователям и агентам документацию с поиском на естественном языке и MCP-сервером.
Уровень кода опущен здесь потому, что важно само качество, а не его конкретная оптимизация только под ИИ. AI-friendly ваш проект или нет, код должен оставаться читаемым и чистым.
Пошаговая инструкция
Теперь самое время упорядочить то, что мы узнали, и объединить все в понятный список действий.
Положите в корень AGENTS.md.
Опишите проект, структуру репозитория, ключевые файлы.
А также можете позаимствовать советы по работе с ИИ от Андрея Карпаты по ссылке (всего 65 строк, четыре принципа: думай и спрашивай перед кодингом, упрощай, меняй только то, что просят, работай над четкой целью).
Добавьте llms.txt и llms-full.txt.
Если у вас есть сайт с документацией — положите файлы в корень. Если нет — создайте папку docs и сгенерируйте эти файлы из README и докстрингов. Агент скажет спасибо. Ну или можете создать issue в своем проекте и подождать, когда другой человек захочет помочь.
Проверяйте код через анализаторы типов, линтеры и тесты.
Этот совет применим не только к AI-Friendly проектам и является универсальным для всех. Иногда 100% покрытие тестами и политика zero-warnings делают библиотеку невероятно стабильной, а ее API — понятным и для человека, и для машины.
Подключите сторонние сервисы.
Добавьте проект в Context7 — это бесплатно и занимает пару минут. Убедитесь, что DeepWiki видит ваш репозиторий (обычно достаточно, чтобы он был публичным).
Напишите AI_POLICY.md в папку .github.
Это полезная дополнительная вещь, которая позволит отгородить проект от «нейрослопа». Это не панацея, но напомнит потенциальным контрибьюторам, что ответственность несет человек. Пример такой политики можно посмотреть у astral-sh.
Вот и все. Пять действий, два-три часа работы. После этого ваш проект станет понятнее для агентов — а значит, для тысяч разработчиков, которые работают через агентов. Это не дополнительная нагрузка, а новый стандарт поддержки, как Community Guidelines десять лет назад.
AI-friendly не означает зеленый свет для «нейрослопа». Наоборот, это повод задуматься об инженерном опыте и ответственности. Если ваш код понятен агенту — он почти наверняка понятен и человеку. Чистые имена, явная типизация, отсутствие магии, качественная документация — это то, что нужно всем.
Пробуйте, ломайте, улучшайте. И пусть ваш код читают не только люди.