Yandex 360 Explicou Como Ensinar Assistentes de IA a Trabalhar com Kits UI Internos

A equipe frontend do Yandex 360 compartilhou como ensinar um assistente IA a trabalhar com um kit UI interno e sistema de design — e por que a preparação especial do repositório é necessária sem isso.

O efeito "uau" e seu lado negativo

Os primeiros experimentos com assistentes IA geralmente causam uma impressão: MVP em cinco minutos, código na primeira tentativa, parece que o futuro já está aqui. Mas quando se trata de um projeto corporativo real com bibliotecas internas e seu próprio kit UI, a ilusão desmorona. O assistente inventa componentes que já existem no sistema, ignora padrões estabelecidos e viola convenções do sistema de design.

O Yandex 360 encontrou isso sistematicamente: 90% da equipe frontend usa assistentes IA todos os dias. O problema de incompatibilidade com a infraestrutura interna não foi uma exceção, mas a regra.

O que significa um repositório AI-ready

Valery Baranov, Chefe de Tecnologia Frontend no Yandex 360, explica a raiz do problema: modelos de linguagem públicos foram treinados em dados abertos. Componentes internos, bibliotecas corporativas e convenções de projeto não chegaram lá. Isso significa que a IA precisa receber contexto explícita e sistematicamente — não através de prompts manuais cada vez.

A equipe desenvolveu vários princípios:

• Documentação estruturada de cada componente levando em conta a janela de contexto do modelo
• Arquivos de dica (`AGENTS.md`, `.cursorrules`) descrevendo arquitetura e padrões proibidos
• Exemplos explícitos — tanto corretos quanto incorretos — para cada entidade
• Metadados do kit UI chegando automaticamente ao contexto quando solicitado
• Descrição de CI/CD e convenções de código em formato legível por máquina

Sistema de design como artefato legível por máquina

Uma tarefa separada é ensinar o assistente a seguir os padrões do sistema de design. Componentes internos não chegam aos dados de treinamento do modelo, então a IA começa a alucinar: inventando APIs inexistentes ou usando padrões desatualizados.

O Yandex 360 adicionou uma camada de documentação adicional. Cada componente é descrito não apenas para desenvolvedores, mas também com modelos de linguagem em mente: erros típicos, variantes aceitáveis, combinações proibidas. Isso permite que o assistente gere código que passa na revisão de requisitos de design na primeira tentativa.

"Fizemos projetos frontend verdadeiramente AI-ready: ensinamos

assistentes a entender a estrutura de nossos repositórios, trabalhar com bibliotecas internas e até seguir padrões do sistema de design," — Valery Baranov, Yandex 360.

Perspectiva de infraestrutura do problema

O Yandex 360 lida com "frontend comum" — componentes técnicos unificados, CI/CD compartilhado, plataformas para distribuir componentes entre equipes. Isso torna a tarefa especialmente crítica: se um componente for descrito incorretamente, os assistentes cometem erros em todos os projetos que o usam.

Então a abordagem da equipe não é correções pontuais de prompts, mas trabalho sistemático com documentação e estrutura de repositório no nível da plataforma.

O que isso significa

A experiência do Yandex 360 mostra: um assistente IA não se torna uma ferramenta eficaz sem investimento em contexto. Equipes que tornarem seus repositórios e sistemas de design legíveis por máquina obterão ganhos reais de velocidade — outras continuarão gastando tempo corrigindo alucinações.