74 lines
2.3 KiB
Markdown
74 lines
2.3 KiB
Markdown
---
|
|
name: documentation
|
|
version: 1.0.0
|
|
description: "生成并更新项目文档。当需要撰写技术文档、README、API 文档或架构决策记录时使用。"
|
|
---
|
|
|
|
# Documentation Generator
|
|
|
|
## 触发条件
|
|
|
|
用户要求创建、更新或改进项目文档。
|
|
|
|
## 执行流程
|
|
|
|
### 1. 确定文档类型
|
|
|
|
| 类型 | 输出位置 | 模板来源 |
|
|
|------|---------|---------|
|
|
| PRD | `docs/vision/PRD.md` | 已有模板，直接填写 |
|
|
| README | `README.md` | 项目概述 + 安装 + 使用 |
|
|
| API 文档 | `docs/architecture/api-contracts.md` | 端点 + 请求/响应 |
|
|
| 架构文档 | `docs/architecture/system-design.md` | 已有模板，直接填写 |
|
|
| 数据模型 | `docs/architecture/data-model.md` | 已有模板，直接填写 |
|
|
| ADR | `docs/architecture/decisions/NNN-*.md` | 复制 `_template.md` 后填写 |
|
|
| 组件文档 | JSDoc / Storybook | Props + 示例 |
|
|
| 变更日志 | `CHANGELOG.md` | Conventional Changelog |
|
|
|
|
> **模板路径**: 创建 ADR 时，先读取 `docs/architecture/decisions/_template.md` 作为基础。
|
|
> PRD、架构文档、数据模型已在 `docs/` 下有完整模板，优先填充而非重新创建。
|
|
|
|
### 2. 收集上下文
|
|
|
|
1. 读取相关源码理解功能
|
|
2. 读取已有文档确认风格
|
|
3. 读取 `package.json` 获取项目信息
|
|
4. 读取 `docs/guides/style-guide.md` 确认文档规范
|
|
|
|
### 3. 生成文档
|
|
|
|
遵循以下写作原则：
|
|
- **简明**：一句话说清楚，不要冗余描述
|
|
- **可执行**：代码示例必须可运行
|
|
- **可维护**：避免写死版本号和路径
|
|
- **受众明确**：新人 onboarding vs 日常参考 vs 架构决策
|
|
|
|
### 4. ADR 创建流程
|
|
|
|
1. 复制模板：`docs/architecture/decisions/_template.md` → `docs/architecture/decisions/NNN-title.md`
|
|
2. 替换 `XXX` 为递增编号（检查已有 ADR 文件确定下一个编号）
|
|
3. 填写所有章节：状态、上下文（含问题陈述和约束）、决策、备选方案、理由、影响
|
|
4. 标注记录人和审核人
|
|
|
|
### 5. JSDoc 规范
|
|
|
|
```typescript
|
|
/**
|
|
* 一句话描述。
|
|
*
|
|
* @param paramName - 参数说明
|
|
* @returns 返回值说明
|
|
* @throws {ErrorType} 何时抛出
|
|
*
|
|
* @example
|
|
* const result = functionName('input');
|
|
*/
|
|
```
|
|
|
|
## 验证
|
|
|
|
1. [ ] 文档无拼写错误
|
|
2. [ ] 代码示例可运行
|
|
3. [ ] 链接有效
|
|
4. [ ] 遵循项目文档风格
|