We started writing docs for AI agents, not humans — and made it an open standard

说明与用途

为 AI 代理创建了机器可读的文档格式，消除了安装和配置错误，并将其公开为标准。

问题

Developer documentation written for humans caused AI agents to misinterpret or invent configuration details, leading to installation and integration failures.

结果

Agents could reliably install and configure products using the new machine‑readable docs, reducing errors and improving developer experience.

工作流

• 1. Observe agents interacting with existing docs and identify missteps.
• 2. Identify missing or ambiguous facts that agents must infer.
• 3. Create a new per‑product, per‑release file (documentation.ai.md).
• 4. Structure the file into fixed sections: identity, install/run, configuration, API quickstart, admin surface, architecture facts, links.
• 5. Ensure each section contains exact commands, env vars, defaults, and real request/response examples.
• 6. Publish the file alongside the human‑oriented docs.
• 7. Release the format as an open standard (CC BY 4.0).

证据

We started watching agents work against our documentation.

来源

A fact an agent has to infer is a fact you failed to state.

来源