Keep machine docs in sync with the product
Mantén la documentación para máquinas sincronizada con el producto
Tie agent-facing documentation to releases so agents never act on stale endpoints or deprecated parameters.
Why
Lag between code and docs causes agents to generate calls against deprecated parameters (Fern). The canonical AX framework (agentexperience.ax — Contextual Alignment) requires that context be kept consistent with the live product because agents cannot know what has changed since their model was trained. Unlike human users who see deprecation banners, agents act on the documentation they receive with no fallback.
Do
Practice docs-as-code in the same PR as API changes.
Don't
Maintain docs on a separate, slower cycle.
Artifact
Process artifact: add a CI check that fails the build if an API schema changes without a matching docs update in the same pull request. The artifact is a required status check, not code to ship.
Citations
- [01]agentexperience.ax — Principles of AX ↗
Contextual Alignment: maintain consistency of content with information accessible from human-oriented context systems; context quality must be robust to work across various models
- [02]Fern — Optimizing API Docs for AI Agents ↗
Lag between code and documentation causes agents to generate calls against deprecated parameters, a leading cause of silent agent failures
- [03]Mathias Biilmann — AX in Practice ↗
LLMs need to know which unique APIs, versions, or knowledge applies — especially anything that may have changed since the model's knowledge cut-off