
关于
文档模板和结构指南。README、API 文档、代码注释和 AI 友好文档。
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. 结构原则
| 原则 | 原因 | |-----------|-----| | 可扫描 | 标题、列表、表格 | | 示例优先 | 展示,而不仅仅是说明 | | 渐进式细节 | 简单 → 复杂 | | 保持更新 | 过时 = 误导 |
记住: 模板是起点。根据项目需求进行调整。
适用场景
此技能适用于执行概述中描述的工作流或操作。
限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为特定环境验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准,请停下来要求澄清。
兼容工具
Claude CodeCursor
标签
后端开发
