agent-docs

核心用法

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 等标准的演进
• 误用风险：若误解"压缩"原则，可能产出信息不足的文档
• 组织采纳：方法论变革需要团队共识，非技术层面的实施阻力