---

name: documentation-templates description: "文档模板和结构指南。README、API 文档、代码注释和 AI 友好文档。" risk: safe source: community date_added: "2026-02-27"

文档模板

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

---

1. README 结构

必要章节（优先级排序）

| 章节 | 用途 | |---------|---------| | 标题 + 一句话描述 | 这是什么？ | | 快速开始 | 5 分钟内运行 | | 功能 | 我能做什么？ | | 配置 | 如何自定义 | | API 参考 | 链接到详细文档 | | 贡献 | 如何帮助 | | 许可证 | 法律 |

README 模板

# Project Name

简短的一行描述。

## Quick Start

[运行的最少步骤]

## Features

- 功能 1
- 功能 2

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |

## Documentation

- API Reference
- Architecture

## License

MIT

---

2. API 文档结构

每个端点模板

## GET /users/:id

通过 ID 获取用户。

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

**Response:**
- 200: User object
- 404: User not found

**Example:**
[请求和响应示例]

---

3. 代码注释指南

JSDoc/TSDoc 模板

/**
 * Brief description of what the function does.
 * 
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws ErrorType - When this error occurs
 * 
 * @example
 * const result = functionName(input);
 */

何时添加注释

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

---

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

# Changelog

## [Unreleased]
### Added
- New feature

## [1.0.0] - 2025-01-01
### Added
- Initial release
### Changed
- Updated dependency
### Fixed
- Bug fix

---

5. 架构决策记录（ADR）

# ADR-001: [Title]

## Status
Accepted / Deprecated / Superseded

## Context
Why are we making this decision?

## Decision
What did we decide?

## Consequences
What are the trade-offs?

---

6. AI 友好文档（2025）

llms.txt 模板

用于 AI 爬虫和代理：

# Project Name
> One-line objective.

## Core Files
- [src/index.ts]: Main entry
- [src/api/]: API routes
- [docs/]: Documentation

## Key Concepts
- Concept 1: Brief explanation
- Concept 2: Brief explanation

MCP 就绪文档

用于 RAG 索引：

• 清晰的 H1-H3 层次结构
• 数据结构的 JSON/YAML 示例
• 流程的 Mermaid 图表
• 自包含的章节

---

7. 结构原则

| 原则 | 原因 | |-----------|-----| | 可扫描 | 标题、列表、表格 | | 示例优先 | 展示，而不仅仅是说明 | | 渐进式细节 | 简单 → 复杂 | | 保持更新 | 过时 = 误导 |

---

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

适用场景

此技能适用于执行概述中描述的工作流或操作。

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为特定环境验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停下来要求澄清。