👥 Developers + AI agents 🎯 Retrieval-ready docs 📅 2026

As AI agents become a primary interface for software, documentation has to work for both the people who read it and the agents that retrieve and reason over it. At Warp, I adapted a modern docs system for AI-native workflows, pairing durable design principles with recurring evaluation.

The problem

Traditional docs are tuned for humans: prose, visual layout, and context the reader fills in. Agents consume docs as structured data, so what makes documentation agent-friendly is largely architectural:

  • Explicit structure instead of implicit, visual-only hierarchy
  • Semantic organization that groups related concepts predictably
  • Canonical concepts, one authoritative page per idea, not scattered duplicates
  • Strong internal linking so relationships are traversable, not just implied
  • Low ambiguity, consistent terms with single, defined meanings
  • Predictable navigation an agent can follow without guessing

Human-readable is not automatically agent-readable.

At a glance

Audience

Developers and the AI agents retrieving and reasoning over the docs

Goal

Make docs reliably useful for retrieval, reasoning, and task completion

Collaboration

Engineering, Growth, DevEx

Tools

Astro Starlight, llms.txt, AFDocs, Git/GitHub, Warp (agentic AI)

Principles

Agent-friendliness is an architectural property, not a writing trick. A few principles make retrieval and reasoning work by design.

Information architecture
↓
Terminology
↓
Internal links
↓
Canonical concepts
↓
Structured pages
↓
Agent
Agent-friendliness is built from the architecture up: each layer makes documentation more retrievable and more reliable for agents.
  • Canonical concepts: One concept, one authoritative page, so agents retrieve a single source of truth instead of reconciling duplicates.
  • Rich internal linking: Agents navigate a graph, not a menu, so dense, accurate links make relationships traversable.
  • Structured information architecture: A predictable hierarchy lets an agent locate and scope content reliably.
  • Consistent terminology: One name, one meaning, so retrieval stays precise.
  • Retrieval-oriented writing: Descriptive headings, lists, and one concept per section make content easy to chunk and extract.
  • Explicit context: Define terms and state prerequisites so each page stands on its own.

These principles are durable; they hold regardless of which model or tool is reading the docs.

Evaluation

Recurring checks measure agent-friendliness and track it over time:

  • AFDocs audit: A weekly agent-friendliness scorecard with per-check scores and trend tracking, so regressions surface quickly.
  • AEO and cross-link audits: Answer-engine optimization and relationship-graph coverage that catch orphaned pages and weak linking.
  • llms.txt: A machine-readable index that points agents to the full docs in markdown.
  • Search and discoverability: Navigation and findability checks that keep content reachable.

How these checks actually run, on a schedule and feeding results back into the system, is the subject of the Documentation Software Factory page.

Continuous improvement

Agent-friendliness compounds. The Documentation Software Factory runs these evaluations on a recurring cadence and turns the findings into improvements: the skills and templates that produce the docs evolve, and each pass leaves them more agent-ready than the last.

Outcomes

  • Improved AI discoverability of the documentation
  • Stronger semantic relationships between pages
  • Better, more predictable navigation
  • Fewer orphaned pages
  • Higher answer quality for agent and search queries
  • More reusable, canonical concepts

Lessons learned

  • AI agents reward good information architecture more than polished prose.
  • Retrieval quality depends more on structure than on writing style.
  • Human-readable documentation is not automatically agent-readable.
  • Continuous evaluation is more valuable than one-time optimization.