名称： agent-docs
描述： 创建专为AI智能体消费优化的文档。适用于编写SKILL.md文件、README文件、API文档或任何将被LLM在上下文窗口中阅读的文档。有助于为RAG检索、令牌效率和混合上下文层次结构组织内容。
编写AI智能体能够高效消费的文档。基于Vercel基准测试和行业标准（AGENTS.md, llms.txt, CLAUDE.md）。
为获得最佳智能体性能的三层架构：
始终保持在上下文中。 最多2,000–4,000个令牌。
# AGENTS.md
> 上下文：Next.js 16 | Tailwind | Supabase
## 🚨 关键规则
- 输出中**禁止包含**机密信息
- **仅使用** `app/` 目录
## 📚 文档索引（使用 read_file）
- 认证：`docs/auth/llms.txt`
- 数据库：`docs/db/schema.md`
包含内容：
- 安全规则、架构约束
- 构建/测试/代码检查命令（置于顶部，利用首因效应）
- 文档地图（指明更多信息的位置）
按需获取。 1K–5K令牌的块。
通过允许列表控制。 仅用于处理边缘情况。
Vercel基准测试（2026）：
| 方法 | 通过率 |
|----------|-----------|
| 基于工具的检索 | 53% |
| 检索 + 提示 | 79% |
| 内联AGENTS.md | 100% |
根本原因： 元认知失败。智能体不知道它们不知道什么——它们假设训练数据是足够的。内联文档完全绕过了这个问题。
一个8KB的压缩索引优于一个40KB的完整文档转储。
压缩为：
- 文件路径（代码所在位置）
- 函数签名（仅名称和类型）
- 否定性约束（"不要使用X"）
RAG系统在标题处进行分割。每个部分必须自成一体：
## 数据库设置 ← 分块边界
先决条件：PostgreSQL 14+
1. 创建数据库...
规则：
- 前置关键信息（分块器会截断）
- 描述性标题（智能体通过标题文本搜索）
智能体无法自主浏览。每个链接 = 工具调用 + 延迟 + 潜在的失败。
| 方法 | 令牌负载 | 智能体成功率 |
|---|---|---|
| 完全内联 | ~12K | ✅ 高 |
| 仅链接 | ~2K | ❌ 需要获取 |
| 混合 | ~4K 基础 | ✅ 两者优点结合 |
LLM具有U型注意力分布：
- 强： 上下文开头（首因效应）
- 强： 上下文结尾（近因效应）
- 弱： 上下文中间
解决方案： 将关键规则放在AGENTS.md的顶部。治理优先，细节在后。
剥离所有非必要内容：
- 没有"欢迎来到..."的序言
- 没有营销文本
- 核心文档中没有更新日志
像llms.txt和AGENTS.md这样的格式能机械地提高信噪比。
为智能体准备的机器可读文档索引：
# 项目名称
> 单行项目描述。
## 认证
- [设置](docs/auth/setup.md)：环境变量和初始化
- [服务器](docs/auth/server.md)：Cookie处理
## 数据库
- [模式](docs/db/schema.md)：完整的Prisma模式
位置： 域根目录下的 /llms.txt
配套文件： /llms-full.txt — 完整的拼接文档，已去除HTML
AGENTS.md是代码库的一部分。受控、版本固定。
缓解措施： 域名允许列表，外部检索采用人在回路机制。
有关RAG优化、多框架文档和API模板的详细指导，请参阅 references/advanced-patterns.md。