AGENTS.md побеждает Skills: Vercel нашел лучший способ обучать AI-агентов документации Next.js 16

Лучший способ передать AI-агенту актуальную документацию — не навыки (skills), а компактный файл AGENTS.md. Vercel провел эксперимент с Next.js 16 и обнаружил, что AGENTS.md обеспечивает 100% прохождение тестов, тогда как навыки — лишь 79%. Проблема в том, что агенты часто игнорируют навыки, даже ес

AGENTS.md показал 100% прохождение тестов против 79% у навыков

Vercel построил два варианта документации для Next.js 16: один в виде навыка (skill), другой — в виде сжатого индекса AGENTS.md размером 8 КБ. Затем оба варианта прогнали через оценочный набор (eval suite), сфокусированный на новых API Next.js 16.

Навыки казались идеальным решением: вы упаковываете документацию в skill, агент вызывает его при работе с Next.js и получает корректный код. Чистое разделение, минимальные накладные расходы, агент загружает только то, что нужно. Существует даже каталог навыков на skills.sh. Но на практике всё пошло не так.

В 56% тестовых случаев навык ни разу не был вызван. Агент имел доступ к документации, но не использовал её. Добавление навыка не дало никакого улучшения по сравнению с базовым сценарием без документации. Даже когда в инструкцию явно добавляли указание использовать навык, максимальный результат составил 79% — и то лишь при очень подробных инструкциях. Без них навыки показывали результат не лучше, чем полное отсутствие документации.

Предыстория и контекст: почему AI-агенты отстают от реальности

Проблема устаревания знаний AI-моделей известна давно. Тренировочные данные моделей вроде GPT-4 или Claude заканчиваются на определённой дате, и новые API, выпущенные после этого срока, остаются для них неизвестными. Разработчики вынуждены либо вручную править сгенерированный код, либо использовать специальные инструменты для подгрузки актуальной документации.

Vercel, как создатель Next.js, заинтересован в том, чтобы AI-агенты правильно генерировали код для его фреймворка. В Next.js 16 появились важные нововведения: 'use cache' для кэширования данных на уровне компонентов, connection() для управления соединениями и forbidden() для обработки запрещённых действий. Ни одно из этих API не входит в обучающие данные современных моделей, поэтому без дополнительной документации агенты обречены на ошибки.

Рынок инструментов для AI-кодинга стремительно растёт. Помимо навыков от Vercel, существуют решения вроде Claude Artifacts, GitHub Copilot Chat с пользовательскими инструкциями и Cursor с правилами проекта. Vercel искал наиболее эффективный способ интеграции документации непосредственно в рабочий процесс агента.

Как работает AGENTS.md и чем он отличается от навыков?

AGENTS.md — это простой текстовый файл, который помещается в корень репозитория и содержит сжатую версию документации. В случае с Next.js 16 Vercel создал индекс размером 8 КБ, который включает ключевые описания новых API, примеры кода и ссылки на полную документацию. Агент читает этот файл при старте и использует его как контекст для генерации кода.

Навыки же — это отдельные модули, которые агент может вызвать по запросу. Они хранятся в каталоге skills.sh и подгружаются только когда агент решает, что они нужны. Теоретически это экономит токены и сохраняет чистоту промпта, но на практике агенты часто игнорируют навыки, даже если те явно доступны.

Разница в подходе фундаментальна: AGENTS.md всегда в контексте, навыки — только по вызову. Vercel выяснил, что современные AI-агенты не склонны самостоятельно инициировать вызов навыков, особенно если задача кажется простой или знакомой. Они предпочитают полагаться на свои внутренние знания, даже если те устарели.

Технические детали: сжатый индекс 8 КБ против навыков с инструкциями

Vercel провёл серию тестов с разными конфигурациями. В базовом сценарии без документации агенты правильно отвечали на вопросы о новых API лишь в 30-40% случаев. Добавление навыка без дополнительных инструкций не улучшило результат — те же 30-40%. Когда в системный промпт добавили явное указание "используй навык Next.js для вопросов по новым API", результат вырос до 79%, но всё равно не достиг 100%.

С AGENTS.md ситуация оказалась иной. Без каких-либо дополнительных инструкций агент, прочитав файл при старте, достиг 100% прохождения тестов. Все 8 КБ документации были в его контексте, и он мог обращаться к ним в любой момент. Никаких проблем с инициализацией вызова — информация всегда под рукой.

Ключевой вывод: современные AI-агенты лучше работают с пассивным контекстом, чем с активным вызовом инструментов. Они не любят "думать" о том, какой навык вызвать, особенно когда задача кажется тривиальной. AGENTS.md устраняет этот барьер, делая документацию частью рабочей среды.

Кого затронет и как: разработчики Next.js, создатели AI-инструментов и команды, внедряющие AI-кодинг

Для разработчиков Next.js 16 результаты Vercel означают простой способ улучшить качество AI-генерируемого кода: достаточно добавить в репозиторий файл AGENTS.md со сжатой документацией. Vercel уже предоставляет готовый шаблон такого файла для Next.js 16, который можно скачать и адаптировать под свой проект.

Создатели AI-инструментов для кодинга, такие как Anthropic, OpenAI, GitHub и Cursor, могут пересмотреть свои подходы к интеграции документации. Возможно, стоит сделать AGENTS.md стандартом де-факто для передачи контекстных знаний агентам, а не полагаться на механизмы вызова навыков.

Команды, внедряющие AI-кодинг в свои процессы, получают практическое руководство: не тратьте время на настройку сложных навыков, если можно просто добавить файл с документацией в репозиторий. Это особенно актуально для проектов с частыми обновлениями API, где документация быстро устаревает.

В российском и СНГ-контексте это может быть полезно для команд, использующих Next.js в продакшене — многие крупные проекты на Next.js работают в России и странах СНГ, и качество AI-генерации кода напрямую влияет на скорость разработки.

Что будет дальше: Vercel продолжит развивать AGENTS.md и, возможно, интегрирует его в платформу

Vercel планирует расширить подход AGENTS.md на другие фреймворки и библиотеки. В ближайшее время ожидается выпуск готовых AGENTS.md для популярных инструментов экосистемы Vercel, таких как Turborepo, Svelte и Nuxt. Также компания изучает возможность автоматической генерации AGENTS.md из документации проектов, размещённых на Vercel.

В более широком смысле, результаты Vercel могут повлиять на развитие стандартов взаимодействия AI-агентов с документацией. Уже сейчас сообщество обсуждает создание открытого реестра AGENTS.md для различных технологий, по аналогии с skills.sh, но с принципиально иной архитектурой — контекст вместо вызова.

Не исключено, что в будущем AGENTS.md станет обязательным файлом для проектов, ориентированных на AI-кодинг, подобно тому как README стал стандартом для документации проектов.

Итог

Эксперимент Vercel показал, что простой файл AGENTS.md весом 8 КБ эффективнее сложных навыков при обучении AI-агентов новым API. 100% прохождение тестов против 79% у навыков — убедительный аргумент в пользу пассивного контекста. Разработчикам Next.js 16 стоит немедленно добавить AGENTS.md в свои проекты, а создателям AI-инструментов — пересмотреть архитектуру передачи документации. Следите за обновлениями Vercel: возможно, AGENTS.md станет новым стандартом в AI-кодинге.