Около 90% фронтенд‑разработчиков в нашей команде используют ИИ‑помощников для написания кода. Лично у меня — и как я могу заметить, у многих — был такой опыт: вы только начинаете пользоваться ИИ‑помощником, просите его сгенерировать какое‑нибудь классное MVP, получаете результат минут за пять и думаете: «Вау, неужели это возможно? Как это вообще работает и как это круто».
А дальше вас ждёт сюрприз.
Всем привет, меня зовут Валерий Баранов, я руковожу командой технологий фронтенда в Яндекс 360. Мы занимаемся тем, что сами называем «общим фронтендом»: общими техническими компонентами, общим CI/CD, платформами дистрибуции общих компонентов. Сегодня я хочу рассказать, как мы в Яндекс 360 сделали фронтенд‑проекты по‑настоящему AI‑ready: научили ассистентов понимать структуру наших репозиториев, работать с внутренними библиотеками и даже соблюдать паттерны дизайн‑системы.
Долина разочарования
Первый час работа идёт хорошо. Ассистент выдаёт именно то, что вы хотите, и кажется, что дальше всё будет так же. Но если вы планируете за пару недель сделать свой следующий SaaS, реальность оказывается сложнее. Обычно в первые пять часов работы над нетривиальной задачей вместе с ИИ‑помощником наступает то, что можно назвать долиной разочарования. Это состояние хорошо описывается фразами вроде:
- «Да я сам быстрее напишу»;
- «Ты зачем переделал то, что уже работало?»;
- «Откуда ты взял этот компонент — его же у нас нет».
Ассистент не понимает, предлагает странные решения, меняет собственные подходы, переписывает код, который только что написал. В такой ситуации часто хочется на него накричать (но он не услышит).
Часто ИИ‑помощники применяются разработчиками для тривиальных задач: написать JSDoc, сгенерировать параметры, помочь на этапе completion. При этом действительно сложные кейсы составляют, по ощущениям, около 10% от всего использования. Возникает вопрос: почему так происходит.
Почему модели так важен контекст
Один из возможных ответов довольно простой: вместо того чтобы «орать на модель», ей нужно дать правильный контекст. Но если мы говорим о правильном контексте, стоит сначала понять, что вообще является контекстом для модели. Для этого полезно сделать шаг назад и посмотреть, как выглядит реальная работа фронтендера.
Если говорить именно о задачах с UI, в моей голове этот процесс выглядит примерно так (для простоты я опускаю некоторые шаги процесса, но в данном контексте это не принципиально):
- Разработчик открывает задачу в Трекере. В задаче описаны требования, и, поскольку мы говорим про интерфейсы, там обязательно есть ссылка на макет в Figma.
- Дальше разработчик внимательно изучает требования, переходит в Figma и разбирается с дизайнами: смотрит, какие используются компоненты, какие токены, какие марджины и паддинги заложили дизайнеры.
- Если какие‑то компоненты не вспоминаются, или подзабылось, как именно устроен UI‑kit, разработчик идёт в Storybook — смотреть документацию по компонентам и токенам.
- После этого он пишет код и открывает pull request. По результатам этого pull request проводится дизайн‑ревью.
- Pull request не всегда соответствует тому, как дизайнер изначально представлял себе реализацию. Разработчик может ошибиться — выбрать не те компоненты или использовать не те токены.
- Дизайнер указывает на проблему, и разработчик всё исправляет и мерджит PR.
И вот здесь возникает вопрос: способен ли ИИ‑помощник проделать тот же самый путь?
Как оптимист, я всё же считаю, что он сможет справиться с этим, если дать правильный контекст и правильные инструменты.
Пирамида контекста
Когда мы говорим о контексте, его удобно представлять в виде пирамиды контекста проекта. Слово «пирамида» здесь не случайно — сразу возникает ассоциация с пирамидой тестирования.
Внизу находятся быстрые юнит‑тесты: их легко писать, они быстро выполняются и уже приносят пользу проекту. Выше — интеграционные тесты: они требуют больше времени, но дают дополнительную ценность. На вершине — самые сложные E2E‑тесты, которые писать трудно, но если они есть, проект получает максимальный эффект.
С контекстом для LLM ситуация очень похожая. Если задуматься о том, какой контекст нужен модели, чтобы она могла корректно работать с вашим проектом, первым пунктом будет понимание специфики самого проекта. Второе — специфика библиотек, которые в нём используются, и их документация.
На практике здесь возникает проблема: во фронтенде могут использоваться внутренние библиотеки. Их документации нет во внешнем контуре, а значит, её нет и в корпусе знаний модели. Более того, нередко документации нет даже у самих библиотек.
И, наконец, дизайн. Поскольку мы фронтендеры, дизайн — это часть нашей повседневной работы. Но он живёт отдельно: в Figma, в инструменте, который никак напрямую не связан ни с кодом, ни с дизайн‑системой в репозитории, ни с редактором, в котором мы пишем код.
Как настроить контекст
Давайте поговорим о том, как можно настроить правильный контекст и помочь модели. Отмечу самый простой и практичный, на мой взгляд, вариант: файл контекста с названием AGENTS.md.
AGENTS.md— это открытый стандарт, который уже поддерживают Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Zed. То есть один файл работает для всех код‑ассистентов, которыми может пользоваться команда — не нужно поддерживать отдельные конфигурации для каждого инструмента.
Задача этого файла — дать ИИ‑помощнику карту проекта, чтобы он не тратил время на первичное разбирательство. GitHub провёл анализ более 2500 репозиториев с AGENTS.md и выделил структуру, которая работает лучше всего:
- Project Overview→ что это за проект, 2–3 предложения.
- Project Structure→ дерево директорий с аннотациями и архитектурными ограничениями.
- Commands→ как собрать, протестировать, запустить (копируемые команды).
- Conventions→ конвенции, которые линтеры не могут проверить.
- Boundaries→ что делать всегда, что спросить, чего не делать никогда.
Вот как это выглядит в реальном проекте:
Что писать, а что не стоит
Здесь работает простое правило: пишите только то, что модель не может обнаружить сама, или на это обнаружение уйдет много времени или запросов.
Стоит включить:
- порядок команд верификации и однострочник для проверки перед коммитом;
- назначение внутренних пакетов и их конвенции;
- специфичные для проекта ограничения (MUST DO / MUST NOT);
- особенности workflow разработки (например, использование нестандартной системы контроля версий).
Не стоит включать:
- версии технологий (модель прочитает package.json);
- базовые паттерны фреймворка (модель знает React hooks);
- переменные окружения (модель прочитает.env.example);
- стандартные паттерны тестирования.
ПоданнымSFEIR Institute, когда инструкции написаны в повелительном стиле («Используй CSS Modules для новых компонентов»), модель следует им в 94% случаев. Описательный стиль («Мы обычно используем CSS Modules») даёт только 73%.
Меньше — значит, лучше
Важный нюанс:исследования HumanLayerпоказывают, что LLM могут стабильно следовать примерно 150–200 инструкциям. При этом системный промпт самого ассистента уже занимает около 50 из них. Остаётся 100–150 для вашего проекта. А деградация при перегрузке контекстом равномерная — страдают все инструкции, а не только новые.
Другими словами, AGENTS.md должен быть коротким — до 300 строк для крупных сервисов, до 150 для библиотек. Каждая строка должна оправдывать своё присутствие. Если информация не поместилась, выносите детали в отдельные файлы документации и ссылайтесь на них. Модель загрузит их по запросу, когда они понадобятся. Это как оглавление книги: оно ничего не стоит, пока к нему не обратились, но позволяет быстро найти нужную главу.
По данным SFEIR,хорошо структурированный AGENTS.md на 80 строк сокращает количество ручных исправлений за моделью на 40%.
Типичные ошибки
Из опыта нашей команды и данных сообщества, вот ошибки, которые допускают чаще всего:
- AGENTS.md‑монолит. Когда в файл складывают всё подряд — документацию API, примеры кода, историю решений — точность модели падает при заполнении контекстного окна на 70%.
- Расплывчатые инструкции. «Используй современные подходы к написанию компонентов и стилей» бесполезно. Модель не понимает, как это применить к конкретному проекту. Лучше: «Новые компоненты создавай в src/components/, используй CSS Modules, не создавай.styl файлы».
- Дублирование файлов контекста. Отдельные файлы для каждого ассистента расходятся в своих данных уже через неделю. AGENTS.md решает это: один файл, одна правда.
- Конфиг вместо линтера. Не надо писать в AGENTS.md правила форматирования, которые eslint/prettier уже проверяют. AGENTS.md — для того, что линтеры не смогут проверить.
Самоподдерживающаяся документация
Самое ценное свойство AGENTS.md — возможность сделать документацию самоподдерживающейся. Если в секции Boundaries написать «Всегда обновляй AGENTS.md при изменении структуры проекта», модель будет это делать. Никаких команд, никаких триггеров — документация инструктирует агента поддерживать саму себя.
Мы закрыли первый уровень пирамиды контекста для проекта, но это только начало. Идём дальше и попробуем закрыть остальные уровни.
Контекст дизайн‑системы и UI‑kit
На этом этапе мы упираемся в ситуацию, знакомую практически всем командам, которые работают с собственным UI‑kit — как научить ИИ‑помощника понимать особенности компонентов вашего проекта.
У нас в Яндекс 360 есть UI‑kit Orbita. Дизайнеры работают с дизайн‑системой, которая тоже называется Orbita. Сам UI‑kit — это библиотека компонентов orb‑components. Здесь важно сразу сделать дисклеймер: дизайн‑система Orbita изначально проектировалась как кроссплатформенная. Она должна быть консистентной между тремя платформами:
- web (о нём мы сегодня и говорим);
- мобильными платформами — Android и iOS;
- и десктопом.
Чтобы предметно говорить о том, что нужно сделать, чтобы дизайн‑система стала AI Ready — спроектированной так, чтобы с ней могли эффективно работать и люди, и ИИ‑инструменты (LLM, генераторы UI, кодогенерация) без дополнительных костылей и ручной адаптации. Разберёмся, из каких частей она состоит. Для простоты можно представить дизайн‑систему как структуру из трёх слоёв.
Первый слой — Foundation. Это основа, в которой определяются типографика, цвета, токены, иконки. Именно эту базу мы используем для того, чтобы поверх неё собирать компоненты.
Компоненты могут быть разного уровня сложности. Есть атомарные компоненты — например, Button или Input. Есть более сложные составные элементы — например, Suggest, внутри которого переиспользуются несколько атомарных компонентов. Такие более крупные сущности часто называют молекулами.
Следующий важный момент — компоненты сами по себе являются лишь строительными блоками. Это переиспользуемые «кирпичики» для интерфейсов. Но если начать использовать их в разных продуктах по‑разному, мы не получим того результата, к которому стремимся, и единого пользовательского опыта. А нам важно, чтобы пользователи, перемещаясь между разными сервисами Яндекс 360, получали один и тот же пользовательский опыт, а интерфейсы были собраны с использованием одних и тех же паттернов.
Поэтому следующий, самый верхний уровень пирамиды — это паттерны использования компонентов.
Паттерны использования компонентов
В качестве паттернов использования компонентов можно привести примеры, хорошо знакомые всем:
- настройки профиля;
- настройки приложения в целом;
- GlobalBar — плашка слева в сервисах Яндекс 360 для переключения между сервисами, это общий компонент в разных сервисах.
И здесь мы упираемся в ключевую проблему. Мы, как разработчики, всегда можем подойти к коллеге или дизайнеру и спросить, как именно это устроено — и он не только объяснит, но и расскажет, почему было сделано именно так, а LLM этого, к сожалению, не знает. И для нас критически важно донести эти знания до модели. Только в этом случае она сможет понимать, как устроена дизайн‑система, и использовать это понимание для сборки интерфейсов, а не просто комбинировать компоненты формально.
Model Context Protocol и документация
Для передачи такого контекста можно использовать Model Context Protocol (MCP) — протокол, с помощью которого модель получает контекст, необходимый ей для выполнения текущей задачи. Пример MCP, который хорошо знаком многим и, скорее всего, уже используется, — Context 7 для документации. Здесь, правда, важно уточнить: он работает для документации, доступной во внешнем контуре.
Если же речь идёт о внутренних компонентах, внутренних пакетах или внутреннем UI‑kit, то вам потребуется свой MCP‑сервер для документации. Поэтому знакомлю вас с MCP‑сервером Orbita DS. Мы сделали его специально для того, чтобы фронтендеры, использующие Orbita в своих проектах, могли получать знания по каждому слою дизайн‑системы.
Через этот MCP‑сервер модель может узнать:
- про Foundation — токены и правила их использования;
- про компоненты — с актуальным API и примерами применения;
- про паттерны композиции компонентов.
И, конечно, один из первых шагов — подключение UI‑kit. Без этого всё остальное просто не имеет смысла.
Мы сделали MCP‑сервер с документацией и начали предоставлять его нашим клиентам — фронтендерам внутри компании. Казалось бы, всё сделано правильно, в чём может быть подвох?
Дело в разнице реализаций. Реализация UI‑kit практически всегда будет отличаться от реализации в Figma — по крайней мере, если UI‑kit активно развивается. Сценарий знакомый: дизайнеры уже нарисовали новый компонент, а в коде он ещё не реализован. Или, наоборот — в UI‑kit остаются компоненты, которые уже не используются и их давно нет в дизайне, но в кодовой базе они всё ещё присутствуют.
Когда Figma и код говорят на разных языках
Хороший пример проблемы рассинхронизации — нейминг props. Он вполне может отличаться даже у одного и того же компонента, который существует и в UI‑kit, и в Figma.
Например, в коде у нас prop называется isDisabled, а в дизайне тот же самый параметр называется enabled. Разработчик смотрит на компонент в Figma, видит вариант enabled и делает логичный вывод: «Ага, нужно использовать prop enabled». Он идёт в IDE, пытается написатьenabled={...}, но такого prop в компоненте просто нет. Он идёт в Storybook — и там тоже не находит enabled. В итоге он пишет нам в поддержку, а мы отвечаем: «Друг, это же isDisabled. Всё же очевидно».
Чтобы такие ситуации не возникали, Figma и код нужно синхронизировать. А для этого прежде всего важно договориться, где правда.
Мы договорились с дизайнерами следующим образом: во всём, что касается того, какие требования предъявляются к компонентам, источник правды — Figma. Foundation‑компоненты, паттерны, иконки — всё это выгружается из Figma, и именно она считается источником истины.
А вот в том, что касается тонкостей реализации компонентов — как именно называются компоненты, как называются props, — источник правды уже код. Когда мы разрабатываем компоненты, мы думаем о преемственности с предыдущими версиями, о соответствии индустриальным конвенциям и об удобстве для разработчиков. Эти вещи дизайнеры могут просто не знать — и это нормально.
Как мы связываем дизайн и код
Каждый слой дизайн‑системы связан с кодовой базой отдельным инструментом:
- Foundation (токены, иконки)→Figmograph, наш внутренний пакет для выгрузки всех токенов и иконок под все платформы. При этом он умеет работать не только с web: данные выгружаются под все платформы. Для каждой платформы существует отдельный пакет, в котором лежат соответствующие значения.
- Компоненты→ Figma Code Connect, связывает реализацию в коде с представлением в Figma. С его помощью можно описать маппинг свойств — как они называются в Figma и как они называются в коде.
- Паттерны→MCP Orbita,который используем для передачи LLM информации о паттернах: какие паттерны реализованы в системе и как они описаны. Это позволяет модели лучше понимать, какие решения стоит применять и как именно реализовывать те или иные паттерны.
В результате LLM, обладая полной картиной знаний о нашем UI‑kit, может генерировать корректный код для фронтендеров, а не просто угадывать названия компонентов и props.
Что в итоге получилось
В результате мы:
- закрыли контекст проекта с помощью AGENTS.md;
- закрыли контекст библиотек через MCP;
- связали дизайн и код с помощью Figma Code Connect.
Используя такой подход, мы получаем AI‑ready фронтенд‑проекты. В них есть информация, которая позволяет генерировать корректные интерфейсы:
- о контексте самого проекта,
- о контексте используемых пакетов и инструментов,
- о контексте дизайн‑системы.
И вот как сейчас выглядят реальные трудозатраты на каждый уровень:
Трудозатраты
Базовый контекст проекта, поддержка всех ассистентов
MCP для UI‑kit
Документация библиотеки в контексте модели
Figma Code Connect
Связь дизайна и кода, актуальный маппинг props
Вывод простой: эффективность ИИ‑помощника напрямую зависит от того, насколько хорошо он знает ваш проект, его архитектурные особенности и правила работы с UI‑kit. Простые решения, вроде структурированного AGENTS.md, быстро передают ассистенту базовый контекст — и уже этого достаточно, чтобы сэкономить десятки часов на ручных переделках. Когда же добавляется интеграция с MCP и автоматическая синхронизация кода с дизайном, ИИ‑помощник становится полноценным участником команды, способным генерировать корректный, поддерживаемый код.
ИИ в разработке — это не магия, а инфраструктурная работа. Начните с малого: с одного документа и описания ключевых конвенций в проекте. А затем шаг за шагом закрывайте оставшиеся «дыры» — описывайте внутренние библиотеки, синхронизируйте дизайн и реализацию, автоматизируйте связь между системами.
А какой контекст уже передаёте своему ИИ‑помощнику вы? Делитесь своими приёмами и наблюдениями.
Больше про ИИ пишу в своёмтелеграм‑канале, присоединяйтесь!
