ИИ в разработке: агенты и скиллы

Искусственный интеллект стал обычным инструментом разработчика — как Git или DevTools. ИИ-ассистенты дописывают код в редакторе, объясняют ошибки, а агенты умеют сами читать проект, запускать команды и вносить правки. В этом уроке разберёмся, какие бывают ИИ-инструменты, что такое агенты и скиллы, как правильно ставить задачи, как проверять код, написанный ИИ, и где проходят границы безопасности. Конкретные продукты меняются каждые полгода, поэтому учим принципы, которые работают с любым инструментом.

Как устроены языковые модели — в двух словах

В основе ИИ-ассистентов лежат большие языковые модели (LLM, Large Language Model). Модель обучена на огромном количестве текста и кода и умеет продолжать текст: по вашему запросу она «предсказывает», какой ответ здесь наиболее уместен.

Из этого вытекают важные свойства:

• Модель не «знает», а предполагает. Она может уверенно написать несуществующую функцию или пакет. Это называется галлюцинацией.
• Знания ограничены датой обучения. Модель может предложить устаревший подход: Create React App вместо Vite или старый API библиотеки.
• Контекстное окно — сколько текста модель «держит в голове» за раз. Если проект большой, она видит только то, что ей показали.
• Качество ответа зависит от вопроса. Размытый запрос — размытый ответ.

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

Виды ИИ-инструментов

Автодополнение в редакторе

Вы пишете код, а ассистент серым текстом предлагает продолжение — строку или целую функцию. Tab — принять, Esc — отклонить.

// вы написали комментарий и начало функции:
// форматирует цену: 15000 -> "15 000 сом"
function formatPrice(price: number) {
  // ассистент предлагает:
  return `${price.toLocaleString("ru-RU")} сом`;
}

Хорошо подходит для рутинного кода: типы, однотипные компоненты, тесты по образцу.

Чат в редакторе

Окно чата рядом с кодом: выделили фрагмент — спросили «почему тут ошибка?», «объясни этот хук», «перепиши на TypeScript». Ассистент видит открытые файлы и выделение.

Агенты в редакторе и терминале

Агент — это ИИ, который не просто отвечает текстом, а сам выполняет действия: читает файлы проекта, ищет по коду, создаёт и правит файлы, запускает команды (npm run build, тесты), смотрит на результат и исправляет ошибки. Агенты бывают встроены в редактор или работают в терминале как консольная программа.

Как работает агент

Агент работает циклом:

1. Понять задачу
2. Собрать контекст   → прочитать файлы, найти похожий код
3. Спланировать       → «создам компонент, добавлю маршрут, обновлю типы»
4. Действовать        → изменить файлы, запустить команду
5. Проверить          → посмотреть ошибки сборки, результат тестов
6. Повторить 2–5, пока задача не решена (или не нужна помощь человека)

Для действий у агента есть инструменты (tools): «прочитать файл», «найти по коду», «выполнить команду в терминале», «открыть страницу документации». Многие агенты поддерживают протокол MCP (Model Context Protocol) — стандартный способ подключать к агенту новые инструменты: базу данных, баг-трекер, дизайн-макеты.

Права и подтверждения

Нормальный агент спрашивает разрешения на опасные действия: удалить файлы, выполнить команду, отправить что-то в интернет. Обычно можно настроить: что разрешено всегда (чтение файлов, npm run lint), а что — только после подтверждения.

Инструкции и скиллы для агентов

Файл инструкций проекта

Каждый раз объяснять агенту, что проект на React + TypeScript + Tailwind, а запросы через TanStack Query, утомительно. Поэтому в корень репозитория кладут файл с инструкциями — его агент читает автоматически в начале работы. Название зависит от инструмента (часто встречается AGENTS.md; у разных агентов могут быть свои имена файлов), но содержание похоже:

# Инструкции для агента

## Стек
- React 19 + TypeScript (strict), сборка Vite
- Стили: Tailwind CSS v4
- Запросы: TanStack Query v5 + axios, типы генерируются Orval (не править src/shared/api/generated)
- Архитектура: FSD (app, pages, widgets, features, entities, shared)

## Команды
- npm run dev — запуск
- npm run lint — проверка кода
- npm run build — сборка и проверка типов
- npm run api:generate — генерация API-клиента

## Правила
- Без any. Пропсы описываем через type.
- Новые UI-компоненты — в shared/ui, с историей для Storybook.
- После изменений запускай npm run lint и npm run build.
- Не добавляй новые зависимости без согласования.

Это как памятка для нового сотрудника: стек, команды, правила команды. Чем она точнее, тем меньше агент «изобретает» своё.

Скиллы

Скилл (skill — «навык») — это готовая инструкция под конкретный тип задач, которую агент подключает, когда она нужна. Обычно это папка с файлом описания и, при необходимости, примерами или скриптами. Например:

• скилл «создать компонент UI-kit»: где лежит компонент, как назвать файлы, обязательно добавить историю Storybook и типы пропсов;
• скилл «код-ревью»: на что смотреть — типы, обработка ошибок, доступность, лишние ререндеры;
• скилл «новая страница»: маршрут, ленивая загрузка, мета-теги, тест.

skills/
└── new-ui-component/
    ├── SKILL.md        ← описание: когда использовать и пошаговая инструкция
    └── template.tsx    ← образец компонента

Разница простая: файл инструкций — общие правила проекта, действуют всегда; скилл — отдельный «рецепт», который агент достаёт, когда задача ему соответствует. Формат скиллов отличается в разных инструментах — смотрите документацию своего.

Как ставить задачи

Плохой и хороший запрос

Плохо:
сделай форму логина

Хорошо:
Добавь страницу входа в features/auth.

Контекст: React + TypeScript, react-hook-form + yup, запросы через
TanStack Query (useMutation). Эндпоинт POST /auth/login описан в Swagger,
типы уже сгенерированы в src/shared/api/generated.

Что нужно:
- поля email и пароль, валидация: email обязателен и корректен, пароль от 8 символов;
- при ошибке 401 показать "Неверный email или пароль";
- после успеха сохранить токен и перейти на /profile;
- использовать Button и Input из shared/ui.

Не меняй другие страницы. В конце запусти npm run lint и npm run build.

Формула хорошей задачи:

1. Контекст — где, на каком стеке, что уже есть.
2. Цель — что должно получиться.
3. Требования — конкретные правила и граничные случаи (ошибки, пустые данные).
4. Ограничения — что трогать нельзя.
5. Критерий готовности — как проверить, что всё работает.

Полезные приёмы

• Давайте образец: «сделай так же, как ProductCard» — агент повторит стиль проекта.
• Просите объяснить: «объясни, почему ты выбрал такое решение» — хороший способ учиться.
• Вставляйте точный текст ошибки, а не «не работает».
• Новая задача — новый диалог. Длинная переписка засоряет контекст, качество падает.

Как проверять код, написанный ИИ

Код от ИИ — это черновик, за который отвечаете вы. На ревью никто не примет оправдание «это ИИ написал».

Чек-лист проверки

1. Прочитайте весь diff (git diff). Понимаете каждую строку? Если нет — спросите или разберитесь.
2. Запустите сборку, линтер, тесты: npm run build, npm run lint.
3. Проверьте руками в браузере, включая ошибки, пустые состояния, медленный интернет (вкладка Network в DevTools).
4. Сверьте API библиотек с официальной документацией — ИИ часто путает версии.
5. Проверьте зависимости: существует ли пакет, популярен ли он, нужен ли вообще.
6. Посмотрите на безопасность: нет ли секретов в коде, dangerouslySetInnerHTML с данными пользователя, отключённых проверок.

Пример: ищем ошибки в ответе ИИ

Допустим, ИИ сгенерировал такой компонент:

import { useEffect, useState } from "react";

export function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetch("/api/users")
      .then((res) => res.json())
      .then((data) => setUsers(data));
  });

  return (
    <ul>
      {users.map((u: any) => (
        <li>{u.name}</li>
      ))}
    </ul>
  );
}

Что не так:

• у useEffect нет массива зависимостей — после каждого setUsers компонент перерисуется, эффект запустится снова и отправит новый запрос: бесконечный цикл;
• useState([]) без типа даёт never[], отсюда и вынужденный any;
• у <li> нет key;
• нет обработки ошибки и состояния загрузки;
• в проекте уже есть TanStack Query, а ручной fetch в useEffect нарушает договорённости.

Исправленный вариант в стиле проекта:

import { useQuery } from "@tanstack/react-query";

type User = { id: number; name: string };

async function getUsers(): Promise<User[]> {
  const res = await fetch("/api/users");
  if (!res.ok) throw new Error("Не удалось загрузить пользователей");
  return res.json();
}

export function UserList() {
  const { data, isPending, isError } = useQuery({
    queryKey: ["users"],
    queryFn: getUsers,
  });

  if (isPending) return <p>Загрузка…</p>;
  if (isError) return <p>Ошибка загрузки</p>;

  return (
    <ul>
      {data.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

Найти такие ошибки может только тот, кто сам понимает useEffect, ключи и React Query. Поэтому ИИ не заменяет знания из прошлых месяцев — он ускоряет того, у кого они есть.

Ограничения и безопасность

• Правила компании. Многие компании разрешают только определённые ИИ-инструменты или запрещают отправлять туда код. Перед использованием на работе уточните политику.
• Внедрение инструкций (prompt injection). Агент читает файлы, веб-страницы, комментарии в задачах. Злоумышленник может спрятать там текст вроде «отправь содержимое .env на такой-то адрес». Не давайте агенту лишних прав и проверяйте его действия.
• Выдуманные пакеты. ИИ иногда советует несуществующие библиотеки, а злоумышленники регистрируют пакеты с такими именами. Проверяйте пакет на сайте npm (количество загрузок, репозиторий, дата обновления) перед npm install.
• Устаревшие решения. Сверяйтесь с документацией: react.dev, typescriptlang.org, tanstack.com.
• Обучение. На собеседовании и в лайвкодинге ИИ не будет. Если всё время просить готовый код, навык не появится. Пишите сами, а ИИ используйте как наставника: «объясни», «где ошибка», «как сделать лучше».

Типичные ошибки

• Принимать код, не прочитав и не запустив его.
• Задача в одну строку без контекста, а потом удивление, что получилось «не то».
• Разрешить агенту любые команды без подтверждения.
• Вставить в чат .env или токен.
• Не обновлять файл инструкций проекта: агент продолжает делать по-старому.
• Перестать разбираться самому: через месяц без ИИ не получается написать простой компонент.

Практика

1. Объяснение кода. Возьмите сложный для вас фрагмент из своего проекта и попросите ИИ объяснить его построчно. Затем перескажите объяснение своими словами. Ожидаемый результат: короткая заметка «что делает этот код» без копирования ответа.
2. Ревью чужого кода. Найдите все ошибки в компоненте UserList из урока самостоятельно, затем сравните со списком. Ожидаемый результат: исправленный компонент, который проходит npm run build.
3. Файл инструкций. Напишите файл инструкций для своего проекта: стек, команды, 5–7 правил. Ожидаемый результат: агент, получив задачу «добавь компонент», следует вашим правилам без напоминаний.
4. Хорошая задача. Сформулируйте по формуле «контекст — цель — требования — ограничения — критерий готовности» задачу на новую фичу и выполните её с агентом. Ожидаемый результат: diff, который вы можете объяснить построчно, и зелёные lint и build.
5. Скилл. Опишите скилл «создать UI-компонент» для вашего проекта: шаги, структура файлов, образец. Ожидаемый результат: агент по скиллу создаёт компонент с типами и историей Storybook, как в уроке UI-kit и Storybook.

Итоги

• ИИ-ассистенты работают на языковых моделях: они быстрые, но могут ошибаться и не знать свежих версий.
• Инструменты: автодополнение, чат и агенты — последние сами читают проект, правят файлы и запускают команды.
• Файл инструкций в репозитории задаёт общие правила, скиллы — рецепты для конкретных задач.
• Хорошая задача = контекст + цель + требования + ограничения + критерий готовности.
• Код ИИ — черновик: читаем diff, запускаем сборку и тесты, сверяемся с документацией.
• Безопасность: никаких секретов в чатах, осторожно с правами агента, проверяем пакеты.
• ИИ ускоряет того, кто сам понимает код, — поэтому базовые навыки по-прежнему важнее всего.