name: 为大型语言模型编写文档 description: 创建有效的文档，以便LLMs能够发现和使用。当记录代码、API、特性或创建参考材料时使用。涵盖结构、简洁性、示例以及最佳实践，以优化LLM理解。
为大型语言模型编写文档
何时使用
- 创建文档、指南或参考材料
- 编写API文档、特性规格或知识库
- 结构化信息以便LLM发现
- 评估文档质量和全面性
核心原则
假设能力
LLMs已经知道基础内容。只添加他们不知道的信息。每个部分都应证明其token成本是值得的。
冗长 (~150 tokens):
PDF（便携式文档格式）文件是一种常见的文件格式，包含文本、图像和其他内容。要从PDF中提取文本，你需要使用一个库。有许多库可用于PDF处理...
简洁 (~50 tokens):
使用pdfplumber进行文本提取：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
### 根据任务脆弱性匹配特异性
**狭窄指令**（低自由度）当：
- 操作容易出错或具有破坏性
- 一致性至关重要
- 需要确切的顺序
**一般指导**（高自由度）当：
- 多种方法都有效
- 上下文决定最佳路径
- 启发式指导方法
## 结构最佳实践
### 渐进披露
像目录一样组织。主文件提供概述；详细材料仅在需要时引用。
- 主文件：高级指南带引用（<500行）
- 参考文件：每个域/主题一个文件
- 避免嵌套引用（文件A → B → C）
### 目录
对于超过100行的文件，包括目录，以便LLMs即使在部分读取时也能看到完整范围。
### 一致术语
选择一个术语并始终使用：
- 总是"API端点"（不是"URL"、"route"、"path"）
- 总是"字段"（不是"box"、"element"）
- 总是"提取"（不是"pull"、"get"）
## 内容模式
### 描述：什么 + 何时
通过具体能力 + 上下文启用发现：
**好**："从PDF文件中提取文本和表格，填写表单，合并文档。当处理PDF文件或用户提到PDF、表单或文档提取时使用。"
**差**："帮助处理文档"
### 示例优先于解释
在抽象描述之前展示具体输入/输出示例。
### 明确步骤的工作流
将复杂操作分解为顺序步骤。对于复杂工作流使用检查表。
### 反馈循环
对于质量关键任务使用验证器模式：
1. 进行编辑
2. **验证** — 运行验证
3. 如果验证失败 — 审查、修复、重试
4. **只有在验证通过时才继续**
## 要避免的反模式
- **太多选项**：呈现单一推荐方法，仅在必要时提供替代方案
- **深度嵌套引用**：保持从主文件深度为一级
- **模糊术语**：使用具体、可发现的词汇
- **Windows风格路径**：始终使用正斜杠（例如，`scripts/helper.py`）
- **时间敏感信息**：使用"旧模式"部分，详细内容折叠