reference-documentation

参考文档

创建全面、易于搜索且组织精确的技术参考文档，作为 API、配置和系统接口的权威信息来源。

何时使用此技能

• 编写 API 参考文档（REST、GraphQL、gRPC）
• 创建完整记录每个参数的配置指南
• 编写数据库或数据模型的架构文档
• 编写包含所有命令、标志和示例的 CLI 参考文档
• 生成完整的技术规范
• 记录错误代码、状态代码和异常目录
• 创建版本升级迁移指南

快速参考

资源	用途	何时加载
references/documentation-patterns.md	API 文档结构、术语表模式、交叉引用、版本化文档、参数表、配置指南	组织任何参考文档时

---

工作流概览

Phase 1: Inventory    → Catalog all public interfaces, parameters, and constraints
Phase 2: Author       → Draft structured entries with examples and cross-links
Phase 3: Verify       → Validate against implementation and tests
Phase 4: Organize     → Structure for optimal retrieval and searchability
Phase 5: Maintain     → Version tracking, deprecation, and update cadence

---

阶段 1：盘点

开始编写前，列出所有需要记录的内容。

盘点清单

• 所有公开 API 端点／方法／函数
• 所有配置参数及其默认值
• 所有错误代码和异常类型
• 所有环境变量
• 所有 CLI 命令和标志
• 所有架构字段和约束
• 所有事件类型和有效负载
• 已移除功能的弃用时间线

信息来源优先级

1. 实现代码（实际行为）
2. 测试（带断言的预期行为）
3. 类型定义／架构（声明的契约）
4. 现有文档（可能已过时，需核实）

---

阶段 2：编写

条目格式

每个记录的条目都采用一致的结构：

### methodName

**Type**: `(param1: string, param2?: number) => Promise<Result>`
**Since**: v2.1.0
**Deprecated**: No

**Description**:
Brief explanation of purpose and behavior.

**Parameters**:

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | What this parameter controls |
| `param2` | `number` | No | `10` | What this parameter controls |

**Returns**: `Promise<Result>` — description of return value

**Throws**:
- `ValidationError` — when param1 is empty
- `TimeoutError` — when operation exceeds 30s

**Examples**:

Basic usage:
\`\`\`typescript
const result = await methodName("value");
\`\`\`

With options:
\`\`\`typescript
const result = await methodName("value", 20);
\`\`\`

**See Also**: [relatedMethod](#relatedmethod), [Configuration Guide](#configuration)

编写规则

1. 记录行为，而非实现方式——说明它的作用，而非实现方法
2. 每个参数都要有一行——无一例外，即使参数显而易见也一样
3. 每个条目都要有示例——至少提供一个可运行的代码示例
4. 明确说明约束——有效范围、长度限制、格式要求
5. 交叉引用相关条目——链接到相关方法、配置和错误代码

---

阶段 3：验证

验证方法

验证内容	方法
方法签名	与源代码类型定义进行比较
默认值	检查源代码中的初始化值
错误条件	阅读实现代码和测试断言
示例	运行示例，或根据代码追踪验证
已弃用条目	检查源代码中的弃用标记

准确性清单

• 所有签名都与当前实现一致
• 所有默认值都准确无误
• 所有错误条件都有记录
• 所有示例都能在当前版本中运行
• 没有继续记录已移除的功能
• 所有新功能都已记录

---

阶段 4：组织

文档层级

1. Overview          — What this API/system does, quick orientation
2. Quick Reference   — Cheat sheet of common operations with examples
3. Authentication    — How to authenticate (if applicable)
4. Detailed Reference — Complete documentation, grouped logically
5. Error Reference   — All error codes with causes and fixes
6. Glossary          — Terms specific to this system
7. Changelog         — What changed in each version

导航辅助

• 目录，置于顶部并提供深层链接
• 字母索引，用于大型参考文档集
• 按类别分组，便于按逻辑查找
• 在标题和说明中嵌入搜索关键词
• 为近期版本新增或变更的条目添加版本徽章

---

阶段 5：维护

版本策略

• 为每个条目标注其引入版本（**Since**: v2.1.0）
• 标记弃用内容并提供迁移指引（**Deprecated**: v3.0 — use newMethod instead）
• 在参考文档底部维护变更日志部分
• 重大变更累积时，按主版本拆分文档

更新触发条件

出现以下情况时，必须更新参考文档：

• 公开 API 签名发生变化
• 添加新的参数、端点或命令
• 默认值或约束发生变化
• 功能被弃用或移除
• 错误代码或行为发生变化

---

内容模式

参数表

参数始终使用表格，切勿使用行内列表：

名称	类型	必填	默认值	描述
timeout	number	否	30000	请求超时时间，单位为毫秒
retries	number	否	3	重试次数

状态码表

代码	名称	描述	解决方法
400	错误请求	输入参数无效	根据架构检查请求正文
401	未授权	缺少或无效的身份验证令牌	重新进行身份验证并重试
429	请求过多	请求过多	等待一段时间，并在 Retry-After 标头指定的时间后重试

配置块

# config.yaml
server:
  port: 3000          # Port to listen on (1024-65535)
  host: "0.0.0.0"     # Bind address
  timeout: 30000      # Request timeout in ms
  max_body_size: "1mb" # Maximum request body size

反模式

• 记录可能在未通知的情况下发生变化的内部／私有接口
• 使用“显而易见”或“不言自明”代替真正的描述
• 因为“类型已经说明得很清楚”而省略错误文档
• 未经验证示例仍可运行就直接复制粘贴
• 在参考条目中混入教程式叙述（应将两者分开）
• 文档更新落后于实现超过一个版本