文档站应提供可机读的 discovery 与 markdown 形态，否则 coding agent 会 truncation/失败并回退训练数据。
Claim
文档站应提供可机读的 discovery 与 markdown 形态，否则 coding agent 会 truncation/失败并回退训练数据。
Why it matters
Agent 编排与 harness 依赖 WebFetch；文档可读性直接决定工具正确率与上下文成本。
Summary
Agent-Friendly Documentation Spec（Draft v0.5.1）用 7 类 23 项检查文档对 coding agent 的可用性。 最高杠杆：llms.txt（<50K）、.md 或 content-negotiation、单页内容控制、同 host 重定向、parity 观测。 配套 afdocs CLI 可对站点跑全量检查。
Actions
- (none)
Evidence
- (none)
Caveats
- (none)
Research queries
- (none)
Body
背景
Coding agent 与 harness 越来越多地通过 HTTP fetch 读文档。人读 OK 的站点对 agent 常失败：SPA 空壳、HTML+CSS 噪音、页面过长被截断、无 discovery 索引。
机制
Spec 把问题拆成可自动化检查：discoverability（llms.txt）、markdown 可用性、page size、结构序列化、URL 稳定性、观测、认证墙。阈值校准到常见 agent fetch 管线（约 50K 内容更稳）。
取舍
- 全站 HTML 重写成本高 → 先 llms.txt + 关键页 .md
- 严格 50K 可能过度切分 → 用索引分层拉取
- 与 MCP/工具文档：同一套原则适用
动作
- 根路径发布
llms.txt并覆盖主文档 - 关键页提供
.md或 content-negotiation - CI 跑 afdocs；agent 侧优先 markdown