name: documentation-templates description: 文档模板和结构指南。包括README、API文档、代码注释和AI友好型文档。 allowed-tools: Read, Glob, Grep
文档模板
常见文档类型的模板和结构指南。
1. README结构
基本部分（优先级顺序）
| 部分 | 目的 |
|---|---|
| 标题 + 一句话描述 | 这是什么？ |
| 快速开始 | 在5分钟内运行 |
| 功能 | 我能做什么？ |
| 配置 | 如何自定义 |
| API参考 | 链接到详细文档 |
| 贡献 | 如何帮助 |
| 许可证 | 法律信息 |
README模板
# 项目名称
简短的一句话描述。
## 快速开始
[运行的最小步骤]
## 功能
- 功能 1
- 功能 2
## 配置
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| PORT | 服务器端口 | 3000 |
## 文档
- [API参考](./docs/api.md)
- [架构](./docs/architecture.md)
## 许可证
MIT
2. API文档结构
每个端点的模板
## GET /users/:id
通过ID获取用户。
**参数:**
| 名称 | 类型 | 必需 | 描述 |
|------|------|----------|-------------|
| id | 字符串 | 是 | 用户ID |
**响应:**
- 200: 用户对象
- 404: 用户未找到
**示例:**
[请求和响应示例]
3. 代码注释指南
JSDoc/TSDoc模板
/**
* 函数功能的简短描述。
*
* @param 参数名 - 参数描述
* @returns 返回值描述
* @throws 错误类型 - 当发生此错误时
*
* @example
* const result = 函数名(输入);
*/
何时注释
| ✅ 注释 | ❌ 不注释 |
|---|---|
| 为什么（业务逻辑） | 什么（显而易见） |
| 复杂算法 | 每一行 |
| 非明显行为 | 自解释的代码 |
| API合约 | 实现细节 |
4. 更新日志模板（保持更新日志）
# 更新日志
## [未发布]
### 新增
- 新功能
## [1.0.0] - 2025-01-01
### 新增
- 初始发布
### 更改
- 更新的依赖
### 修复
- 错误修复
5. 架构决策记录 (ADR)
# ADR-001: [标题]
## 状态
已接受 / 已弃用 / 已替代
## 上下文
为什么做出这个决定？
## 决策
我们决定了什么？
## 后果
权衡是什么？
6. AI友好型文档 (2025)
llms.txt模板
为AI爬虫和代理准备：
# 项目名称
> 一句话目标。
## 核心文件
- [src/index.ts]: 主入口
- [src/api/]: API路由
- [docs/]: 文档
## 关键概念
- 概念 1: 简短解释
- 概念 2: 简短解释
MCP就绪文档
为RAG索引准备：
- 清晰的H1-H3层次结构
- JSON/YAML示例用于数据结构
- Mermaid图表用于流程
- 自包含的部分
7. 结构原则
| 原则 | 为什么 |
|---|---|
| 可扫描 | 标题、列表、表格 |
| 示例优先 | 展示，而不只是告诉 |
| 渐进式细节 | 简单 → 复杂 |
| 保持更新 | 过时 = 误导 |
记住： 模板是起点。根据项目需求调整。