Modern Web Guidance Source: как Google готовит и калибрует скиллы по современному вебу для кодинг-агентов

Modern Web Guidance — это набор скиллов, которые встраивают в кодинг-агентов экспертизу по веб-платформе: знание современных API, лучшие практики и данные о совместимости браузеров. Задача простая — уводить агентов от легаси-паттернов и заставлять их пользоваться тем, что веб-платформа уже умеет из коробки.

Этот репозиторий — исходники проекта. Он содержит код и документацию для трёх вещей: написания гайдов, их калибровки и оценки их пользы. Готовые скиллы публикуются в отдельном репозитории GoogleChrome/modern-web-guidance, откуда их удобно устанавливать. Проект развивают команда Google Chrome, команда Microsoft Edge и сообщество веб-разработчиков. Сейчас это превью-релиз: контент активно дополняется, а обратная связь и правки приветствуются прямо в исходном репозитории.

Зачем это нужно

Кодинг-агенты часто генерируют устаревший код, потому что обучающие данные LLM переполнены легаси. Вместо нативного решения на платформе агент рисует раздутый JavaScript. Даже если модель знает, что API существует, ей не хватает плотных примеров из реальной практики, чтобы выдать продакшен-код.

Modern Web Guidance закрывает этот пробел. CLI скилла возвращает в контекст агента короткие гайды, написанные экспертами. Каждый гайд сфокусирован на одной из трёх вещей:

• Современные API браузера — модели чаще всего неправильно используют именно их структуру.
• Производительность и доступность — приоритет платформенным API, которые оптимизирует сам браузер и в которых уже встроена поддержка скринридеров и клавиатуры.
• Ответственные фолбэки — лёгкие запасные варианты вместо тяжёлых полифиллов и старых библиотек.

Что внутри

Покрытие тянется от возможностей платформы нескольких лет давности до самого передового края. На текущий момент это:

• 232 возможности веб-платформы: 128 в CSS и вёрстке, 36 в HTML и DOM, 68 в JavaScript и API.
• 186 сценариев использования из реальной разработки: гайды по доступности, встроенному AI, CSS, формам, HTML, JavaScript, производительности и UI-компонентам.

Направления охвата хорошо видны по шести дисциплинам: плавные визуальные состояния (View Transitions, анимации входа и выхода), современная вёрстка (container queries, subgrid, цветовое пространство oklch), производительность (предзагрузка, диагностика INP, планирование через scheduler.yield), нативные компоненты интерфейса (Popover API, <dialog>, Anchor Positioning, валидация через :user-invalid), доступность и встроенный в браузер AI (локальный перевод, суммаризация, определение языка).

Пример типового гайда — navigation-drawer: пошаговая сборка навигационной панели на современных возможностях платформы.

Авторы специально следят за экономией токенов. Через эвалы они вычищают тривиальный контент, который модели и так знают, и оставляют только то, что реально меняет поведение агента.

Установка

Основной способ — интерактивный мастер установки:

npx modern-web-guidance@latest install

Попробовать без установки тоже можно:

# Поиск по гайдам
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

# Получить гайд по идентификатору
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

Есть и альтернативные каналы установки под конкретные агенты и инструменты:

Обновление после установки через npx — команда npx modern-web-guidance@latest update. Для плагинов обновление делается средствами самого агента.

Набор скиллов можно кастомизировать флагом --choose. Доступны два пака: основной modern-web-guidance (примерно 234 токена — про API, вёрстку и производительность) и chrome-extensions (примерно 181 токен — про Manifest V3, фоновые воркеры и публикацию в Chrome Web Store).

Как проверяют, что гайды работают

Ключевая особенность проекта — эвал-харнесс. Каждый гайд эмпирически проверен и постоянно перекалиброван. Конвейер замкнутый:

1. Эксперт пишет гайд и эталонную демку.
2. Из них автоматически генерируются Playwright-проверки и страница с антипримером.
3. Калибровочная петля: грейдер обязан проходить эталон на 100% и обязан падать на антипримере тоже на 100%. Если нет — агент сам правит тесты.
4. Сквозные прогоны: кодинг-агенты решают одни и те же задачи с гайдами и без них, результаты сравнивают.

Задачи для прогонов сформулированы как реальные запросы разработчика, например «сделай, чтобы картинки грузились быстрее». Названия API в промптах не звучат — так проверяется, сможет ли агент сам найти нужный гайд.

Метрики две. «Возможность» — это 100% минус доля успеха без руководства: если она мала, модели и так справляются. «Прирост» — разница между прогонами с гайдами и без них; именно его максимизируют, пересматривая гайды.

Свежий срез результатов: Claude Code на sonnet-5-5 вырос с 56% до 90% (+34 п.п.), Antigravity CLI на gemini-4-argon — с 65% до 95% (+30 п.п.), Codex CLI на gpt-6.1-sol — с 58% до 85% (+27 п.п.). Каждая строка таблицы — около 170 задач и свыше 1400 проверок.

Телеметрия

CLI собирает анонимную статистику: число установок, имя агента, идентификаторы полученных гайдов и поисковые запросы, которые агент отправил в CLI. Сырые промпты пользователей не собираются. Полный список собираемых данных открыт в файле modern-web.ts.

Чтобы отключить телеметрию, достаточно переменной окружения:

export DISABLE_TELEMETRY=1

Лицензия и участие

Код репозитория распространяется под Apache License 2.0. Содержимое гайдов в каталоге guides/ — под Creative Commons Attribution 4.0 (CC-BY 4.0). Часть документации основана на MDN Web Docs и спецификациях W3C, WHATWG и IETF.

Проект принимает вклад во всё: в гайды, в эвал-кейсы, в инфраструктуру оценки. Как участвовать, описано в CONTRIBUTING.md. Публичный репозиторий modern-web-guidance — это чистая точка публикации для установки скиллов; вся работа идёт в исходном репозитории.