# Documentation Templates

> 文档模板与结构指南。涵盖 README、API 文档、代码注释以及 AI 友好型文档。

- Skill: `kscz0000/documentation-templates` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/documentation-templates`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/documentation-templates/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/documentation-templates

---


# 文档模板

> 常见文档类型的模板与结构指南。

---

## 1. README 结构

### 核心章节（按优先级排序）

| 章节 | 目的 |
|------|------|
| **标题 + 一句话简介** | 这是什么？ |
| **快速开始** | 5分钟内运行起来 |
| **功能特性** | 能做什么？ |
| **配置说明** | 如何自定义 |
| **API 参考** | 详细文档链接 |
| **贡献指南** | 如何参与 |
| **许可证** | 法律信息 |

### README 模板

```markdown
# 项目名称

简短的一句话描述。

## 快速开始

[运行的最少步骤]

## 功能特性

- 功能 1
- 功能 2

## 配置说明

| 变量 | 描述 | 默认值 |
|------|------|--------|
| PORT | 服务器端口 | 3000 |

## 文档

- API 参考
- 架构说明

## 许可证

MIT
```

---

## 2. API 文档结构

### 端点文档模板

```markdown
## GET /users/:id

根据 ID 获取用户。

**参数：**
| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| id | string | 是 | 用户 ID |

**响应：**
- 200: 用户对象
- 404: 用户不存在

**示例：**
[请求和响应示例]
```

---

## 3. 代码注释指南

### JSDoc/TSDoc 模板

```typescript
/**
 * 函数功能的简短描述。
 * 
 * @param paramName - 参数描述
 * @returns 返回值描述
 * @throws ErrorType - 何时抛出此错误
 * 
 * @example
 * const result = functionName(input);
 */
```

### 何时添加注释

| ✅ 应该注释 | ❌ 不应注释 |
|-----------|-----------|
| 为什么（业务逻辑） | 是什么（显而易见） |
| 复杂算法 | 每一行代码 |
| 非显而易见的行为 | 自解释的代码 |
| API 契约 | 实现细节 |

---

## 4. 变更日志模板（Keep a Changelog）

```markdown
# 变更日志

## [未发布]
### 新增
- 新功能

## [1.0.0] - 2025-01-01
### 新增
- 初始版本
### 变更
- 更新依赖
### 修复
- Bug 修复
```

---

## 5. 架构决策记录（ADR）

```markdown
# ADR-001: [标题]

## 状态
已采纳 / 已弃用 / 已取代

## 背景
为什么要做这个决策？

## 决策
我们决定了什么？

## 影响
有哪些权衡取舍？
```

---

## 6. AI 友好型文档（2025）

### llms.txt 模板

面向 AI 爬虫和智能体：

```markdown
# 项目名称
> 一句话目标。

## 核心文件
- [src/index.ts]: 主入口
- [src/api/]: API 路由
- [docs/]: 文档

## 核心概念
- 概念 1: 简要说明
- 概念 2: 简要说明
```

### MCP 就绪文档

面向 RAG 索引：
- 清晰的 H1-H3 层级结构
- 数据结构使用 JSON/YAML 示例
- 流程使用 Mermaid 图表
- 章节自包含

---

## 7. 结构原则

| 原则 | 原因 |
|------|------|
| **可扫描** | 使用标题、列表、表格 |
| **示例优先** | 展示而非仅讲述 |
| **渐进细节** | 简单 → 复杂 |
| **保持更新** | 过时 = 误导 |

---

> **记住：** 模板只是起点。根据项目需求进行调整。

## 使用时机
本技能适用于执行概述中描述的工作流程或操作。

## 限制
- 仅当任务明确符合上述范围时使用本技能。
- 输出内容不能替代特定环境的验证、测试或专家评审。
- 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。