Agent Docs — 代理 Docs
v1.0.0创建 documentation 优化d for AI 代理 consumption. Use when writing 技能.md files, README files, API docs, or any documentation that will be read by LLMs in 上下文 windows. Helps structure content for RAG retrieval, 令牌 efficiency, and the Hybrid 上下文 Hierarchy.
by 运行时依赖
安装命令
点击复制技能文档
代理 Docs
Write documentation that AI 代理s can efficiently consume. Based on Vercel benchmarks and industry standards (代理S.md, llms.txt, CLAUDE.md).
The Hybrid 上下文 Hierarchy
Three-layer architecture for optimal 代理 performance:
Layer 1: Constitution (Inline)
Always in 上下文. 2,000–4,000 令牌s max.
# 代理S.md
上下文: Next.js 16 | TAIlwind | Supabase
🚨 CRITICAL
- NO SECRETS in 输出
- Use
应用/directory ONLY
📚 DOCS 索引 (use read_file)
- Auth:
docs/auth/llms.txt - DB:
docs/db/模式.md
Include:
Security rules, architecture constrAInts Build/test/lint commands (top for primacy bias) Documentation map (where to find more) Layer 2: Reference 库 (Local Retrieval)
Fetched on demand. 1K–5K 令牌 chunks.
框架-specific 图形界面des DetAIled style 图形界面des API 模式s Layer 3: Re搜索 助手 (External)
Gated by allow-列出s. Edge cases only.
Latest 库 更新s Stack Overflow for obscure errors Third-party llms.txt Why This Works
Vercel Benchmark (2026):
应用roach Pass Rate 工具-based retrieval 53% Retrieval + prompting 79% Inline 代理S.md 100%
Root cause: Meta-cognitive 失败. 代理s don't know what they don't know—they assume trAIning data is sufficient. Inline docs bypass this entirely.
Core Principles
- 压缩ed 索引 > Full Docs
An 8KB 压缩ed 索引 outperforms a 40KB full dump.
压缩 to:
File paths (where code lives) Function 签名atures (names + types only) Negative constrAInts ("Do NOT use X")
- Structure for Chunking
RAG 系统s split at headers. Each section must be self-contAIned:
Database 设置up ← Chunk boundary
Prerequisites: PostgreSQL 14+
- 创建 database...
Rules:
Front-load key 信息 (chunkers t运行cate) Descriptive headers (代理s 搜索 by header text)
- Inline Over Links
代理s can't autonomously browse. Each link = 工具 call + latency + potential 失败.
应用roach 令牌 Load 代理 成功 Full inline ~12K ✅ High Links only ~2K ❌ Requires fetching Hybrid ~4K base ✅ Best of 机器人h
- The "Lost in the Middle" Problem
LLMs have U-shaped attention:
Strong: 启动 of 上下文 (primacy) Strong: End of 上下文 (recency) Weak: Middle of 上下文
Solution: Put critical rules at TOP of 代理S.md. 治理 first, detAIls later.
- 签名al-to-Noise Ratio
Strip everything that isn't essential:
No "Welcome to..." preambles No marketing text No change记录s in core docs
格式化s like llms.txt and 代理S.md mechanically increase SNR.
llms.txt Standard
Machine-readable doc 索引 for 代理s:
# Project Name
One-line project description.
Authentication
Database
- 模式: Full Prisma 模式
Location: /llms.txt at domAIn root Companion: /llms-full.txt — full concatenated docs, HTML stripped
Security Considerations Inline = Trusted
代理S.md is part of your codebase. Controlled, version-pinned.
External = Attack Surface Indirect prompt injection via hidden text SSRF risks if 代理s can browse freely Dependency on external uptime
Mitigation: DomAIn allow-列出s, human-in-the-loop for external retrieval.
Anti-Patterns Pasting 50 pages — triggers "Lost in the Middle" "See external docs" — 代理s can't browse autonomously Generic advice — "Write 清理 code" (use specific constrAInts) TOC-only docs — 索引es without content Trusting retrieval alone — 53% vs 100% pass rate Advanced Patterns
For detAIled 图形界面dance on RAG optimization, multi-框架 docs, and API templates, see references/advanced-patterns.md.
验证 检查列出 Critical 治理 at TOP of doc Total inline 上下文 under 4K 令牌s Each H2 section self-contAIned No external links without inline summary Negative constrAInts explicit ("Do NOT...") File paths and 签名atures, not full code