Agent Docs

核心用法

agent-docs 是一套针对 AI Agent 消费场景设计的文档编写规范，主要用于创建 SKILL.md、README、API 文档等将被 LLM 在上下文窗口中读取的内容。其核心框架是三层混合上下文架构（Hybrid Context Hierarchy）：

1. Constitution 层（内联）：2000-4000 token，始终驻留上下文，包含安全规则、架构约束、关键命令和文档索引
2. Reference Library 层（本地检索）：1K-5K token 分块，按需获取的框架指南和 API 模式
3. Research Assistant 层（外部）：需白名单授权，仅用于边缘场景如最新库更新

显著优点

• 效能验证：Vercel 2026 基准显示，纯工具检索通过率 53%，检索+提示 79%，内联 AGENTS.md 达 100%
• 解决根本问题：绕过 Agent 的"元认知失败"——Agent 不知道自己不知道什么，内联文档彻底规避此问题
• Token 效率：8KB 压缩索引优于 40KB 完整文档，通过文件路径、函数签名、负向约束实现高效压缩
• 结构优化：针对 RAG 分块设计，每个 H2 区块自包含；利用 U 型注意力，关键规则置顶

潜在局限

• 维护成本：Constitution 层需与代码库同步更新，否则产生漂移
• 规模瓶颈：4K token 上限限制复杂项目的规则覆盖
• 外部依赖风险：llms.txt 等标准尚未完全统一，跨生态兼容性存疑

适合人群

• 构建 AI 原生开发工作流的团队
• 维护大型代码库、需多 Agent 协作的工程师
• 追求极致上下文效率的技术作者

常规风险

• 安全边界：内联内容可信，但外部检索存在提示注入和 SSRF 风险
• 过度压缩：关键信息遗漏可能导致 Agent 误判
• 格式僵化：机械追求 SNR 可能降低人类可读性

核心用法

Agent Docs 是一套专为 AI 代理消费优化的文档编写规范，核心采用 Hybrid Context Hierarchy（混合上下文层级） 三层架构：

1. Layer 1: Constitution（内联层） — 始终驻留上下文，2K-4K tokens，包含安全规则、架构约束、文档索引
2. Layer 2: Reference Library（本地检索层） — 按需获取，1K-5K token 块，包含框架指南、API 模式
3. Layer 3: Research Assistant（外部层） — 白名单控制，用于边缘案例

关键操作：编写 AGENTS.md 放置项目根目录，遵循「关键规则置顶」「压缩索引优于完整文档」「自包含分块」等原则。

显著优点

• 效果验证：Vercel 2026 基准显示，内联 AGENTS.md 方案任务通过率达 100%，对比纯工具检索（53%）和检索+提示（79%）优势显著
• 元认知失效规避：解决代理「不知道自己不知道什么」的根本问题
• Token 效率：8KB 压缩索引优于 40KB 完整文档转储
• 即插即用：无需外部依赖，纯 Markdown 实现

潜在局限

• 维护成本：需人工维护三层文档一致性，项目演进时可能滞后
• 规模上限：Layer 1 严格限制 4K tokens，超大型项目需精简取舍
• 团队学习曲线：开发者需理解 LLM 注意力机制（U 型分布、「Lost in the Middle」问题）
• 外部信息滞后：Layer 3 受白名单限制，难以及时获取最新库更新

适合人群

• AI 原生开发团队：使用 Claude、GPT-4 等作为日常开发助手的工程师
• 框架/工具链维护者：需要为下游开发者提供机器可读文档的项目
• RAG 系统架构师：优化企业内部知识库检索效率的技术负责人

常规风险

• 架构固化风险：过度依赖内联文档可能导致团队忽视工具链升级
• 安全误配置：若 AGENTS.md 包含真实密钥（尽管规范明确禁止），会造成泄露
• 检索依赖幻觉：用户可能误以为 100% 通过率代表万能，忽略任务复杂度差异

---
来源：基于 Vercel 2026 基准测试、AGENTS.md / llms.txt / CLAUDE.md 行业标准