ИИ‑помощник не понимает ваш UI Kit? Показываем, как это починить

Около 90% фронтенд‑разработчиков в нашей команде используют ИИ‑помощников для написания кода. Лично у меня — и как я могу заметить, у многих — был такой опыт: вы только начинаете пользоваться ИИ‑помощником, просите его сгенерировать какое‑нибудь классное MVP, получаете результат минут за пять и думаете: «Вау, неужели это возможно? Как это вообще работает и как это круто». 

А дальше вас ждёт сюрприз. 

Всем привет, меня зовут Валерий Баранов, я руковожу командой технологий фронтенда в Яндекс 360. Мы занимаемся тем, что сами называем «общим фронтендом»: общими техническими компонентами, общим CI/CD, платформами дистрибуции общих компонентов. Сегодня я хочу рассказать, как мы в Яндекс 360 сделали фронтенд-проекты по‑настоящему AI-ready: научили ассистентов понимать структуру наших репозиториев, работать с внутренними библиотеками и даже соблюдать паттерны дизайн-системы.

Долина разочарования

Первый час работа идёт хорошо. Ассистент выдаёт именно то, что вы хотите, и кажется, что дальше всё будет так же. Но если вы планируете за пару недель сделать свой следующий SaaS, реальность оказывается сложнее. Обычно в первые пять часов работы над нетривиальной задачей вместе с ИИ‑помощником наступает то, что можно назвать долиной разочарования. Это состояние хорошо описывается фразами вроде:

• «Да я сам быстрее напишу»;

• «Ты зачем переделал то, что уже работало?»;

• «Откуда ты взял этот компонент — его же у нас нет».

Ассистент не понимает, предлагает странные решения, меняет собственные подходы, переписывает код, который только что написал. В такой ситуации часто хочется на него накричать (но он не услышит).

Часто ИИ-помощники применяются разработчиками для тривиальных задач: написать JSDoc, сгенерировать параметры, помочь на этапе completion. При этом действительно сложные кейсы составляют, по ощущениям, около 10% от всего использования. Возникает вопрос: почему так происходит?

Почему модели так важен контекст

Один из возможных ответов довольно простой: вместо того чтобы «орать на модель», ей нужно дать правильный контекст. Но если мы говорим о правильном контексте, стоит сначала понять, что вообще является контекстом для модели. Для этого полезно сделать шаг назад и посмотреть, как выглядит реальная работа фронтендера.

Если говорить именно о задачах с UI, в моей голове этот процесс выглядит примерно так (для простоты я опускаю некоторые шаги процесса, но в данном контексте это не принципиально): 

1. Разработчик открывает задачу в Трекере. В задаче описаны требования, и, поскольку мы говорим про интерфейсы, там обязательно есть ссылка на макет в Figma.

2. Дальше разработчик внимательно изучает требования, переходит в Figma и разбирается с дизайнами: смотрит, какие используются компоненты, какие токены, какие марджины и паддинги заложили дизайнеры.

3. Если какие-то компоненты не вспоминаются или подзабылось, как именно устроен UI Kit, разработчик идёт в Storybook — смотреть документацию по компонентам и токенам.

4. После этого он пишет код и открывает pull request. По результатам этого pull request проводится дизайн‑ревью. 

5. Pull request не всегда соответствует тому, как дизайнер изначально представлял себе реализацию. Разработчик может ошибиться — выбрать не те компоненты или использовать не те токены.

6. Дизайнер указывает на проблему, и разработчик всё исправляет и мерджит 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 → что делать всегда, что спросить, чего не делать никогда.

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

# Project Overview
Фронтенд-платформа для сервисов Яндекс 360.
Монорепо: packages/ — общие библиотеки, apps/ — отдельные сервисы.

# Commands
npm run typecheck && npm run lint  # запустить перед каждым коммитом

# Conventions
- Новые компоненты создавай в packages/ui/, используй CSS Modules, не создавай .styl файлы
- Внутренний пакет @orb/components — это UI-kit Orbita, предпочитай его сторонним библиотекам
- Импорты только через алиасы (@orb/...), не через относительные пути за пределами пакета

# Boundaries
MUST: обновляй AGENTS.md при изменении структуры проекта
MUST NOT: не подключай новые пакеты без обсуждения с пользователем

Что писать, а что не стоит

Здесь работает простое правило: пишите только то, что модель не может обнаружить сама, или на это обнаружение уйдет много времени или запросов.

Стоит включить:

• порядок команд верификации и однострочник для проверки перед коммитом;

• назначение внутренних пакетов и их конвенции;

• специфичные для проекта ограничения (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 фронтенд-проекты. В них есть информация, которая позволяет генерировать корректные интерфейсы:

• о контексте самого проекта;

• о контексте используемых пакетов и инструментов;

• о контексте дизайн-системы.

И вот как сейчас выглядят реальные трудозатраты на каждый уровень:

Вывод простой: эффективность ИИ-помощника напрямую зависит от того, насколько хорошо он знает ваш проект, его архитектурные особенности и правила работы с UI Kit. Простые решения, вроде структурированного AGENTS.md, быстро передают ассистенту базовый контекст — и уже этого достаточно, чтобы сэкономить десятки часов на ручных переделках. Когда же добавляется интеграция с MCP и автоматическая синхронизация кода с дизайном, ИИ-помощник становится полноценным участником команды, способным генерировать корректный, поддерживаемый код.

ИИ в разработке — это не магия, а инфраструктурная работа. Начните с малого: с одного документа и описания ключевых конвенций в проекте. А затем шаг за шагом закрывайте оставшиеся «дыры» — описывайте внутренние библиотеки, синхронизируйте дизайн и реализацию, автоматизируйте связь между системами.

А какой контекст уже передаёте своему ИИ‑помощнику вы? Делитесь своими приёмами и наблюдениями.

Больше про ИИ пишу в своём телеграм‑канале, присоединяйтесь!