Agent Docs

编写AI智能体能够高效使用的文档。基于Vercel基准测试和行业标准（AGENTS.md、llms.txt、CLAUDE.md）。

混合上下文层次结构

用于实现最优智能体性能的三层架构：

第一层：宪法（内联）

始终存在于上下文中。最大2,000–4,000个词元。

# 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`

包含：

• 安全规则、架构约束
• 构建/测试/代码检查命令（置于顶部，利用首因效应）
• 文档地图（指明何处可找到更多信息）

第二层：参考库（本地检索）

按需获取。1K–5K词元的文本块。

• 特定框架指南
• 详细风格指南
• API模式

第三层：研究助手（外部）

通过允许列表控制访问。仅用于处理边缘情况。

• 最新的库更新
• 针对冷门错误的Stack Overflow
• 第三方llms.txt

为何此法有效

Vercel基准测试（2026年）：

根本原因：元认知失败。智能体不知道它们不知道什么——它们假设训练数据是足够的。内联文档完全绕过了这个问题。

核心原则

1. 压缩索引 > 完整文档

一个8KB的压缩索引优于40KB的完整转储。

压缩至：

• 文件路径（代码所在位置）
• 函数签名（仅名称和类型）
• 负面约束（“不要使用X”）

2. 为分块而设计结构

RAG系统会在标题处进行分割。每个部分必须是自包含的：

## Database Setup          ← Chunk boundary

Prerequisites: PostgreSQL 14+

1. Create database...

规则：

• 关键信息前置（分块器会截断内容）
• 使用描述性标题（代理通过标题文本进行搜索）

3. 行内内容优先于链接

代理无法自主浏览。每个链接都意味着一次工具调用、延迟以及潜在的失败风险。

4. “迷失在中间”问题

LLM具有U型注意力分布：

• 强：上下文开头（首因效应）
• 强：上下文结束（时效性）
• 弱：上下文中间

解决方案：将关键规则放在AGENTS.md的顶部。治理优先，细节其次。

5. 信噪比

剥离所有非必要内容：

• 不要有"欢迎来到..."之类的开场白
• 不要有营销文本
• 核心文档中不要有变更日志

像llms.txt和AGENTS.md这样的格式会机械地提高信噪比。

llms.txt 标准

供代理使用的机器可读文档索引：

# 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% 对比 100% 的通过率

高级模式

关于RAG优化、多框架文档和API模板的详细指南，请参阅references/advanced-patterns.md。

验证清单

• 关键治理内容置于文档顶部
• 内联上下文总量控制在4000词元以内
• 每个H2章节自成体系
• 外部链接必须附带内联摘要
• 明确列出禁止性约束（"请勿..."）
• 仅提供文件路径与签名，不包含完整代码