Документ AGENTS.md от Vercel обучает искусственных помощников 70 лучшим практикам использования React.

Коллега из команды платформы опубликовал ссылку во внутреннем канале Slack без каких-либо пояснений — только сырая URL и эмодзи в виде пожатия плечами. Ссылка вела на репозиторий vercel-labs/agent-skills, а именно на раздел react-best-practices. Сначала предполагалось, что это ещё одна переработанная статья с «советами по производительности React», адаптированная под тренды искусственного интеллекта. Однако это оказалось не так. На самом деле это сборник из 70 правил, разделённых на 8 категорий; Vercel утверждает, что они сформированы на основе более чем десятилетнего опыта наблюдения за тем, как производственные приложения на React и Next.js ломаются определёнными способами. Важно отметить, что этот документ предназначен в первую очередь для использования искусственным интеллектом-ассистентом по программированию, а людьми-разработчиками — лишь во вторую очередь.

Именно такой формат является сутью того, что делает это особенным, и стоит на нем остановиться перед тем, как перейти к самому содержанию правил.

Что на самом деле есть в репозитории

Для установки этой функции достаточно одной команды:

npx skills add vercel-labs/agent-skills

На самом деле это преобразуется в файл AGENTS.md — стандарт, который все чаще используется для предоставления структурированной информации о проекте инструментам для программирования (таким как Claude Code, Cursor, Codex и OpenCode, все они ищут этот файл). После его создания у вашего инструмента появляется сборник правил, на который он может опираться при написании или проверке кода, вместо того чтобы полагаться исключительно на различные учебники по React, случайно попавшие в его данные обучения.

70 правил разделены на восемь категорий, каждая из которых имеет маркер приоритета от CRITICAL до LOW. Две категории с маркером CRITICAL, как и ожидается, являются теми, на которые команда Vercel указывает как на основные причины сбоев в реальных условиях: последовательные асинхронные операции, создающие «водопады», и неконтролируемое увеличение размера пакетов. Типичное правило из категории «водопады» формулируется примерно так:

// Flagged: sequential awaits create a waterfall
async function getThreadPage(threadId) {
  const thread = await getThread(threadId)
  const author = await getAuthor(thread.authorId)
  const replies = await getReplies(threadId)
  return { thread, author, replies }
}

// Preferred: parallelize independent fetches
async function getThreadPage(threadId) {
  const [thread, replies] = await Promise.all([
    getThread(threadId),
    getReplies(threadId),
  ])
  const author = await getAuthor(thread.authorId)
  return { thread, author, replies }
}

Всё это не кажется чем-то принципиально новым, если вы занимались разработкой с React. На самом деле интересно не содержание правила — а то, что теперь оно существует в форме, которую машина может парсить и применять единообразно во всем кодовом базисе, даже в 2 часа ночи при пул-реквесте, который никто тщательно не проверял, без усталости или ускорений, которые возникают при приближении дедлайна.

Почему это отличается от инструмента линтинга

Первая реакция — задаться вопросом, не является ли это просто ESLint в другой оболочке. В некотором смысле да, но именно механизм делает его уникальным. Инструмент для проверки кода выделяет проблемы после того, как код уже существует. Такой подход направлен на влияние на код в процессе его создания, позволяя обнаружить ошибки ещё до того, как они будут введены. Если искусственный интеллект отвечает за 30–60 процентов изменений в конкретном запросе на пул-реквест (причём оценки этого показателя сильно различаются в зависимости от того, кого вы спросите в команде), то встроение правил непосредственно в процесс генерации представляет собой совершенно иной способ воздействия по сравнению с выявлением ошибок уже после их возникновения.

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

Где появляется скептицизм

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

Вторая проблема имеет более структурный характер: что произойдёт, когда количество правил вырастет с 70 до 200, или когда инструменты от конкурирующих поставщиков начнут попадать в один и тот же файл AGENTS.md и противоречить друг другу? Сейчас, при наличии единого репозитория и совершенно новой концепции, всё кажется упорядоченным и понятным. Однако спустя восемнадцать месяцев легко представить себе, что каждая фреймворк-система, каждый поставщик хостинга и каждая система дизайна захотят, чтобы их собственные инструменты были установлены. В таком случае агенту придётся справляться с кучей правил, содержащих противоречивые указания, и, возможно, не будет очевидного способа определить, какие из них должны иметь приоритет.

Тестирование на реальном кодовом базисе

Исходя скорее из любопытства, чем из ожиданий, этот инструмент был применён к среднему по размеру внутреннему панели управления, чтобы узнать, что именно он выявит. Результаты с категориями CRITICAL и HIGH оказались довольно обыденными: несколько последовательных вызовов await, которые можно было выполнить параллельно, пара клиентских компонентов, у которых не было реальной необходимости существовать в виде клиентских компонентов, и один довольно неловкий случай использования целой библиотеки обработки дат только для форматирования одного значения. Всё это не стало бы сюрпризом для тех, кто уже проводил серьёзную оптимизацию производительности кодовой базы на React. Однако бросалась в глаза скорость — агенту потребовалось примерно четыре минуты, чтобы найти и отметить всё это, в то время как человеку-рецензенту потребовалось бы гораздо больше времени, чтобы обнаружить те же проблемы, распределённые по большому pull requestу.

Именно это различие в скорости является ключевым преимуществом здесь. Сами правила не являются чем-то революционным — большинство опытных инженеров уже инстинктивно обладают этими знаниями. Изменение заключается в том, что теперь правила применяются с такой последовательностью и скоростью, которую человек-рецензент, особенно тот, кто уже проводит третью рецензию за день, просто не может поддерживать.

Недооцененное преимущество: обучение, а не только контроль

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

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

К чему это приводит

Этот инструмент в итоге был добавлен в общую конфигурацию команды, главным образом потому, что его недостатки минимальны, а преимущества — наличие агента, который прекращает написание кода в стиле «водопад» — являются разумной платой за это. Пока неясно, станет ли этот подход стандартным способом передачи рекомендаций фреймворков в AI-агенты или просто превратится в ещё один файл конфигурации, который постепенно устареет, когда новизна исчезнет, и никто не потрудится его обновить. Этот вопрос стоит рассмотреть через шесть месяцев, а не отвечать на него сейчас.

Связанные статьи

• Inside TypeScript 7's Go Rewrite: Speed Gains Without Code Changes — Узнайте, как компилятор TypeScript 7 на основе Go обеспечивает в 8–12 раз более быструю сборку, почему такая архитектурная замена эффективна и как безопасно обновлять существующие проекты.

Что такое частичная предварительная обработка и одновременная обработка: пояснение — Узнайте, как функции частичной предварительной обработки в Next.js и одновременной обработки в React устраняют проблему медленной работы приложений, позволяя фреймворкам планировать и выполнять задачи поэтапно вместо того, чтобы рассматривать процесс отрисовки как единую блокирующую операцию.