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.

Источник