Yandex 360 explica como ensinar um assistente de IA a trabalhar com um UI kit interno

A equipe de frontend do Yandex 360 explicou como ensinar um assistente de IA a trabalhar com um UI kit interno e um design system, e por que isso é impossível sem uma preparação especial do repositório.

O efeito "uau" e o outro lado da moeda

Os primeiros experimentos com assistentes de IA costumam impressionar: um MVP em cinco minutos, código de primeira, e parece que o futuro já chegou. Mas quando se trata de um projeto corporativo real, com bibliotecas internas e um UI kit próprio, a ilusão desmorona. O assistente inventa componentes que já existem no sistema, ignora os padrões adotados e viola as convenções do design system.

No Yandex 360, a equipe esbarrou nisso de forma sistemática: 90% dos desenvolvedores de frontend usam assistentes de IA todos os dias. O problema de incompatibilidade com a infraestrutura interna se mostrou a regra, não a exceção.

O que significa um repositório AI-ready

Valeri Baranov, líder de tecnologias de frontend no Yandex 360, explica a raiz do problema: os modelos de linguagem públicos foram treinados com dados abertos. Componentes internos, bibliotecas corporativas e convenções de projeto não entraram nesse treinamento. Portanto, é preciso passar o contexto à IA de forma explícita e sistemática, e não por dicas manuais a cada vez.

A equipe definiu alguns princípios:

• Documentação estruturada de cada componente, levando em conta a janela de contexto do modelo
• Arquivos de dicas (`AGENTS.md`, `.cursorrules`) com a descrição da arquitetura e dos padrões proibidos
• Exemplos explícitos, tanto corretos quanto incorretos, para cada entidade
• Metadados do UI kit que entram automaticamente no contexto durante a requisição
• Descrição do CI/CD e das convenções de código em formato legível por máquina

O design system como artefato legível por máquina

Outra tarefa é ensinar o assistente a seguir os padrões do design system. Os componentes internos não estão nos dados de treinamento dos modelos, então a IA passa a alucinar: inventa uma API inexistente ou usa padrões obsoletos.

No Yandex 360, foi adicionada uma camada extra de documentação. Cada componente é descrito não só para o desenvolvedor, mas também pensando no modelo de linguagem: erros típicos, variantes permitidas, combinações proibidas. Isso permite que o assistente gere código que passa de primeira na revisão dos requisitos de design.

"Tornamos os projetos de frontend realmente AI-ready: ensinamos os

assistentes a entender a estrutura dos nossos repositórios, a trabalhar com bibliotecas internas e até a seguir os padrões do design system", diz Valeri Baranov, do Yandex 360.

A visão de infraestrutura do problema

O Yandex 360 cuida do "frontend comum": componentes técnicos unificados, CI/CD compartilhado e plataformas de distribuição de componentes entre equipes. Isso torna a tarefa especialmente crítica: se um componente é descrito de forma errada, os assistentes erram em todos os projetos que o usam.

Por isso, a abordagem da equipe não é ajustar prompts pontualmente, mas fazer um trabalho sistemático na documentação e na estrutura do repositório em toda a plataforma.

O que isso significa

A experiência do Yandex 360 mostra que um assistente de IA não se torna uma ferramenta eficaz sem investimento em contexto. As equipes que tornarem seus repositórios e design systems legíveis por máquina terão um ganho real de velocidade; as demais continuarão gastando tempo corrigindo alucinações.