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

核心功能

agent-docs 是一套面向 AI Agent 消费优化的文档编写规范与模板系统，核心目标是解决 LLM 在上下文窗口中的"认知失败"问题——即 Agent 不知道自己不知道什么，因而过度依赖训练数据而忽略提供的文档。

三层混合上下文架构（Hybrid Context Hierarchy）：

1. Layer 1: Constitution（内联层）——始终驻留上下文，2-4K token，包含安全规则、架构约束、构建命令和文档索引图
2. Layer 2: Reference Library（本地检索层）——按需获取，1-5K token 分块，框架指南、详细规范、API 模式
3. Layer 3: Research Assistant（外部检索层）——白名单 gated，仅处理边缘情况，最新更新、Stack Overflow、第三方 llms.txt

Vercel 2026 基准测试验证：纯工具检索 53% → 检索+提示 79% → 内联 AGENTS.md 100% 任务完成率。

显著优点

• 解决"Lost in the Middle"问题：利用 LLM 的 U 型注意力特征，将关键治理规则置于文档顶部（首因效应）
• 高信号噪音比：强制剔除"欢迎来到..."、营销文案、更新日志，仅保留约束条件、文件路径、函数签名
• 零依赖零网络：纯 Markdown 实现，无可执行代码，无外部 API 调用
• 机器可读标准：支持 llms.txt 格式（项目根索引）和 llms-full.txt（完整去 HTML 文档）
• 安全可控：内联文档受版本控制，外部检索受域名白名单限制

局限与注意事项

• 纯文档类 Skill：无自动化工具，需人工按规范编写后供 Agent 读取
• 时效性依赖：引用的 Vercel 2026 基准数据需定期验证更新
• 学习成本：需要理解三层架构原理才能正确应用，非开箱即用模板
• Token 预算敏感：Constitution 层严格限制 4K token，对复杂项目可能需要精简取舍

适用人群

• 需要为 AI Agent 编写技术文档的开发者（SKILL.md、API 文档、README）
• 构建 AI 开发工具链的平台团队（Claude Code、Cursor、Devin 等环境）
• 追求 RAG 优化和上下文效率的高级用户

常规风险

• 低：纯 Markdown 无代码执行风险
• 间接提示注入：外部文档若被恶意篡改可能带入攻击，但通过白名单机制 mitigated
• SSRF：外部检索若未正确配置允许列表存在风险，但默认无外部调用