Agentic Engine Optimization (AEO)代理引擎优化（AEO）

How AI coding agents consume documentation is fundamentally different from how humans do - and if you’re still optimizing only for human readers, you’re leaving a growing share of your audience invisible to your tooling. Docs, CLIs, MCPs, Skills…there’s a whole ecosystem of interfaces that AI agents interact with.AI 编码代理读取文档的方式与人类根本不同——如果你仍然只为人类读者进行优化，就会让日益增长的受众在你的工具链中不可见。文档、CLI、MCP、技能……AI 代理交互的整个生态系统都在其中。

Disclosure and context. I’m a Director at Google Cloud AI, so a few things are worth flagging before you read on. The Lighthouse team in Chrome have shipped an experimental llms.txt check (docs, coverage); independently, the Google Search / Webmaster team have published their own guidance on SEO and AI agents, and Search does not officially recommend llms.txt as a standard. My position on AEO in this post should be read through a specific lens: my audience here is developers, and for that audience we should fully expect agents to consume docs more and more (vs humans) via agentic coding tools like Claude Code, Gemini CLI, Cursor, and Copilot. Optimizing for that consumption pattern makes sense for developer-facing docs even where it diverges from broader Search guidance aimed at the open web. Treat this as one practitioner’s view from inside the developer-tools world, not a Google-wide recommendation.披露与背景。我是 Google Cloud AI 的总监，所以在继续阅读之前有几件事需要说明。Chrome 的 Lighthouse 团队已经发布了实验性的 llms.txt 检查（文档、覆盖率）；独立地，Google Search / Webmaster 团队也发布了他们关于 SEO 与 AI 代理的指南，且 Search 并未正式将 llms.txt 作为标准推荐。本文中我对 AEO 的立场应当通过特定的视角来阅读：我的受众是开发者，对这类受众我们应当完全预期代理会比人类更频繁地通过 Claude Code、Gemini CLI、Cursor、Copilot 等代理编码工具消费文档。针对这种消费模式进行优化对面向开发者的文档是有意义的，即使它与面向开放网络的更广泛 Search 指南有所偏离。请将此视为来自开发者工具内部的实践者观点，而非 Google 全公司的推荐。

I’ve been watching something play out across developer portals that I think deserves more attention than it’s getting.我一直在观察开发者门户中出现的一些现象，我认为它们值得获得更多关注。

An engineer opens Claude Code, asks it to implement a spec and hits enter. The agent fetches some of your documentation. It might grab some of what it needs, parse it as raw text, strip the HTML, count the tokens, and either use it as context - or silently discard it because the token count exceeds its context window.一名工程师打开 Claude Code，要求它实现一个规范并回车。代理会抓取你的部分文档。它可能获取所需的内容，将其解析为原始文本，去除 HTML，统计 token 数，然后将其作为上下文使用——或者因为 token 数超过上下文窗口而悄悄丢弃。

Your analytics recorded nothing useful. Scroll depth was zero. Time-on-page was 400 milliseconds. No link clicks, no tutorial completions, no UI interactions. The funnel you’ve optimized for years showed nothing.你的分析记录没有任何有用信息。滚动深度为零。页面停留时间为 400 毫秒。没有链接点击，没有教程完成，没有 UI 交互。你多年优化的漏斗显示为空。

But the agent was absolutely there. It read your docs. And depending on how those docs were structured, it either completed the task successfully - or hallucinated a solution because the content was too token-heavy, poorly structured, or blocked by a misconfigured robots.txt.但代理确实在场。它阅读了你的文档。根据文档的结构，它要么成功完成任务，要么因为内容 token 过多、结构不佳或被错误配置的 robots.txt 阻挡而产生幻觉式的解决方案。

I’ve started calling the discipline that addresses this Agentic Engine Optimization.我开始把解决此问题的学科称为代理引擎优化。

What is Agentic Engine Optimization?什么是代理引擎优化？

Agentic Engine Optimization (AEO) is the practice of structuring, formatting, and serving technical content so that AI coding agents can actually use it - not just human readers.代理引擎优化（AEO）是对技术内容进行结构化、格式化和提供的实践，使 AI 编码代理能够实际使用它——而不仅仅是人类读者。

The analogy I keep coming back to is SEO. We spent years learning to optimize for search crawlers and human click patterns. AEO is the same idea, but for a different consumer: AI agents that autonomously fetch, parse, and reason over your content.我不断回归的类比是 SEO。我们花了多年时间学习为搜索爬虫和人类点击模式进行优化。AEO 是同样的思路，只是面向不同的消费者：自主抓取、解析并推理你内容的 AI 代理。

The things that matter turn out to be pretty specific:真正重要的因素相当具体：

• Discoverability - can agents find your documentation without rendering JavaScript?可发现性——代理能否在不渲染 JavaScript 的情况下找到你的文档？
• Parsability - is the content machine-readable without requiring visual layout interpretation?可解析性——内容是否机器可读，而无需视觉布局解释？
• Token efficiency - does the content fit within typical agent context windows without truncation?Token 效率——内容是否能在典型代理的上下文窗口内完整呈现而不被截断？
• Capability signaling - does the documentation tell agents what your API does, not just how to call it?能力信号——文档是否告诉代理你的 API 能做什么，而不仅仅是如何调用？
• Access control - does your robots.txt actually let AI traffic through?访问控制——你的 robots.txt 是否真的允许 AI 流量通过？

If any of these fail, agents either skip your content entirely or produce subtly wrong outputs. The tricky part is you’ll probably never know, because no analytics event fires.如果其中任何一点失败，代理要么完全跳过你的内容，要么产生细微错误的输出。棘手之处在于你可能永远不会知道，因为没有分析事件被触发。

How AI agents actually read your documentationAI 代理到底是如何阅读你的文档的

It’s worth spelling out the behavioral difference here, because it’s bigger than I initially expected.值得把行为差异写出来，因为它比我最初预期的要大得多。

The human pattern人类模式

A human developer lands on your docs homepage. They navigate to a relevant section. They skim headings, read a few paragraphs, maybe run a code sample in the interactive console, follow two or three internal links, and spend 4–8 minutes in session. Your analytics captures all of it.一名人类开发者打开你的文档首页。他们导航到相关章节。浏览标题，阅读几段文字，或许在交互式控制台运行代码示例，点击两三次内部链接，整个会话耗时 4–8 分钟。你的分析会捕获所有这些。

The agent pattern代理模式

A recent research paper (Developer Experience with AI Coding Agents) studied HTTP traffic from nine major AI coding agents - including Claude Code, Cursor, Cline, Aider, VS Code, and Junie - fetching developer documentation. The findings were pretty striking.一篇近期研究论文（《AI 编码代理的开发者体验》）研究了九大主流 AI 编码代理——包括 Claude Code、Cursor、Cline、Aider、VS Code、Junie——对开发者文档的 HTTP 流量。结果相当惊人。

Agents typically compress multi-page navigation into one or two HTTP requests. Where a human would spend minutes clicking through your documentation hierarchy, an agent issues a single GET request, receives the full page, and moves on. The whole concept of “user journey” collapses into a single server-side event.代理通常将多页导航压缩为一两次 HTTP 请求。人类需要花分钟点击浏览文档层级，而代理只发出一次 GET 请求，获取完整页面后继续。整个“用户旅程”概念在服务器端事件中坍缩为一次请求。

The practical consequence: every client-side analytics event - scroll depth, time-on-page, button clicks, tutorial completions, link follows, form interactions - becomes invisible. The agent just bypasses all of it.实际后果是：所有客户端分析事件——滚动深度、页面停留时间、按钮点击、教程完成、链接跟随、表单交互——都变得不可见。代理直接绕过了这些。

The fingerprints of AI trafficAI 流量的指纹

The study also identified distinct behavioral signatures you can use to spot AI agent traffic in your server logs:研究还识别出可用于在服务器日志中发现 AI 代理流量的独特行为特征：

Beyond coding agents, AI assistant web services (ChatGPT, Claude, Google Gemini, Perplexity) also generate distinct fingerprints when users share URLs in chat interfaces - triggering their own server-side fetches.除了编码代理，AI 助手网络服务（ChatGPT、Claude、Google Gemini、Perplexity）在用户在聊天界面分享 URL 时也会产生独特指纹——触发它们自己的服务器端抓取。

Once you know what to look for, you can start segmenting AI agent traffic in your analytics. I was surprised how much of it was already there in my own logs.一旦知道该看什么，你就可以在分析中对 AI 代理流量进行分段。我惊讶地发现自己的日志中已经有相当多的此类流量。

The token problem: your docs may be invisible to agentsToken 问题：你的文档可能对代理不可见

This is probably the most underappreciated part of the whole picture: token economics.这可能是整个图景中最被低估的部分：token 经济学。

Agents don’t have infinite context. Most have practical limits between 100K–200K tokens, and context management is an active constraint in every task. The paper highlights a concrete example: the Cisco Secure Firewall Management Center REST API Quick Start Guide (Version 10.0) comes in at 193,217 tokens - nearly 718,000 characters. That single document threatens to consume or exceed most agents’ entire usable context window.代理的上下文并非无限。大多数代理的实际限制在 100K–200K token 之间，且上下文管理是每个任务中的关键约束。论文举了一个具体例子：Cisco Secure Firewall Management Center REST API 快速入门指南（版本 10.0）长达 193,217 token——约 718,000 字符。单个文档就可能消耗或超出大多数代理的全部可用上下文窗口。

When an agent hits a document that’s too long, a few things can happen - none of them good:当代理遇到过长的文档时，可能会出现以下几种情况——都不理想：

• It may truncate silently, cutting off critical information可能会悄悄截断，切掉关键信息
• It may skip the document entirely in favor of something shorter可能会直接跳过该文档，转而使用更短的内容
• It may attempt chunking, which adds latency and error surface可能会尝试分块，这会增加延迟并带来错误风险
• It may fall back to parametric knowledge - i.e., make something up可能会回退到参数化知识——即凭空编造

I think this means token count is now a first-class documentation metric. If you’re not tracking token counts for your documentation pages, you’re missing a signal that agents actually use to decide whether to even attempt reading your content.我认为这意味着 token 数量现在应该成为文档的一级指标。如果你没有为文档页面跟踪 token 数，你就错失了代理决定是否尝试阅读内容的关键信号。

Practical token targets实际的 token 目标

Here’s what seems to work as a rough guide:以下是一个粗略的指导原则：

• Quick start / getting started pages: < 15,000 tokens快速入门/入门页面：< 15,000 token
• Individual API reference pages: < 25,000 tokens单个 API 参考页面：< 25,000 token
• Full API reference: chunk by resource/endpoint, not by product完整 API 参考：按资源/端点分块，而不是按产品分块
• Conceptual guides: < 20,000 tokens; link to detail rather than embed it概念指南：< 20,000 token；链接到细节而非嵌入

The AEO stack: what to actually buildAEO 栈：到底要构建什么

AEO isn’t a single thing - it’s a layered set of signals and standards. I’ve been thinking of it as a stack, from foundation to surface:AEO 不是单一事物——它是一套分层的信号和标准。我把它想象成一个从基础到表层的栈：

Layer 1: Access control (robots.txt)层 1：访问控制（robots.txt）

This is the agent’s first stop. Before fetching content, many agents check robots.txt to determine what they’re allowed to access.这是代理的第一站。许多代理在抓取内容之前会检查 robots.txt，以确定允许访问的范围。

A misconfigured robots.txt that blocks known AI crawlers will silently deny agents access to your documentation entirely. No traffic, no errors, no indication anything went wrong. I’ve seen this trip up teams who had no idea their docs were invisible to agents.配置错误的 robots.txt 阻止已知 AI 爬虫，会悄悄让代理完全无法访问你的文档。没有流量、没有错误、没有任何异常提示。我见过团队因此卡住，却根本不知道文档对代理是不可见的。

The practical steps:实际步骤：

• Audit your robots.txt for unintended blocks on AI agent user-agents审计 robots.txt，确保未意外阻止 AI 代理的 User-Agent
• Consider explicitly permitting well-known AI agent patterns (Anthropic, OpenAI, Google, Perplexity crawlers)考虑显式允许已知的 AI 代理模式（Anthropic、OpenAI、Google、Perplexity 爬虫）
• If you need more nuanced control, look at agent-permissions.json - an emerging spec that lets you declaratively specify which automated interactions are allowed, rate limits, preferred API endpoints, and more如果需要更细粒度的控制，可查看 agent-permissions.json——一个新兴规范，允许声明哪些自动交互被允许、速率限制、首选 API 端点等

Layer 2: Discovery via llms.txt层 2：通过 llms.txt 进行发现

Even if an agent can access your content, it still needs to find the right content. This is where llms.txt comes in.即使代理能够访问你的内容，它仍然需要找到正确的内容。这时 llms.txt 派上用场。

I think of llms.txt as a sitemap for AI agents. It’s a flat, Markdown-formatted file hosted at yourdomain.com/llms.txt that provides a structured directory of your documentation - descriptions and all, so agents can figure out what’s relevant without having to crawl your entire site.我把 llms.txt 当作 AI 代理的站点地图。它是一个平面、Markdown 格式的文件，托管在 yourdomain.com/llms.txt，提供文档的结构化目录——包括描述，让代理无需爬遍整个站点即可判断哪些内容相关。

A well-formed llms.txt looks something like:一个格式良好的 llms.txt 大致如下：

# YourProduct Documentation

## Getting Started
- [Quick Start Guide](/docs/quickstart): Install and make your first API call in 5 minutes
- [Authentication](/docs/auth): OAuth 2.0 and API key authentication patterns
- [Core Concepts](/docs/concepts): Data model, entities, and terminology

## API Reference
- [REST API Overview](/docs/api): Base URLs, versioning, pagination, error codes
- [Users API](/docs/api/users): CRUD operations for user management (12K tokens)
- [Events API](/docs/api/events): Event streaming and webhook configuration (8K tokens)

## MCP Integration
- [MCP Server](/docs/mcp): Model Context Protocol server for direct agent integration

What makes a good llms.txt:优秀 llms.txt 的要素：

• Descriptions that tell the agent what it will find, not just what the page is called描述应告诉代理会找到什么，而不仅仅是页面名称
• Token counts per page where useful (so agents can make informed context decisions)在适用时提供每页的 token 数（帮助代理做出上下文决策）
• Organized by task, not by product hierarchy按任务组织，而非按产品层级
• Kept under 5,000 tokens itself (it shouldn’t blow the budget just being an index)自身保持在 5,000 token 以下（不应因索引本身耗尽预算）

Layer 3: Capability signaling via skill.md层 3：通过 skill.md 进行能力信号

llms.txt tells agents where things are. skill.md tells them what your product can actually do.llms.txt 告诉代理在哪里可以找到内容。skill.md 告诉它们你的产品到底能做什么。

This is a distinction that I think matters more than it first appears. Instead of an agent having to infer capabilities from prose documentation, skill.md surfaces them declaratively - mapping intentions to endpoints and resources.这是一个比表面看起来更重要的区分。与其让代理从散文文档中推断能力，skill.md 以声明式方式呈现——将意图映射到端点和资源。

A skill.md for an authentication service might look like:一个身份验证服务的 skill.md 可能如下所示：

---
name: auth-service
description: Handles user authentication, OAuth 2.0 flows, and session management
---

## What I can accomplish
- Authenticate users via OAuth 2.0 (authorization code, client credentials, PKCE)
- Issue and validate JWT tokens
- Manage user sessions and refresh token rotation
- Integrate with SSO providers (SAML, OIDC)

## Required inputs
- Client ID and Client Secret (from developer console)
- Redirect URI (must be pre-registered)
- Requested scopes (read:user, write:data, admin)

## Constraints
- Rate limit: 1000 token requests per minute per application
- Token expiry: access tokens 1hr, refresh tokens 30 days
- PKCE required for public clients

## Key documentation
- [OAuth 2.0 Guide](/docs/oauth): Full flow walkthrough with code samples
- [Token Reference](/docs/tokens): Token structure, claims, validation
- [Postman Collection](/docs/postman): Ready-to-use request templates

This is what lets agents make meaningful decisions - not just fetch documentation, but understand whether your API can even satisfy the user’s intent before spending context budget on a full read.这让代理能够做出有意义的决策——不仅仅是抓取文档，而是先判断你的 API 是否能满足用户意图，再决定是否消耗上下文预算进行完整阅读。

Layer 4: Content formatting for agent parsing层 4：为代理解析而格式化内容

Even with perfect discovery and capability signaling, the actual content needs to be agent-readable. A few things I’ve found matter here:即使发现和能力信号完美，实际内容仍需对代理可读。我发现以下几点很关键：

Serve Markdown, not just HTML. Many documentation platforms let you access raw Markdown by appending .md to a URL or via a query parameter. Make this discoverable. Agents process Markdown with dramatically lower token overhead than HTML (no tag noise, no navigation chrome, no footer cruft).提供 Markdown，而非仅 HTML。许多文档平台可以通过在 URL 末尾添加 .md 或使用查询参数获取原始 Markdown。让这点可被发现。相较于 HTML（标签噪声、导航栏、页脚杂项），Markdown 的 token 开销显著更低。

Structure for scanning, not reading. Agents don’t read linearly - they parse structure:结构化以便扫描，而非线性阅读。代理不会逐行阅读——它们解析结构：

• Use consistent heading hierarchies (H1 → H2 → H3, no skipping)使用一致的标题层级（H1 → H2 → H3，不能跳层）
• Lead each section with the outcome, not the background每个章节以结果为导向，而非背景说明
• Put code examples immediately after the claim they illustrate代码示例紧随其说明出现
• Use tables for parameter references - they compress better than prose lists参数参考使用表格——比散文列表更易压缩

Kill the navigation noise. Sidebars, breadcrumbs, and footer links that appear in your HTML are just noise in Markdown/text. Keep them out of the parseable content path.去除导航噪声。侧边栏、面包屑和页脚链接在 HTML 中出现，但在 Markdown/文本中只是噪声。保持它们不出现在可解析内容路径中。

Front-load the useful stuff. The first 500 tokens of any page should answer: what is this, what can it do, and what do I need to get started. Agents have limited patience for preamble.前置有用信息。任何页面的前 500 token 应回答：这是什么、能做什么、如何快速上手。代理对前言的耐心有限。

Layer 5: Token surfacing层 5：Token 可见性

This one is simpler than it sounds but surprisingly high-leverage: surface token counts on your documentation pages. Ideally in both the llms.txt index and on the pages themselves (as metadata or a page header).这看似简单，却极具杠杆效应：在文档页面上展示 token 数量。理想情况下在 llms.txt 索引以及页面本身（元数据或页面标题）中都提供。

This gives agents the information they need to make smart decisions:这为代理提供了做出智能决策所需的信息：

• “This page is 8K tokens - I can include it fully in context”“此页 8K token——我可以完整放入上下文”
• “This page is 150K tokens - I should fetch only the relevant section”“此页 150K token——我应只抓取相关章节”
• “This page exceeds my context window - I’ll use the summary from llms.txt instead”“此页超出我的上下文窗口——我将使用 llms.txt 中的摘要”

Implementation is straightforward: count characters server-side, divide by ~4 for a rough token estimate, and expose it as a meta tag or HTTP response header.实现很直接：服务器端统计字符数，除以约 4 得到粗略 token 估算，并以 meta 标签或 HTTP 响应头暴露。

Layer 6: “Copy for AI”层 6：“为 AI 复制”

This is more of a UX bridge than an infrastructure layer, but I think it’s worth including: the Copy for AI button.这更像是 UX 桥梁而非基础设施层，但值得一提：为 AI 复制按钮。

When a developer is working inside an IDE with an AI assistant and wants to include documentation as context, they currently copy and paste from rendered HTML - which includes navigation noise, footers, all of it. A “Copy for AI” button that copies clean Markdown to the clipboard is a small thing, but it meaningfully improves the quality of context the agent receives.当开发者在 IDE 中使用 AI 助手并想把文档作为上下文时，通常会从渲染的 HTML 中复制粘贴——其中包含导航噪声、页脚等。一个“为 AI 复制”按钮将干净的 Markdown 复制到剪贴板，虽小却显著提升代理获取上下文的质量。

Anthropic, Cloudflare, and others have already shipped variants of this. It’s low effort and high signal.Anthropic、Cloudflare 等已经推出了此类变体。投入低、信号高。

AGENTS.md: the emerging defaultAGENTS.md：新兴默认入口

One thing worth calling out specifically: AGENTS.md.特别值得指出的一点：AGENTS.md。

Just as README.md became the default entry point for human developers exploring a repository, AGENTS.md is becoming the entry point for AI agents. When a coding agent opens a project, it looks for AGENTS.md in the root directory and pulls its instructions into every subsequent task.正如 README.md 成为人类开发者浏览仓库的默认入口，AGENTS.md 正在成为 AI 代理的入口。当编码代理打开项目时，会在根目录寻找 AGENTS.md 并将其指令拉入后续任务。

I’ve been writing about this separately, but the short version is that a good AGENTS.md includes:我单独写过这方面的文章，简要概括，一个好的 AGENTS.md 包含：

• Project structure and key file locations项目结构和关键文件位置
• Direct links to relevant API or service documentation指向相关 API 或服务文档的直接链接
• Available dev sandboxes and test environments可用的开发沙箱和测试环境
• Rate limits and constraints the agent should know about速率限制和代理应知的约束
• Preferred patterns and conventions for the codebase代码库的首选模式和约定
• Links to MCP servers if available如有 MCP 服务器，提供链接

Cisco DevNet has already adopted this as the default file in their GitHub template for open-source projects - newly created projects come with an AGENTS.md pre-populated with project-specific content, links to OpenAPI docs, DevNet sandboxes, and test environments.Cisco DevNet 已在其 GitHub 开源项目模板中将其设为默认文件——新建项目会预置一个 AGENTS.md，包含项目特定内容、OpenAPI 文档链接、DevNet 沙箱和测试环境。

Monitoring AI referral traffic监控 AI 引荐流量

One thing you can do right now: start tracking AI referral traffic in your analytics.你现在可以做的一件事：在分析中开始跟踪 AI 引荐流量。

Here are the referral sources worth watching:以下是值得关注的引荐来源：

labs.perplexity.ai/referral
chatgpt.com/(none)
chatgpt.com/organic
link.edgepilot.com/referral
platform.openai.com/referral
perplexity/(not set)
claude.ai/referral
copilot.microsoft.com/referral
gemini.google.com/referral

You’ll also want to monitor for the HTTP fingerprints I mentioned earlier - axios/1.8.4, curl/8.4.0, got (sindresorhus/got), colly - to catch direct agent traffic that arrives without a referrer.你还需要监控前面提到的 HTTP 指纹——axios/1.8.4、curl/8.4.0、got（sindresorhus/got）、colly——以捕获没有 referrer 的直接代理流量。

Building a proper AI traffic segment gives you the leading indicators for whether any of this work is actually making a difference.构建合适的 AI 流量分段能为你提供是否产生实际影响的前置指标。

The broader implications for developer experience对开发者体验的更广泛影响

I want to step back for a moment, because I think AEO points at something bigger than a technical checklist.我想稍作停顿，因为我认为 AEO 指向的东西比技术清单更大。

For most of the web’s history, developer portals were designed around human cognitive patterns: progressive disclosure, visual hierarchy, interactive examples, guided tutorials. All of those assume a human is in the loop at every step.在大部分网络历史中，开发者门户是围绕人类认知模式设计的：渐进式披露、视觉层级、交互式示例、引导式教程。这些假设都以人为中心。

In an agent-heavy world, many of those assumptions break down:在以代理为主的世界里，许多假设失效：

• Visual hierarchy is irrelevant - agents read text, not layouts视觉层级无关紧要——代理读取文本，而非布局
• Progressive disclosure becomes an obstacle - agents want everything at once渐进式披露成为障碍——代理希望一次性获取全部信息
• Interactive examples lose their value - unless there’s a static/API equivalent交互式示例失去价值——除非有静态/API 等价物
• User journeys collapse - a multi-chapter tutorial becomes a single context load用户旅程坍缩——多章节教程变成一次上下文加载

This doesn’t mean human-centered design stops mattering. Humans still read docs. But they increasingly read them inside an AI assistant’s context - which means the agent is often the proximate consumer, even when a human is the ultimate beneficiary.这并不意味着以人为本的设计不再重要。人类仍然阅读文档，只是他们越来越多地在 AI 助手的上下文中阅读——这意味着代理往往是直接的消费者，即使最终受益者是人类。

The best documentation going forward will probably need to serve both audiences at once: scannable and well-structured for humans, machine-readable and token-efficient for agents.未来最好的文档可能需要同时服务两类受众：对人类可扫描、结构良好；对代理机器可读、token 高效。

AEO audit checklistAEO 审核清单

Here’s what I’d check if I were evaluating a documentation site’s agent-readiness today:如果我今天评估一个文档站点的代理可读性，我会检查以下内容：

Discovery发现

• llms.txt exists at root with structured index of all documentation根目录存在结构化索引的 llms.txt
• robots.txt does not inadvertently block known AI agent user-agentsrobots.txt 未意外阻止已知 AI 代理的 User-Agent
• agent-permissions.json defines access rules for automated clientsagent-permissions.json 定义了自动客户端的访问规则
• AGENTS.md exists in code repositories linking to relevant docs代码仓库中存在 AGENTS.md 并链接到相关文档

Content structure内容结构

• Documentation pages available as clean Markdown (not just rendered HTML)文档页面提供干净的 Markdown（而非仅渲染的 HTML）
• Each page leads with a clear outcome statement in the first 200 words每页在前 200 字内给出明确的结果声明
• Headings are consistent and hierarchically correct标题一致且层级正确
• Code examples immediately follow their prose description代码示例紧随其文字说明
• Parameter references use tables, not nested prose参数参考使用表格，而非嵌套散文

Token economicsToken 经济学

• Token counts are tracked per documentation page为每个文档页面跟踪 token 数
• No single page exceeds 30,000 tokens without chunking strategy单页不超过 30,000 token，除非采用分块策略
• Token counts exposed in llms.txt for key pages在 llms.txt 中为关键页面暴露 token 数
• Token counts available as page metadata (meta tag or HTTP header)在页面元数据中提供 token 数（meta 标签或 HTTP 头）

Capability signaling能力信号

• skill.md files describe what each service/API does, not just how to call itskill.md 文件描述每个服务/API 的功能，而不仅是调用方式
• Each skill includes: capabilities, required inputs, constraints, key doc links每个 skill 包含：能力、必需输入、约束、关键文档链接
• MCP server available for direct agent integration (if applicable)如适用，提供 MCP 服务器供直接代理集成

Analytics分析

• AI referral sources segmented in web analytics在网页分析中对 AI 引荐来源进行分段
• Server logs monitored for known AI agent HTTP fingerprints在服务器日志中监控已知 AI 代理的 HTTP 指纹
• Baseline established for AI vs. human traffic ratio建立 AI 与人类流量比例的基线

UX bridgeUX 桥梁

• “Copy for AI” button available on documentation pages文档页面提供“为 AI 复制”按钮
• Markdown source accessible via URL convention (e.g., appending .md)通过 URL 约定（例如追加 .md）访问 Markdown 源文件

Tooling工具

To help automate some of these checks, I’ve shipped agentic-seo - a lightweight audit tool that scans your site for AEO opportunities. It checks for llms.txt, robots.txt agent blocking, token counts, Markdown availability, and more. Think of it as Lighthouse, but for agent-readiness.为帮助自动化这些检查，我发布了 agentic-seo——一个轻量级审计工具，扫描站点的 AEO 机会。它检查 llms.txt、robots.txt 代理阻塞、token 计数、Markdown 可用性等。把它当作 Lighthouse 的代理可读性版。

Where to start从哪里开始

If you’re looking at this list and wondering where to begin, here’s the sequence I’d recommend:如果你看到这份清单并想知道从哪儿入手，我的推荐顺序是：

1. Audit your robots.txt - ten minutes of work, prevents silent agent lockout审计 robots.txt——十分钟工作，防止代理静默锁定
2. Add llms.txt - a few hours, immediate discoverability gains添加 llms.txt——几小时，立即提升可发现性
3. Measure and surface token counts - a weekend project with high leverage测量并展示 token 数——周末项目，高杠杆
4. Write skill.md for your top 3 APIs - start with whatever agents are most likely to reach for为前三个 API 编写 skill.md——先从最可能被代理访问的开始
5. Add “Copy for AI” buttons - low effort, high signal添加“为 AI 复制”按钮——低投入，高信号
6. Set up AI traffic monitoring - gives you the data to justify everything else设置 AI 流量监控——为其他工作提供数据支撑

Wrapping up结束语

SEO taught us that great content isn’t enough - you have to make it discoverable in the way that matters for the actual traffic patterns of the era. I think AEO is the same lesson, just for a different consumer.SEO 告诉我们，仅有优质内容不够——必须让其以符合当时流量模式的方式可被发现。我认为 AEO 是同样的教训，只是面向不同的消费者。

AI coding agents are already a significant and growing share of documentation traffic. They behave fundamentally differently from human readers. And most developer portals aren’t built for them yet.AI 编码代理已经是文档流量中显著且增长的份额。它们的行为与人类读者根本不同。而大多数开发者门户尚未为它们而建。

The teams that move early here will probably have a real advantage: their APIs will be the ones agents recommend, integrate successfully, and come back to. The ones that don’t will see growing gaps between documentation quality and actual agent task success - a silent failure mode that’s genuinely hard to debug.率先行动的团队将拥有真实优势：他们的 API 将成为代理推荐、成功集成并被反复调用的对象。未跟进的团队会看到文档质量与实际代理任务成功率之间的差距日益扩大——一种难以调试的静默失败模式。

The good news is that building for agents tends to make documentation better for humans too. The disciplines overlap more than they diverge.好消息是，为代理构建的文档往往也会让人类受益。两者的实践重叠多于分歧。

Start with llms.txt. Ship a skill.md. Audit your robots.txt. Measure your tokens. Most of this is a weekend’s worth of work, and the payoff is already real.从 llms.txt 开始。发布 skill.md。审计 robots.txt。测量 token。大多数工作只需一个周末，回报已经非常明显。