mcpField
D
documentation-templates

documentation-templates

github.com/vudovn开发8.2k188 次安装10 周前更新
代码仓库

关于 documentation-templates

面向开发者的文档模板与结构指南，涵盖 README、API 文档、代码注释、变更日志和 ADR，并包含适用于 AI 爬虫与 RAG 的文档建议。

主要功能

  1. 01README 结构与模板
  2. 02API 端点文档模板
  3. 03JSDoc/TSDoc 注释指南
  4. 04变更日志与 ADR 模板
  5. 05AI 友好文档规范

适用场景

  1. 01为新项目编写 README
  2. 02统一 API 端点说明
  3. 03记录代码注释与架构决策

MCP 相关

提供面向 RAG 索引的 MCP 就绪文档建议，包括清晰的标题层级、数据示例和流程图。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vudovn/ag-kit --skill documentation-templates

安装后在 Claude Code 中输入/documentation-templates确认已加载。

详细介绍

文档模板

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

1. README 结构

必要章节（优先级顺序）
章节用途
标题 + 一句话简介这是什么？
快速入门在 5 分钟内运行
功能可以做什么？
配置如何自定义
API 参考详细文档链接
贡献如何参与
许可证法律信息
README 模板
# Project Name

Brief one-line description.

## Quick Start

[Minimum steps to run]

## Features

- Feature 1
- Feature 2

## Configuration

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

## Documentation

- [API Reference](./docs/api.md)
- [Architecture](./docs/architecture.md)

## License

MIT

2. API 文档结构

单个端点模板
## GET /users/:id

Get a user by ID.

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

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

**Example:**
[Request and response 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 使用的文档

llms.txt 模板

面向 AI 爬虫和 Agent：

# 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. 结构原则

原则原因
便于浏览标题、列表、表格
示例优先展示，而不只是描述
循序渐进简单 → 复杂
保持最新过时内容 = 误导

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

评论

支持 Markdown