makemd/docs/RULES/documentation.md

文档规范标准

1. 目录命名规范

1.1 目录命名规则

类别	格式	示例	说明
主目录	中文或英文	docs/Business/	业务线/域
子目录	数字前缀+英文	docs/Business/01_Product/	模块序号
归档目录	ARCHIVE/	docs/ARCHIVE/	历史文档

1.2 目录大小写规则

• 全部使用小写：所有目录名必须使用小写字母
• 分隔符：使用 - 或 _，保持一致
• 示例：
  • ✅ docs/business/, docs/architecture/
  • ❌ docs/Business/, docs/ARCHIVE/

1.3 主目录结构

docs/
├── business/          # 业务文档
├── architecture/      # 架构文档
├── api/               # API文档
├── rules/             # 规范文档
├── tasks/             # 任务文档
├── loops/             # 业务闭环文档
└── services/          # 服务文档

2. 文件命名规范

2.1 命名规则

类别	格式	示例
索引文件	index.md	business/index.md
模块文档	NN_Name.md	01_Product.md
规范文档	kebab-case.md	code-quality-rules.md
报告文档	YYYY-MM-DD_Name.md	2026-03-20_Code_Review.md

2.2 文件后缀

• 统一使用 .md 后缀
• 禁止使用 .md_txt、.markdown 等变体

2.3 命名大小写

• 目录: 全部小写
• 文件: 首字母大写，驼峰命名（除非是 index.md）

3. 索引文件规范

3.1 索引文件命名

• 标准索引: index.md
• 禁止: _index.md、00_Index.md、INDEX.md

3.2 索引文件位置

• 每个目录必须有 index.md 作为入口
• 索引文件必须包含该目录内容的概览和链接

3.3 索引文件格式

# 模块名称

## 目录结构

- [子模块1](01_SubModule/) - 简短描述
- [子模块2](02_SubModule/) - 简短描述

## 内容概览

...

4. 文档格式规范

4.1 标题层级

# 一级标题 (页面标题)
## 二级标题 (主要章节)
### 三级标题 (子章节)
#### 四级标题 (细节内容)

4.2 代码块

```typescript
// 代码内容
const example = 'code';
```

4.3 表格格式

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容 | 内容 | 内容 |

5. 常见错误

5.1 已识别的格式错误

错误类型	错误示例	正确示例
大小写错误	ARCHIVE/00_Business/	archive/00_business/
索引文件命名	_index.md	index.md
文件后缀	document.md_txt	document.md
中文目录	文档/	documents/

5.2 需要修复的目录

当前路径	建议路径
docs/ARCHIVE/	docs/archive/
docs/LOOPS/	docs/loops/
docs/SERVICES/	docs/services/
docs/TASKS/	docs/tasks/
docs/RULES/	docs/rules/
docs/API_Documentations/	docs/api/

6. 迁移计划

阶段1：创建规范文件

• 创建 docs/rules/documentation.md

阶段2：识别需要迁移的目录

• 识别所有大小写不一致的目录
• 识别所有命名不规范的目录

阶段3：执行迁移（2026-03-26）

• 重命名目录为小写（archive, api, loops, rules, services, tasks）
• 更新所有相关引用

阶段4：验证

• 检查所有链接是否有效
• 验证文档结构完整性

7. 参考

• 项目术语表: TERMINOLOGY.md
• 业务闭环: loops/_index.md