kscz0000 文档模板
常见文档类型的模板与结构指南。
1. README 结构
核心章节（按优先级排序）
| 章节 | 目的 |
|---|---|
| 标题 + 一句话简介 | 这是什么？ |
| 快速开始 | 5分钟内运行起来 |
| 功能特性 | 能做什么？ |
| 配置说明 | 如何自定义 |
| API 参考 | 详细文档链接 |
| 贡献指南 | 如何参与 |
| 许可证 | 法律信息 |
README 模板
# 项目名称
简短的一句话描述。
## 快速开始
[运行的最少步骤]
## 功能特性
- 功能 1
- 功能 2
## 配置说明
| 变量 | 描述 | 默认值 |
|------|------|--------|
| PORT | 服务器端口 | 3000 |
## 文档
- API 参考
- 架构说明
## 许可证
MIT
2. API 文档结构
端点文档模板
## GET /users/:id
根据 ID 获取用户。
**参数：**
| 名称 | 类型 | 必填 | 描述 |
|------|------|------|------|
| id | string | 是 | 用户 ID |
**响应：**
- 200: 用户对象
- 404: 用户不存在
**示例：**
[请求和响应示例]
3. 代码注释指南
JSDoc/TSDoc 模板
/**
* 函数功能的简短描述。
*
* @param paramName - 参数描述
* @returns 返回值描述
* @throws ErrorType - 何时抛出此错误
*
* @example
* const result = functionName(input);
*/
何时添加注释
| ✅ 应该注释 | ❌ 不应注释 |
|---|---|
| 为什么（业务逻辑） | 是什么（显而易见） |
| 复杂算法 | 每一行代码 |
| 非显而易见的行为 | 自解释的代码 |
| API 契约 | 实现细节 |
4. 变更日志模板（Keep a Changelog）
# 变更日志
## [未发布]
### 新增
- 新功能
## [1.0.0] - 2025-01-01
### 新增
- 初始版本
### 变更
- 更新依赖
### 修复
- Bug 修复
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. 结构原则
| 原则 | 原因 |
|---|---|
| 可扫描 | 使用标题、列表、表格 |
| 示例优先 | 展示而非仅讲述 |
| 渐进细节 | 简单 → 复杂 |
| 保持更新 | 过时 = 误导 |
记住： 模板只是起点。根据项目需求进行调整。
使用时机
本技能适用于执行概述中描述的工作流程或操作。
限制
- 仅当任务明确符合上述范围时使用本技能。
- 输出内容不能替代特定环境的验证、测试或专家评审。
- 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。