介绍
# Agent Docs
编写 AI 代理能够高效消费的文档。基于 Vercel 基准测试和行业标准（AGENTS.md、llms.txt、CLAUDE.md）。
## 混合上下文层次结构
用于优化代理性能的三层架构：
### 第 1 层：宪法（内联） **始终在上下文中。** 最多 2,000–4,000 个 token。
```markdown # AGENTS.md > Context: Next.js 16 | Tailwind | Supabase
## 🚨 CRITICAL - NO SECRETS in output - Use `app/` directory ONLY
## 📚 DOCS INDEX (use read_file) - Auth: `docs/auth/llms.txt` - DB: `docs/db/schema.md` ```
**包括：** - 安全规则、架构约束 - 构建/测试/检查命令（置于顶部以利用首因效应） - 文档地图（在哪里查找更多信息）
### 第 2 层：参考库（本地检索） **按需获取。** 1K–5K token 的块。
- 特定框架指南 - 详细风格指南 - API 模式
### 第 3 层：研究助手（外部） **由允许列表限制。** 仅限边缘情况。
- 最新库更新 - 用于处理罕见错误的 Stack Overflow - 第三方 llms.txt
## 为什么这样做有效
**Vercel 基准测试 (2026)：** | 方法 | 通过率 | |----------|-----------| | 基于工具的检索 | 53% | | 检索 + 提示 | 79% | | **内联 AGENTS.md** | **100%** |
**根本原因：** 元认知失败。代理不知道他们不知道什么——他们假设训练数据已经足够。内联文档完全绕过了这一点。
## 核心原则
### 1. 压缩索引 > 完整文档
一个 8KB 的压缩索引优于 40KB 的完整转储。
**压缩为：** - 文件路径（代码所在位置） - 函数签名（仅名称 + 类型） - 负面约束（“不要使用 X”）
### 2. 为分块构建结构
RAG 系统在标题处分割。每个部分必须是自包含的：
```markdown ## Database Setup ← Chunk boundary
Prerequisites: PostgreSQL 14+
1. Create database... ```
**规则：** - 前置关键信息（分块器会截断尾部） - 描述性标题（代理按标题文本搜索）
### 3. 内联优于链接
代理无法自主浏览。每个链接 = 工具调用 + 延迟 + 潜在失败。
| 方法 | Token 负载 | 代理成功率 | |----------|------------|---------------| | 完全内联 | ~12K | ✅ 高 | | 仅链接 | ~2K | ❌ 需要获取 | | 混合 | ~4K 基础 | ✅ 两全其美 |
### 4. “迷失在中间”问题
LLM 具有 U 形注意力： - **强：** 上下文开头（首因） - **强：** 上下文结尾（近因） - **弱：** 上下文中间
**解决方案：** 将关键规则放在 AGENTS.md 的**顶部**。治理优先，细节在后。
### 5. 信噪比
剔除所有非必要内容： - 没有“欢迎来到……”之类的序言 - 没有营销文本 - 核心文档中没有更新日志
像 llms.txt 和 AGENTS.md 这样的格式从机制上提高了信噪比。
## llms.txt 标准
供代理使用的机器可读文档索引：
```markdown # Project Name
> One-line project description.
## Authentication
- [Setup](docs/auth/setup.md): Environment vars and init - [Server](docs/auth/server.md): Cookie handling
## Database
- [Schema](docs/db/schema.md): Full Prisma schema ```
**位置：** 域根目录下的 `/llms.txt` **配套文件：** `/llms-full.txt` — 完整的连接文档，已剥离 HTML
## 安全考量
### 内联 = 受信任 AGENTS.md 是代码库的一部分。受控、版本固定。
### 外部 = 攻击面 - 通过隐藏文本进行间接提示注入 - 如果代理可以自由浏览，存在 SSRF 风险 - 依赖外部可用性
**缓解措施：** 域名允许列表，外部检索采用人在回路。
## 反模式
1. **粘贴 50 页** — 触发“迷失在中间” 2. **“参见外部文档”** — 代理无法自主浏览 3. **通用建议** — “编写整洁代码”（请使用具体约束） 4. **仅目录文档** — 没有内容的索引 5. **仅信任检索** — 53% vs 100% 的通过率
## 高级模式
有关 RAG 优化、多框架文档和 API 模板的详细指南，请参阅 [references/advanced-patterns.md](references/advanced-patterns.md)。
## 验证清单
- [ ] 关键治理规则位于文档顶部 - [ ] 总内联上下文在 4K token 以下 - [ ] 每个 H2 部分自包含 - [ ] 没有内联摘要的外部链接 - [ ] 负面约束明确（“不要……”） - [ ] 文件路径和签名，而非完整代码