Modern Web Guidance 1.0: настройка Claude Code, Codex и Cursor

Установите Modern Web Guidance 1.0 как навык (skill) проекта и сначала проверьте его на одной задаче по фронтенду. Используйте legacy-scan для подготовки изменений с последующим ревью, а не для переписывания кода без проверки. Чтобы отключить телеметрию Modern Web Guidance, задайте DISABLE_TELEMETRY=1 до первой команды.

Что даёт Modern Web Guidance 1.0

Modern Web Guidance снабжает вашего агента рекомендациями по возможностям браузеров до того, как он начнёт писать код. Релиз 1.0, опубликованный 10 ноября 2026 года, содержит 203 руководства по конкретным задачам и охватывает 250 возможностей веб-платформы. Проект поддерживают команды Chrome, Edge, Firefox и MDN вместе с сообществом.

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

Поиск использует локальную модель эмбеддингов для сопоставления по смыслу и BM25 для ранжирования по ключевым словам. Самому поиску не нужен внешний API языковой модели или API-ключ, как указано в официальном README проекта.

Навык полезен, когда агент знает о браузерном API, но упускает детали: например, поведение переходов или резервные решения для совместимости. Вы по-прежнему определяете поддерживаемые браузеры, проверяете изменения и запускаете тесты приложения. Прежде чем применять навык ко всему репозиторию, убедитесь на одной задаче, что агент действительно следует руководству.

Как установить навык в Claude Code, Codex или Cursor

Установите навык через командную строку (CLI) на уровне проекта: этот способ подходит для всех трёх агентов. Код команды установки вызывает Vercel Skills. По состоянию на 2026-11-13 используйте Node.js 22.20 или новее: этого требует текущий установщик Skills.

Также нужны npm/npx и разрешение на загрузку необходимых пакетов. Откройте Bash в корневом каталоге проекта. Перед запуском официальной команды установки отключите телеметрию Modern Web Guidance:

export DISABLE_TELEMETRY=1
npx modern-web-guidance@latest install

В интерактивном установщике выберите Claude Code, Codex, Cursor или только те агенты, которыми пользуетесь. Для пробы в одном репозитории оставьте установку на уровне проекта. Установщик использует этот вариант по умолчанию.

После установки через CLI проверьте расположение файлов навыка и способ его явного вызова:

Агент	Файл навыка в проекте	Явный вызов
Claude Code	.claude/skills/modern-web-guidance/SKILL.md	Введите /modern-web-guidance.
Codex	.agents/skills/modern-web-guidance/SKILL.md	Используйте /skills или укажите $modern-web-guidance.
Cursor	.agents/skills/modern-web-guidance/SKILL.md	Введите / в чате Agent и выберите навык.

Пути соответствуют текущим настройкам установщика для каждого агента. Это каталоги проекта, а не кэш плагинов или пути глобальной установки.

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

Чтобы обновить навык, установленный через CLI, выполните из каталога проекта:

npx modern-web-guidance@latest update

После обновления просмотрите изменения в файлах навыка и повторите проверку получения руководства из следующего раздела. Команды используют @latest, поэтому будущее обновление может установить версию новее 1.0.

Установка через каталог плагинов — отдельный способ со своей процедурой обновления. Не подменяйте её этой инструкцией для CLI. Устройство плагинов Claude Code и управление ими разобраны в инструкции по установке, проверке и удалению плагинов.

Как проверить поиск руководств и их применение агентом

Проверьте и CLI, и то, как агент использует полученный текст. Успешная команда в терминале ещё не доказывает, что агент загрузил навык.

В Bash выполните пример с диалоговым окном из документации:

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

Команда search возвращает JSON с идентификаторами и описаниями руководств. Команда retrieve возвращает текст выбранного руководства. Если вывод большой, CLI может вместо него показать путь к сохранённому файлу; поручите агенту прочитать его целиком.

Затем вызовите установленный навык и дайте агенту задачу с чёткими границами. Запрос ниже требует сохранить фреймворк и требования к браузерам, получить руководство до правок и отчитаться о тестах:

Use the modern-web-guidance skill to add an animated modal dialog.
Keep the existing framework and browser support policy.
Retrieve the relevant guidance before editing.
Afterward, report the guide IDs, required fallbacks, and tests run.

В журнале вызовов инструментов найдите реальные команды поиска и получения руководства. В итоговом отчёте агент должен назвать руководство и объяснить, какие решения он принял на его основе. Фразы «использовал лучшие практики» для проверки недостаточно.

Руководство по анимации диалогового окна из релиза даёт конкретный критерий для ревью. Если используется сокращённая запись transition, объявление transition-behavior: allow-discrete должно идти после неё. Иначе transition сбросит значение этого свойства.

Проверьте анимацию появления и закрытия, поведение при включённом уменьшении анимации и существующие сценарии взаимодействия с диалогом.

Если команда завершается ошибкой до выдачи результатов поиска, сначала проверьте версию Node.js и разрешения на загрузку пакетов. Инструкции навыка из релиза отдельно оговаривают, что загрузка пакета и автономная работа — разные этапы. Разрешайте запуск команды для нужного пакета, а не произвольные команды через npx.

Если результаты не подходят, укажите в запросе конкретное поведение интерфейса, например «confirmation modal dialog». Не получайте неподходящее руководство ради формально успешной проверки.

Как использовать legacy-scan без автоматического переписывания кода

Запускайте legacy-scan, чтобы найти возможные участки для модернизации в репозитории или каталоге. Для правки отдельного компонента используйте поиск и получение руководства. Это разделение описано в документации по модернизации.

Для отчёта в удобном для чтения виде выполните из корня проекта:

npx modern-web-guidance@latest legacy-scan .

Для структурированного вывода, который сможет разобрать агент, используйте:

npx modern-web-guidance@latest legacy-scan . --json

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

Поручите агенту пройти четыре этапа из документации:

1. Просканировать выбранный каталог и собрать кандидатов на изменение.
2. Проверить каждое совпадение в контексте окружающего кода по правилам keepWhen/dropWhen. Отбросить ложные срабатывания, а не считать каждое совпадение обязательным к исправлению.
3. Подготовить отчёт с проверенными находками и планом правок. Получить ваше согласие до начала модернизации.
4. Внести только согласованные изменения по соответствующим руководствам, предварительно получив их текст. Запустить существующие тесты и повторно просканировать изменённые участки.

Особенно внимательно проверяйте намеренно оставленные резервные решения и код с проверками поддержки браузерных возможностей. Старая на вид реализация может оставаться необходимой для браузеров, которые поддерживает проект.

В версии 1.0 сканер охватывает примерно 20% руководств: только те, для которых есть детерминированные правила обнаружения устаревших конструкций. Это доля каталога руководств, а не процент кода в вашем проекте. Отсутствие находок не подтверждает ни полноту модернизации, ни доступность интерфейса, ни корректность приложения.

Задайте требования к браузерам и настройте .mwgrc

Явно укажите требования к совместимости и не включайте экспериментальные рекомендации без необходимости. По умолчанию навык считает, что возможности со статусом Baseline Widely available можно использовать без резервных решений.

В инструкции по настройке Baseline показано, как записать целевой уровень поддержки в AGENTS.md или CLAUDE.md. Исходите из реальных требований проекта. Не меняйте их лишь для того, чтобы принять предложенную замену.

Необязательный JSON-файл .mwgrc в корне проекта управляет доступом к экспериментальным рекомендациям. Для консервативной настройки добавьте или обновите эти поля, сохранив остальные параметры существующего файла:

{
  "allowOriginTrials": false,
  "allowVolatileFeatures": false
}

Рекомендации категории volatile относятся к возможностям, которые поддерживает только один браузерный движок. Речь о возможностях, выпущенных за последние 3 месяца или ещё проходящих стабилизацию. Руководства для них остаются в поиске, но для получения текста нужно явное разрешение.

Для рекомендаций по браузерным экспериментам Origin Trial предусмотрено отдельное разрешение.

Чтобы разрешить рекомендации для volatile-возможностей, выполните команду сами в интерактивном терминале Bash:

npx modern-web-guidance@latest set-allow-volatile-features

Для рекомендаций по Origin Trial при необходимости используйте отдельную команду:

npx modern-web-guidance@latest set-allow-origin-trials

Команды запрашивают подтверждение и устанавливают соответствующий параметр в true. Проверьте выведенный путь к конфигурации и изменённый ключ, затем повторите получение руководства.

Отказ при запуске через агента или в неинтерактивной оболочке предусмотрен намеренно. Код команды разрешения требует интерактивного терминала, которым управляет разработчик. Не просите агента обходить эту проверку.

Эти параметры открывают доступ к рекомендациям. Они не включают возможности браузера, не регистрируют сайт в Origin Trial и не расширяют требования проекта к поддержке браузеров.

Отключите телеметрию и учитывайте расходы на контекст

Отключайте телеметрию в окружении, из которого действительно запускается Modern Web Guidance, а не только в постороннем терминале. Раздел о конфиденциальности проекта перечисляет собираемые данные: число установок, имена вызывающих агентов, идентификаторы полученных руководств и поисковые запросы, сформированные агентом. Согласно этому описанию, исходные промпты пользователей не собираются.

При этом поисковые запросы могут раскрывать детали задачи. Добавьте export DISABLE_TELEMETRY=1 в файл настройки Bash, например .bashrc, и проверьте, что окружение команд агента наследует переменную. При необходимости перезапустите уже работающий агент или IDE с обновлённым окружением.

В том окружении Bash, где агент выполняет команды, проверьте значение без его вывода:

test "${DISABLE_TELEMETRY:-}" = 1

Код завершения 0 подтверждает, что в этом окружении переменная равна 1. Это не проверка сетевого трафика. Команда также не показывает настройки телеметрии у провайдера агента или других инструментов.

Автономный поиск не означает, что весь процесс работает без сети. Для загрузки пакетов нужен сетевой доступ, а телеметрия Modern Web Guidance включена, пока вы её не отключите.

В README заявлены примерные размеры пакетов: 205 tokens для modern-web-guidance и 175 tokens для chrome-extensions. Эти значения не ограничивают общий расход токенов на задачу. Тексты полученных руководств добавляются в контекст, а проверка и правки требуют дальнейшей работы агента.

Измеряйте фактический расход на типичных задачах. Не рассчитывайте экономию только по заявленному размеру навыка.

Проверяйте прирост качества на своих задачах

Результаты Google дают основание попробовать навык, но не гарантируют одинаковую долю успешных решений или экономию токенов на любой задаче. В срезе результатов из официального README за 2026-11-08 приведены такие показатели:

Агент и обозначение модели	Задачи / проверки	Без руководств	С руководствами	Прирост
claude_code / opus-5-5	215 / 1801	57%	88%	31 процентный пункт
codex_cli / gpt-6.1-sol	215 / 1795	54%	82%	28 процентных пунктов
antigravity_cli / gemini-4-argon	214 / 1673	58%	94%	36 процентных пунктов

Это доля пройденных проверок, а не доля успешно завершённых реальных проектов. Количество задач и проверок в строках различается. Поэтому таблица не позволяет ранжировать модели по результатам строго одинакового набора заданий.

Методика на странице результатов определяет долю успешных проверок как число пройденных проверок, делённое на число выполненных. Запуски, которые аварийно завершились или превысили лимит времени до оценки, исключают вместе с парными запусками.

Google построила оценку качества на своих руководствах. В разборе типичных ошибок агентов описано, как ответы сопоставляют с ожиданиями из руководств. Это результаты оценки, проведённой разработчиком инструмента, а не независимое подтверждение качества вашего приложения.

Перед внедрением сравните выполнение одной типичной задачи над компонентом с руководствами и без них. Используйте одну модель, один промпт и одинаковые требования к браузерам. Оцените поведение в браузере, регрессионные тесты, затраты времени и фактический расход токенов.

Чтобы оценить затраты, смотрите на стоимость завершённой задачи, а не только цену токенов. Оставляйте Modern Web Guidance в проекте, если он улучшает значимые для вас проверки без неприемлемого роста расходов и времени на ревью.