Your Real Third Audience Isn't Mobile Users — It's Claude Code

For the last decade, web developers have planned content for two audiences: humans on screens and search engine crawlers. Addy Osmani — Google's AI engineering director — is now arguing, with data, that there is a third audience already consuming our sites at scale, and almost nobody is designing for them. He calls it Agentic Engine Optimization (AEO), and the original essay he published this month is the first operational framework I have seen for the problem.

1. Who Is the Third Audience?

AI coding agents: Claude Code, Cursor, Cline, Aider, GitHub Copilot Workspace, Continue, and the long tail of internal copilots companies are wiring up to their own product manuals. These agents are not browsing your site like a person. They issue a single HTTP request, strip the HTML, count tokens, and either fit your content into their context window or silently discard it. The "discard" case is the dangerous one — your documentation didn't fail in a way you can see in your analytics. It failed silently inside someone else's tool.

2. The Cisco Moment

Osmani's most striking example is concrete and humbling. Cisco's Secure Firewall documentation runs about 193,217 tokens, roughly 718,000 characters. That single page exceeds most agents' context windows entirely. Agents hitting it don't read it; they truncate it, skip sections, or hallucinate the parts that don't fit. If you have ever asked Claude Code or Cursor a question about a popular product's API and gotten a confidently wrong answer, this is one of the reasons. The page wasn't broken for humans. It was broken for the agent.

3. Token Budgets as a First-Class Metric

Osmani's recommended targets are practical and worth pinning to the wall: quick-start pages under 15,000 tokens, API references under 25,000, conceptual guides under 20,000. He is not telling you to dumb down your content; he is telling you to chunk it so a 200K-token agent can budget for it alongside the user's actual question, the project files, and the agent's own scratchpad. If your single doc page eats the entire window, your content effectively cannot be cited.

4. AGENTS.md and CLAUDE.md

The agent-facing recommendation that is going to spread fastest is the simplest: publish an AGENTS.md at the root of your repo as the canonical entry point for agents, and add a short CLAUDE.md that mirrors or references it for teams specifically using Claude Code. Treat these the way you used to treat robots.txt and sitemap.xml — table stakes for a serious project. The format is a single markdown file with sections an agent can chunk: project overview, install/run commands, common tasks, code style, testing rules, gotchas, and links to the deeper sections.

5. This Is Not the Same AEO SEO People Talk About

Osmani goes out of his way to point this out. The "AEO" your marketing team has been chasing — Answer Engine Optimization, getting cited in ChatGPT or Perplexity replies — is a different problem with overlapping terminology. Google's John Mueller has explicitly recommended against pushing markdown pages for organic search, and Google does not currently consume llms.txt. So you can have a great Agentic Engine Optimization story for Claude Code while having zero impact on your Google rankings, and vice versa. The cleanest mental model: classical SEO targets the search engine; Answer Engine Optimization targets generative search engines (ChatGPT, Perplexity, Gemini, Claude.ai); Osmani's Agentic Engine Optimization targets coding agents. Three audiences, three sets of techniques.

6. What Teams Should Ship This Quarter

First, audit your top 20 documentation pages with a token counter. Anything over 25K tokens is a tax on every agent that lands there. Second, add an AGENTS.md at repo root and link your most-cited pages from it. Third, expose stable, parseable endpoints — JSON, OpenAPI, server-rendered HTML without JavaScript-only content — and stop relying on client-side rendering for anything an agent might need. Agents do not run your React app. Fourth, instrument it: log every request whose user-agent matches a known coding agent (Claude-User, Cursor, Cline, etc.) and watch which pages they hit, where they truncate, and which pages send them away.

7. The Flywheel Implication

Engineers increasingly evaluate libraries by asking their coding agent. If your library's docs cause Claude Code to hallucinate or apologise, your library is invisible to a fast-growing slice of decisions. Conversely, if your AGENTS.md is the cleanest one in your category, agents will reach for your library by default — even if your DevRel team has never blogged about it. This is, on the cynical reading, a huge marketing channel for whoever moves first. On the less cynical reading, it is a chance to make the experience of using your software materially better for the engineers who depend on it.

My Take

I have watched enough framework-of-the-month cycles to be cautious about new optimization acronyms, but Agentic Engine Optimization is different in one important way: the audience is real, paying users, not a search algorithm. The agent is mediating an engineer's decision right now while they pay you for a license, evaluate your SDK, or consider migrating to your platform. Optimizing for that audience is not chasing crumbs — it is making your product easier to choose. The teams that adopt this in Q2 will own a measurable advantage by year-end, and the rest of us will be writing AGENTS.md files in a panic during Q4. Don't be the panic cohort.