AGENTS.md против «skills»: простой файл, который дает 100% успеха ИИ-агентам

AGENTS.md против «skills»: простой файл, который дает 100% успеха ИИ-агентам

Vercel проверил, как лучше “докармливать” кодинг-агентов актуальными знаниями о фреймворке, и победила максимально простая идея - один Markdown-файл в корне проекта.

Проблема: актуальность знаний модели быстро устаревает, и при выходе новых API (например, в Next.js) агент начинает генерировать неверный код или тянет старые паттерны.

Vercel сравнил два подхода: “skills” (агент сам должен вызвать пакет знаний/доков) и AGENTS.md (постоянный контекст, доступный агенту на каждом шаге).

Цифры из тестов

- Skills не вызывались в 56% кейсов, хотя документация была доступна.

- Базовый результат без доков - 53% pass rate.

- Skills “по умолчанию” дали те же 53% (то есть 0 улучшения).

- Skills с явной инструкцией “сначала изучи проект, потом вызови skill” поднялись до 79%, но формулировки оказались хрупкими.

- AGENTS.md с сжатым индексом документации дал 100% pass rate; индекс ужали с ~40KB до ~8KB без потери результата.

Почему “пассивный контекст” сработал лучше

- Нет точки принятия решения (“надо ли мне вызвать skill?”) - информация уже доступна.

- Контекст стабильно попадает в системные инструкции на каждом шаге, без асинхронной загрузки и “порядка вызовов”.

Готовый индекс актуальной документации в виде правил агента для проектов на Next.js

Запустить команду: npx @next/codemod@canary agents-md

Команда определяет версию Next.js, скачивает подходящую документацию в .next-docs/, добавляет сжатый индекс в AGENTS.md.

Статья в оригинале есть тут vercel.com