# Dev Docs Generate

> 开发文档生成规范，快速生成开发文档，自动放到docs目录下，方便技术快速了解项目，能快速入手开发

- Skill: `crmeb/dev-docs-generate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add crmeb/dev-docs-generate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crmeb/dev-docs-generate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: crmeb (https://skillmd.com/u/crmeb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/crmeb/dev-docs-generate

---


# CRMEB 项目文档写作规范

## 0. 自动调用场景

### 0.1 触发条件

- **目录浏览时**：当浏览文档相关目录时自动调用
  - 打开 `dev-docs/` 目录时触发
  - 打开 `dev-docs/phpapi/` 目录时触发
  - 打开 `dev-docs/admin/` 目录时触发
  - 打开 `dev-docs/uniapp/` 目录时触发
  - 打开 `dev-docs/nuxt/` 目录时触发
- **文档创建时**：当创建新的 Markdown 文档文件时自动调用
- **文档编辑时**：当编辑现有文档文件时自动调用
- **关键词触发**：当文档内容包含以下关键词时自动调用
  - `文档`、`说明`、`指南`、`手册`、`规范`
  - `API`、`接口`、`部署`、`开发`、`需求`

### 0.2 适用文件类型

- `.md` (Markdown 文件)
- `.txt` (文本文件)
- `.doc`/`.docx` (Word 文档)
- `.pdf` (PDF 文档)

### 0.3 调用优先级

- 当多个技能同时触发时，文档规范技能优先级中等
- 仅在文档相关操作时被触发
- 不影响其他技能的正常使用

## 1. 文档类型

### 1.1 技术文档

- **API 文档**：接口设计、参数说明、返回格式
- **开发文档**：架构设计、模块说明、开发流程
- **部署文档**：环境要求、安装步骤、配置说明
- **接口文档**：接口列表、请求参数、返回示例

### 1.2 业务文档

- **需求文档**：功能描述、业务流程、数据结构
- **测试文档**：测试用例、测试结果、缺陷报告
- **用户手册**：功能介绍、操作指南、常见问题

## 2. 格式规范

### 2.1 文件名规范

- 使用小写下划线分隔
- 清晰描述文档内容
- 示例：`api接口文档.md`、`部署指南.md`

### 2.2 标题层级

- 使用 `#` 表示标题层级
- 一级标题：文档主题
- 二级标题：主要章节
- 三级标题：细分内容
- 最多使用四级标题

### 2.3 文本格式

- 正文使用宋体/无衬线字体，14px
- 代码块使用 ``` 包裹，指定语言
- 列表使用 `-` 或 `1.` 表示
- 强调内容使用 `**加粗**` 或 `*斜体*`

### 2.4 代码规范

- 代码块必须指定语言
- 缩进一致，格式清晰
- 关键代码添加注释
- 示例：
  ```php
  // 获取用户信息
  public function getUserInfo($id) {
      return $this->where('id', $id)->find();
  }
  ```

### 2.5 文档存放目录

- 文档保存到 `dev-docs` 目录中
- 后端接口文档存放 `dev-docs/phpapi` 目录中
- 后端前端 ElementUI（Admin）文档存放 `dev-docs/admin` 目录中
- 移动端前端 UniApp（移动端）文档存放 `dev-docs/uniapp` 目录中
- PC 端 Nuxt（PC）文档存放 `dev-docs/nuxt` 目录中

## 3. 内容要求

### 3.1 结构清晰

- 引言：文档目的、适用范围
- 主体：详细内容，逻辑连贯
- 结论：总结、后续计划
- 附录：参考资料、术语表

### 3.2 语言要求

- 使用简洁、准确的语言
- 避免歧义，术语统一
- 中文文档使用规范汉字
- 英文文档语法正确

### 3.3 内容完整性

- 包含必要的背景信息
- 步骤清晰，可操作
- 提供示例和截图
- 注明版本和更新日期

### 3.4 可维护性

- 定期更新，保持时效性
- 使用版本控制管理文档
- 注明作者和联系方式
- 便于搜索和导航

## 4. 文档工具

### 4.1 编辑工具

- 推荐使用 Markdown 格式
- 支持工具：VS Code、Typora、语雀
- 图片存储：项目内部或图床

### 4.2 版本管理

- 与代码一同纳入 Git 管理
- 提交信息清晰，说明文档变更
- 定期备份，防止丢失

## 5. 审核与发布

### 5.1 审核流程

1. 编写完成后进行自我检查
2. 提交给相关人员审核
3. 根据反馈修改完善
4. 最终确认发布

### 5.2 发布规范

- 发布前检查格式和内容
- 明确文档版本号
- 通知相关人员文档更新
- 确保文档可访问

## 6. Markdown 文档模板

```markdown
# 文档标题

## 1. 引言

### 1.1 文档目的
- 说明文档的编写目的

### 1.2 适用范围
- 说明文档的适用范围

### 1.3 术语定义
- 解释文档中使用的专业术语

## 2. 主体内容

### 2.1 功能描述
- 详细描述功能特性

### 2.2 实现方案
- 说明技术实现方案

### 2.3 代码示例

```php
// 代码示例
function example() {
    return true;
}
```

### 2.4 操作步骤

1. 第一步操作
2. 第二步操作
3. 第三步操作

## 3. 结论

### 3.1 总结
- 总结文档的主要内容

### 3.2 后续计划
- 说明后续的工作计划

## 4. 附录

### 4.1 参考资料
- 列出参考的文档和资源

### 4.2 联系方式
- 提供联系人信息

---

**版本**: 1.0
**作者**: 文档作者
**更新日期**: YYYY-MM-DD
```

## 7. Markdown 语法指南

### 7.1 标题

```markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
```

### 7.2 列表

- 无序列表项 1
- 无序列表项 2
  - 嵌套列表项

1. 有序列表项 1
2. 有序列表项 2

### 7.3 链接和图片

- [链接文本](https://example.com)
- ![图片描述](https://example.com/image.jpg)

### 7.4 代码块

```javascript
// JavaScript 代码
console.log('Hello World');
```

### 7.5 表格

| 表头 1 | 表头 2 |
| ------ | ------ |
| 单元格 1 | 单元格 2 |
| 单元格 3 | 单元格 4 |

### 7.6 引用

> 这是一段引用文本

## 8. 注意事项

- 避免冗长，重点突出
- 保持格式统一
- 定期更新文档
- 确保内容准确无误
- 便于他人理解和使用
- 生成文档最后说明由AI生成

---

以上规范适用于 CRMEB 项目所有文档写作，确保文档质量和一致性。