name: 为大语言模型写作文档 description: 教导如何为大语言模型写作有效的文档和指令，通过假设能力、使用渐进披露、优先示例而非解释，并在工作流中构建反馈循环。 allowed-tools:

Read
Write
Grep

为大语言模型写作文档

指导如何创建大语言模型能够发现、理解并成功使用的文档和指令。

核心原则

假设能力

大语言模型已经非常智能。只添加模型不知道的信息。质疑每一部分：

“大语言模型真的需要这个解释吗？”
“我可以假设模型知道这个吗？”
“这值得它的令牌成本吗？”

冗长示例 (~150 令牌):

PDF（便携式文档格式）文件是一种常见的文件格式，包含
文本、图像和其他内容。要从PDF中提取文本，您需要
使用一个库。有许多可用于PDF处理的库...

简洁示例 (~50 令牌):

使用 pdfplumber 进行文本提取：
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

匹配任务脆弱性的特异性

狭窄指令（低自由度）：数据库迁移、破坏性操作、一致性关键任务
一般指导（高自由度）：代码审查、设计决策、上下文决定最佳路径的地方

跨模型测试

效果因模型而异。对Claude Opus有效的技能可能需要对Claude Haiku提供更多细节。

结构与渐进披露

像目录一样组织

主文件提供概述并指向详细材料。LLM仅在需要时读取额外文件。

模式:

主文件：高级指南，带有引用（< 500 行）
参考文件：每个领域或主题一个
保持引用一级深（避免链式：A → B → C）

示例结构:

my-doc/
├── OVERVIEW.md           # 高级指南
├── reference/
│   ├── api.md           # 具体参考
│   ├── examples.md      # 使用示例
│   └── troubleshooting.md
└── scripts/
    └── helper.py        # 可执行实用程序

长文件的目录

对于任何超过100行的文件，在顶部包括目录，以便LLM看到完整范围：

## 目录
- 认证与设置
- 核心方法（创建、读取、更新、删除）
- 高级功能
- 错误处理模式

一致的术语

每个概念选择一个术语并始终使用：

总是“API 端点”（而不是“URL”、“路由”、“路径”）
总是“字段”（而不是“框”、“元素”、“控件”）
总是“提取”（而不是“拉取”、“获取”、“检索”）

内容模式

描述：什么 + 何时

通过具体描述启用发现：

它做什么：具体能力
何时使用它：特定触发器和上下文

好例子:

从PDF文件中提取文本和表格，填写表单，合并文档。
当处理PDF文件或用户提及PDF、表单或文档提取时使用。

坏例子:

帮助处理文档

示例优先于解释

在抽象描述之前展示具体输入/输出：

## 生成提交消息

遵循这些示例：

**示例 1:**
输入：添加了用户认证与JWT令牌
输出：
feat(auth): 实现基于JWT的认证

添加登录端点和令牌验证中间件

明确步骤的工作流

将复杂操作分解为顺序步骤：

## 数据库迁移工作流

任务进度：
- [ ] 步骤 1：创建备份
- [ ] 步骤 2：运行迁移脚本
- [ ] 步骤 3：验证模式
- [ ] 步骤 4：验证数据完整性

关键任务的反馈循环

为质量关键工作使用验证器：

## 文档编辑过程

1. 进行编辑
2. **验证**：运行 `validate.py`
3. 如果验证失败：
   - 查看错误
   - 修复问题
   - 再次运行验证
4. **仅在验证通过时继续**
5. 最终化输出

条件工作流

引导LLM通过决策点：

## 修改工作流

1. 确定修改类型：
   - 创建新内容？ → 遵循“创建工作流”
   - 编辑现有内容？ → 遵循“编辑工作流”

2. 创建工作流：
   - 使用库 X
   - 从头构建
   - 导出格式 Y

3. 编辑工作流：
   - 解包现有文件
   - 修改内容
   - 完成时重新打包

可验证的中间输出

对于复杂任务，创建可验证的中间格式：

## 批量更新工作流

1. 创建计划文件（JSON 格式）
2. **验证计划**：运行 `validate_plan.py`
3. 如果验证通过，执行
4. 验证输出匹配计划

避免时间敏感信息

使用“旧模式”部分处理弃用方法：

## 当前方法

使用 v2 API 端点：`api.example.com/v2/messages`

## 旧模式

<details>
<summary>旧 v1 API（已弃用 2025-08）</summary>
v1 API 使用：`api.example.com/v1/messages`
</details>

反模式

过多选项

除非必要，不要呈现多种方法。

坏:

您可以使用 pypdf，或 pdfplumber，或 PyMuPDF，或 pdf2image，或...

好:

使用 pdfplumber 进行文本提取。

对于需要OCR的扫描PDF，使用 pdf2image 和 pytesseract。

深层嵌套引用

保持引用一级深。嵌套链（文件 A → 文件 B → 文件 C）会导致部分读取和错过上下文。

模糊触发术语

在描述中具体以启用发现：

模糊：帮助处理数据

具体：分析Excel电子表格，生成数据透视表，创建图表。当处理Excel文件、电子表格或.xlsx文件时使用。

Windows样式路径

始终使用正斜杠（Unix 样式）：

✓ 好：scripts/helper.py
✗ 错误：scripts\helper.py

测试与迭代

首先创建评估

在编写大量文档之前：

识别LLM在没有文档时工作的空白
创建3个以上的代表性测试用例
建立基准性能
编写最小文档以填补空白
基于结果测试和迭代

与Claude一起迭代开发

使用Claude在没有文档的情况下完成任务
识别可重用模式
请求Claude创建捕获该模式的文档
审查简洁性（移除Claude已经知道的解释）
在类似任务上用新实例测试文档
基于观察迭代

关键要点

有效的LLM文档假设智能，优先示例而非解释，为渐进发现组织，并验证关键工作流。用目标模型测试并根据真实使用模式迭代。