# Notes on Chrome's Modern Web Guidance for coding agents

Part of: [Technical Documentation](https://ninadpathak.com/articles/technical-documentation/)

Chrome shipped more than 200 guides written for coding agents. I think its rule of cutting what the model already knows is worth copying, a plain Markdown index should come before the npm install, and it's fair to ask who decides what every agent writes by default.

Canonical: https://ninadpathak.com/articles/chrome-modern-web-guidance-notes/

By Ninad Pathak (https://ninadpathak.com/about/). Published 2026-11-17, updated 2026-11-18.

On November 10 a member of the Chrome team posted [Modern Web Guidance](https://github.com/GoogleChrome/modern-web-guidance) to [Hacker News](https://news.ycombinator.com/item?id=50443812): more than 200 guides, shipped in collaboration with Firefox, Edge and MDN, that tell a coding agent to use what browsers now do natively. The guides are written for a model to read, not a person.

I read the project as [technical documentation](https://ninadpathak.com/articles/technical-documentation/) with a new kind of reader, and I think its guides are tightly edited in a way human docs should copy. I also think the project leads with the wrong way to get the guides, an npm install where a plain web page would do.

## The editing is the part to copy

The first thing I'd take from Modern Web Guidance is its rule about what to leave out of a guide. The README says the team runs evals so it can "prune lowest-common-denominator content that models already know".

Cutting what the reader already knows is the right standard, and it applies to human readers as much as to models. I argued for the same standard, with expert human readers in mind, in [the case for shorter documentation](https://ninadpathak.com/articles/shorter-documentation/).

The one guide I opened, on building a navigation drawer, follows that rule. The guide says which approach to use and why it beats animating with JavaScript, and it never stops to explain what a dialog element is.

The navigation drawer guide also tells the agent what to assume when the user's request doesn't specify a detail. I'd add a line like that to human documentation as well, because two readers who each have to guess a default can guess differently.

## They measured it, with their own ruler

I'm more impressed that the README publishes a measurement of its guides than I am by the figure. Its table of runs with and without the guides shows Claude Code on Opus 5.5 going from 57% of checks passed to 88% on November 8, over 215 tasks.

The Chrome team wrote the guides, the tasks and the graders, so I read 88% against 57% as a sign that the guides help, and I wouldn't quote the 31-point gain as their effect. A commenter in the thread ran the project's legacy scan on their own code and it found only two issues, and a maintainer replied that the scan covers about a fifth of the guides so far.

The legacy scan checks existing code and the eval table checks newly generated code, and I haven't run either one myself. Even so, I can't name many docs teams that publish a table of pass rates with and without their docs.

## The front door is where I disagree

The README offers the guides first as an agent skill installed with an npm command, and I think a web page should come first. Documentation should be readable by a person or an agent that has installed nothing.

The guides can be read without installing anything, to be fair. The launch post links readable versions on Chrome's developer site, and the README links every guide's Markdown file.

Simon Willison [asked in the thread](https://news.ycombinator.com/item?id=50444594) for one more step beyond readable pages: a plain Markdown index on a public URL, written to be searched with grep, so any agent that can make an HTTP request finds the right guide. Paul Irish of the Chrome team replied "We'll make this happen", and added that the index costs too many tokens for regular use.

So my disagreement is only with what the README presents first, and Irish's reply to Willison has made it smaller than it was on launch day. I'd still put the Markdown index at the top of the README, for the occasional users Irish agreed it suits, and present the npm install as the route for agents that read the guides on every task.

Installing the tool also has a privacy cost that fetching a web page doesn't have. The README says the command-line tool sends Google anonymous usage data, including the search queries an agent generates, and says that setting `DISABLE_TELEMETRY=1` turns it off.

An index file plus one Markdown page per guide is also the shape agents already request from docs sites, going by the server logs in [my notes on Fern's agent traffic report](https://ninadpathak.com/articles/agents-reading-docs/).

## Who writes the agent's defaults

An objection in the thread stayed with me: Chrome already has a great deal of influence over the web, and these guides would let it steer the code that everyone's coding agent writes. I think that worry is fair, and I think it applies to anyone who writes docs for agents, not only to Chrome.

The project's answer is that four browser and documentation teams steward it and that its guides take their browser-support data from the Baseline project. Shared stewardship answers part of the worry, though a Chrome engineer said in the same thread that Mozilla had joined only in the last few weeks.

Whoever writes the page an agent reads is setting a default for every codebase that agent works on. Documentation has always set defaults this way, one developer at a time over months, and an agent applies the same default within seconds of fetching the page.

The post called the guides hand-crafted, which is the word Ghostty used for its release notes.

I said in [my thoughts on that label](https://ninadpathak.com/articles/written-by-a-human/) that "hand-crafted" was losing its meaning as agents became the readers. Here the label is attached to writing made for agents, and it's aimed at the developers who choose which guides their agent reads.

So I'd read "hand-crafted" as a claim that people took care over the guides, and then I'd ask for the evidence, which this project does supply: the date of the last eval run, and the tasks it was run on.

---

Work with me: email hello@ninadpathak.com, or book a 30-minute call at https://zcal.co/ninadpathak/meet

Services: https://ninadpathak.com/services/
