本文へ移動
AI 活用

AI が古い WEB の書き方をする理由と直し方。Modern Web Guidance と AGENTS.md で Baseline を守らせる

公開 読了まで 約12分

( この記事の要点 )

  1. AI が古い書き方をするのは、学んだコードの偏りと、プロジェクトの対応範囲を知らないことが主な理由
  2. Modern Web Guidance のガイドで新しい書き方を渡し、AGENTS.md に Baseline の目標と自社の部品の優先順位を書く
  3. Baseline の lint は網として使う。ツールごとにデータが違うので、採用する機能は MDN などで人が確かめる

AI に「モーダルを作って」と頼むと、div を重ねて JavaScript でフォーカスと Esc キーを自前で扱うコードが返ってくる。<dialog> で書けば済むのに、とレビューで直す。そんな手戻りが毎週続いているなら、AI への頼み方より先に、チームの「前提」を AI に渡せていないのかもしれません。

2026年11月10日、Chrome チームはコーディングエージェント向けのガイダンス集「Modern Web Guidance」の 1.0 を公開しました。Firefox と Edge のチームも加わったと発表されています。この記事では、これをきっかけに、AI が古い書き方をする理由と、どこまで新しい機能を使ってよいかを AI に伝え、lint とレビューで確かめるチームの進め方をまとめます。道具が変わっても使える部分を中心に書きます。

AI が古い書き方をする理由

AI のモデルは、過去に書かれた大量のコードから学んでいます。WEB の世界では、<dialog> や Popover API、:has() が使えるようになる前のコードのほうが、ずっと多く残っています。そのため、何も指示しなければ「よく見かける書き方」、つまり少し前の書き方に寄りがちです。

もう1つは、AI が「このプロジェクトはどのブラウザまで対応するのか」を知らないことです。対応の範囲が分からなければ、安全側に倒して古い書き方とライブラリを選ぶか、逆に一部のブラウザでしか動かない機能を混ぜてしまいます。どちらも、AI の能力というより、前提が伝わっていないことが原因です。

直す順番は次のとおりです。

  1. 新しい機能の正しい使い方を AI に渡す(ガイダンス)
  2. どこまで使ってよいかを、プロジェクトの指示ファイルに書く(Baseline の目標)
  3. 書かれたコードを lint とレビューで確かめる
3つの層の図。「書く前」に「1 ガイダンス:新しい書き方を渡す」「2 指示ファイル:Baseline の目標を書く」。点線の区切りに「AI がコードを書く」。「書いた後」に「3 lint とレビュー:書かれたコードを確かめる」。
AI に新しい書き方を使わせる3つの層。書く前にガイダンスと指示ファイルで前提を渡し、書いた後に lint とレビューで確かめます。

Modern Web Guidance 1.0 の中身(2026年11月時点)

変わりやすい情報なので、この節にまとめます。

  • 何か:公式ドキュメントでは「WEB プラットフォームの専門知識、ベストプラクティス、ブラウザの互換性データをコーディングエージェントに組み込むスキルのセット」と説明されています。MCP サーバーではなく、エージェントが必要なときに読み込む「スキル」の形です。
  • 状態:2026年5月にプレビューとして出たあと、11月10日に 1.0(安定版)になりました。1.0 の発表では、Firefox と Edge が Chrome に加わり、ブラウザをまたいだ取り組みになりつつあると書かれています。
  • 中身:200 以上のガイド。ダイアログやポップオーバーのアニメーション、フォームの自動入力、パスキーなどの使い方が、Baseline の互換性データと、対応していないブラウザへの代わりの書き方つきで入っています。
  • 入れ方:スキルに対応したエージェントなら、npx modern-web-guidance@latest install が推奨されています。Claude Code ではプラグインとしても入れられます。
# 推奨(スキルに対応したエージェントなら)
npx modern-web-guidance@latest install

# Claude Code のプラグインとして
claude plugin marketplace add GoogleChrome/modern-web-guidance
claude plugin install modern-web-guidance@googlechrome
  • 既定の範囲:Baseline の目標を決めずに入れると、「Baseline Widely available」が既定になります。
  • 実験的な機能:1つのブラウザエンジンにしか実装されていない機能(volatile features)は、set-allow-volatile-features で許可したときだけ使われます。
  • 古いコードの点検:既存のコードを調べる仕組み(modernization workflow)は、1.0 では静的解析で「限られたパターン」だけを確かめる、と発表に書かれています。これだけで古い書き方がすべて見つかるわけではありません。
  • ライセンス:配布用のリポジトリ(GoogleChrome/modern-web-guidance)の README では、コードは Apache License 2.0、ガイドは CC BY 4.0 です。

公式ドキュメントにも「結果は、プロジェクトの要件・モデル・プロンプト・使うエージェントによって変わる」とあります。入れれば終わりではなく、次の2つの層とセットで使います。

AGENTS.md・CLAUDE.md に Baseline の目標を一文で書く

Baseline は、主要なブラウザ(Chrome のデスクトップ版と Android 版、Edge、Firefox のデスクトップ版と Android 版、Safari の macOS 版と iOS 版)の対応状況を表す呼び方です。

段階 意味
Limited まだ一部のブラウザでしか使えない
Newly available すべての主要なブラウザの最新版で使える
Widely available Newly available になってから 30か月たった

「Baseline 2024」のように、Newly available になった年で呼ぶこともできます。

Baseline の段階を時間の順に並べた図。「Limited:一部のブラウザだけ」の例は closedby と appearance: base-select。「Newly available:主要ブラウザの最新版」の例は popover。30本の目盛りの区間に「30か月」。「Widely available」の例は <dialog> と :has()。
Baseline の段階と機能の例。状態は web-features 3.47.0 時点で、本文の表と同じです。

Modern Web Guidance の公式ドキュメントでは、AGENTS.md か CLAUDE.md に目標を書く例が示されています。

This project's Baseline target is Baseline 2024.

目標の書き方は、この一文だけです。チームでは、この下に「目標より新しい機能を使うときは、対応していないブラウザ向けの代わりの書き方を添える」のような自社のルールを足しておくと、レビューの基準とそろいます。

目標そのものの決め方(お客様との合意、browserslist への書き方)は、以前の記事「対応ブラウザの決め方」にまとめました。ここでは、決めた目標を AI に読ませる置き場所を整理します。

ツール 読むファイル メモ
AGENTS.md に対応するエージェント リポジトリの AGENTS.md 編集しているファイルに一番近い AGENTS.md が優先
Claude Code CLAUDE.md(または .claude/CLAUDE.md) AGENTS.md は読まない。CLAUDE.md に @AGENTS.md と書けば取り込める
GitHub Copilot .github/copilot-instructions.md、AGENTS.md など どれを読むかは機能と環境ごとに違う。GitHub の対応表で確かめる
上に「AGENTS.md」(正本)、中身は「Baseline の目標」「自社の部品の優先順位」。左下の「CLAUDE.md」(中身は @AGENTS.md、Claude Code)から実線の矢印「取り込む」。右下の「.github/copilot-instructions.md」(中身は「目標の一文」、GitHub Copilot)から点線の矢印「一文だけ写す」。
AGENTS.md を正本にし、CLAUDE.md は @AGENTS.md で取り込みます。Copilot の指示ファイルにも Baseline の目標の一文だけ書いておきます。

おすすめは、AGENTS.md を正本にして、CLAUDE.md には @AGENTS.md の一行と Claude Code だけの設定を書く形です。GitHub の対応表では、Copilot が AGENTS.md を読むかどうかは機能と環境(GitHub.com、VS Code など)ごとに違います。.github/copilot-instructions.md にも Baseline の目標の一文だけは書いておくと、ずれが起きにくくなります。

自社のコンポーネントとの優先順位も書く

制作会社やプロダクトのチームには、すでにモーダルやフォームの部品があることが多いはずです。そのままにすると、AI がガイダンスに従って、自社の部品を <dialog> や素の <input> に置き換えてしまうことがあります。

Chrome のブログで紹介された note 株式会社の事例では、AGENTS.md に「Modern Web Guidance が勧めるからといって、使える自社のコンポーネントを素の HTML 要素に置き換えない」「食い違うときは自社のコンポーネントを優先する」と書いています。チームでも、次の順番を一言で書いておくと迷いが減ります。

## 優先順位
1. このリポジトリの components/ にある部品
2. Modern Web Guidance のガイド
3. それ以外の一般的な書き方
部品の中身を直すときは、2 に従って書き換えてよい。

lint で網を張り、結果をうのみにしない

指示を書いても、AI が守るとは限りません。そこで、Baseline の範囲を外れた機能を lint で見つけます。CSS は ESLint 公式の @eslint/css、HTML は @html-eslint/eslint-plugin に、どちらも use-baseline というルールがあります。

// eslint.config.js(ESLint 9.39.5 と 10.15.0、@eslint/css 2.0.1、@html-eslint/eslint-plugin 0.68.0 で確認)
import css from "@eslint/css";
import html from "@html-eslint/eslint-plugin";
import htmlParser from "@html-eslint/parser";

export default [
  {
    files: ["**/*.css"],
    plugins: { css },
    language: "css/css",
    rules: { "css/use-baseline": ["warn", { available: "widely" }] },
  },
  {
    files: ["**/*.html"],
    plugins: { "@html-eslint": html },
    languageOptions: { parser: htmlParser },
    rules: { "@html-eslint/use-baseline": ["warn", { available: "widely" }] },
  },
];

available には "widely"・"newly"・年(2024 など)を書けます。手元(Node.js 22.23.5)で、新しめの機能を並べたファイルに試した結果が次の表です。比べるために、web-features 3.47.0(Baseline のデータの元)の状態を並べました。

書いたもの web-features の状態 "widely" の指摘
:has()、CSS ネスト Widely なし
@starting-style Newly あり
field-sizing Newly あり
position-area(アンカー配置) Newly(2026年1月)※アンカー配置の機能全体は Limited あり
appearance: base-select Limited あり
<dialog closedby> Limited あり
commandfor / command Newly あり
popover 属性 Newly(2025年1月) なし

ほとんどは期待どおりですが、popover 属性は指摘されませんでした。@html-eslint 0.68.0 が持つデータでは、この属性が Widely available(年は 2024)として扱われていたためです。また、同じ HTML のルールを年(2024)で指定すると、Limited の closedby も指摘されませんでした。ルールごとに使うデータと判断の細かさが違う、ということです。

そのため、lint は「見落としを減らす網」として使い、判断は人がします。

  • ルールは warn で入れ、版を固定して、更新するときに結果の差を見る
  • 指摘が出なくても、新しく採用する機能は MDN か webstatus.dev で状態を一度確かめる
  • 年で指定するより、まずは "widely" か "newly" で始める

レビューで見るところ

AI が書いたプルリクエストでは、次の5つを確かめます。

  • 自前で組んでいる UI(モーダル、ツールチップ、開閉)に、使える HTML の要素や属性がないか
  • Baseline の目標より新しい機能に、代わりの書き方(@supports や機能の検出)が添えてあるか
  • 自社のコンポーネントを、勝手に素の要素へ置き換えていないか
  • lint の警告を、無効化のコメントで消していないか
  • 指示ファイル(AGENTS.md・CLAUDE.md)自体を書き換えていないか。書き換えていたら、それも差分としてレビューする

まとめ

  • AI が古い書き方をするのは、学んだコードの偏りと、プロジェクトの対応範囲を知らないことが主な理由です。
  • Modern Web Guidance のようなガイダンスで新しい書き方を渡し、指示ファイルに Baseline の目標と自社の部品の優先順位を書きます。
  • lint は網として使い、ツールごとのデータの違いを前提に、採用する機能は人が確かめます。

まずは、AGENTS.md に Baseline の目標を一文書くところから始めてみてください。MODS BASE でも、制作の現場でこの進め方を試しています。

( Written by )

MODS BASE

MODS BASEは、長野県上伊那郡辰野町を拠点に、WEB 制作、WEB 集客の運用代行、UI/UX デザイン・プロダクト開発、ブランディング・グラフィック、AI 導入支援を手がけるデザイン・開発スタジオです。全国のお客様にオンラインで対応しています。

( Related service )

WEB 制作

何を伝え、どう動いてもらうか。UX の設計から考えるホームページ制作。

( Related )

関連記事

( Contact )

Let’s talk.

まだ決まっていなくても大丈夫です。気になっていることから、気軽にお聞かせください。