基于 Vercel 基准测试与行业标准的 AI 代理文档编写指南，通过三层上下文架构优化 RAG 检索效率，帮助开发者创建 LLM 友好型技术文档。
说明：
## 核心用法
Agent Docs 是一套面向 AI 代理消费场景的技术文档编写方法论，核心目标是解决 LLM 在上下文窗口中的”元认知失败”问题——即代理不知道自己不知道什么，往往过度依赖训练数据而忽略关键约束。
该技能采用**三层混合上下文架构**：
– **Layer 1（宪法层）**：内联的 AGENTS.md，2-4K 令牌，始终驻留上下文，包含安全规则、架构约束和文档索引
– **Layer 2（参考库）**：按需获取的本地文档块，1-5K 令牌，涵盖框架指南和 API 模式
– **Layer 3（研究助手）**：白名单管控的外部资源，仅用于边缘案例
具体实践包括：压缩索引替代完整文档、为 RAG 分块优化结构、内联优于链接、利用 U 型注意力曲线（关键规则置顶）、以及最大化信噪比。
## 显著优点
1. **经过验证的效果**：Vercel 2026 基准测试显示，内联 AGENTS.md 方案达到 100% 通过率，远超纯工具检索（53%）和检索+提示（79%）
2. **Token 效率**：8KB 压缩索引优于 40KB 完整文档转储，显著降低上下文成本
3. **安全内建**：主动将安全规则嵌入宪法层，从源头规避秘密泄露、架构违规等风险
4. **行业标准对齐**：兼容 llms.txt、CLAUDE.md、AGENTS.md 等新兴规范
5. **即插即用**：纯文档技能，零依赖、零配置，立即可用于任何项目
## 潜在缺点与局限性
1. **维护成本**：三层架构需要持续同步，文档更新时需确保各层一致性
2. **团队学习曲线**：开发者需理解”为机器阅读而写”与传统文档的差异
3. **过度压缩风险**：极端压缩可能导致人类读者理解困难
4. **框架特定性**：部分建议（如 Next.js 示例）需要适配到其他技术栈
5. **外部资源管控**：Layer 3 的白名单机制在实际落地中可能遇到组织流程阻力
## 适合的目标群体
– **技术文档工程师**：需要优化文档的 LLM 可消费性
– **AI 原生开发团队**：构建重度依赖 AI 编码助手的项目
– **平台/框架维护者**：希望提供官方 AGENTS.md 或 llms.txt 的项目
– **DevRel 与开发者体验团队**：提升开发者工具链的 AI 友好度
– **企业架构师**：制定组织级 AI 辅助开发规范
## 使用风险
– **性能风险**：无，纯静态文档技能
– **依赖风险**：零外部依赖，完全自包含
– **版本漂移**：需手动跟进 llms.txt 等标准的演进
– **误用风险**：若误解”压缩”原则，可能产出信息不足的文档
– **组织采纳**：方法论变革需要团队共识，非技术层面的实施阻力
会员专属
