191 lines
3.8 KiB
Markdown
191 lines
3.8 KiB
Markdown
# 文档编写规范
|
||
|
||
**状态**：已确定
|
||
**最后更新**：2025-01-28
|
||
|
||
---
|
||
|
||
## 一、核心原则
|
||
|
||
### 1.1 抽象与实现分离
|
||
- **设计文档**：描述"做什么"和"为什么"，不描述"怎么做"
|
||
- **实现细节**：在代码中体现，不在设计文档中详细描述
|
||
|
||
### 1.2 问题与知识分离
|
||
- **问题**：待讨论、待解决的问题 → [问题追踪/](../../问题追踪/)
|
||
- **知识**：已确定、已验证的知识 → [知识库/](./)
|
||
|
||
### 1.3 确定性先行
|
||
- **约束优先**：先明确约束和规则，再讨论具体实现
|
||
- **决策记录**：所有重要决策都要记录在 [决策记录/](../../决策记录/)
|
||
|
||
---
|
||
|
||
## 二、文档分类
|
||
|
||
### 2.1 知识库文档
|
||
**位置**：`知识库/`
|
||
**特点**：
|
||
- 已确定、已验证的内容
|
||
- 可被其他文档引用
|
||
- 需要定期维护
|
||
|
||
**分类**：
|
||
- `规范/` - 约束和规则
|
||
- `参考/` - 技术参考
|
||
- `最佳实践/` - 已验证的最佳实践
|
||
|
||
### 2.2 设计文档
|
||
**位置**：`设计文档/`
|
||
**特点**：
|
||
- 描述"做什么"和"为什么"
|
||
- 引用知识库中的规范
|
||
- 关联相关的决策记录
|
||
|
||
**分类**：
|
||
- `需求设计/` - 功能需求
|
||
- `架构设计/` - 系统架构
|
||
- `功能设计/` - 具体功能设计
|
||
|
||
### 2.3 决策记录（ADR）
|
||
**位置**：`决策记录/`
|
||
**特点**：
|
||
- 记录所有重要决策
|
||
- 包含决策背景、选项、理由
|
||
- 格式标准化
|
||
|
||
### 2.4 问题追踪
|
||
**位置**：`问题追踪/`
|
||
**特点**：
|
||
- 管理待解决问题
|
||
- 状态明确（待讨论/进行中/已解决）
|
||
- 可追溯
|
||
|
||
---
|
||
|
||
## 三、文档模板
|
||
|
||
### 3.1 设计文档模板
|
||
|
||
```markdown
|
||
# {功能名称}设计
|
||
|
||
**状态**：{设计中|已完成|已废弃}
|
||
**创建日期**：YYYY-MM-DD
|
||
**最后更新**：YYYY-MM-DD
|
||
|
||
## 一、设计目标
|
||
|
||
功能要解决什么问题？
|
||
|
||
## 二、设计约束
|
||
|
||
引用：[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)
|
||
|
||
## 三、设计方案
|
||
|
||
### 3.1 方案概述
|
||
|
||
### 3.2 详细设计
|
||
|
||
## 四、相关决策
|
||
|
||
- [ADR-{序号}](../../决策记录/ADR-{序号}.md)
|
||
|
||
## 五、待讨论问题
|
||
|
||
- [问题追踪/待讨论/{问题}.md](../../问题追踪/待讨论/{问题}.md)
|
||
|
||
## 六、实现计划
|
||
|
||
1. 步骤1
|
||
2. 步骤2
|
||
```
|
||
|
||
### 3.2 ADR模板
|
||
|
||
```markdown
|
||
# ADR-{序号}: {决策标题}
|
||
|
||
**状态**：{已采纳|已拒绝|已替代|待定}
|
||
**日期**：YYYY-MM-DD
|
||
**决策者**：{姓名/角色}
|
||
|
||
## 上下文
|
||
|
||
为什么需要做这个决策？
|
||
|
||
## 考虑的选项
|
||
|
||
### 选项1：{选项名称}
|
||
- 优点：
|
||
- 缺点：
|
||
|
||
## 决策
|
||
|
||
选择的方案：{选项名称}
|
||
|
||
## 理由
|
||
|
||
为什么选择这个方案？
|
||
|
||
## 后果
|
||
|
||
### 正面影响
|
||
-
|
||
|
||
### 负面影响
|
||
-
|
||
|
||
### 约束
|
||
-
|
||
```
|
||
|
||
---
|
||
|
||
## 四、引用规范
|
||
|
||
### 4.1 引用格式
|
||
- 知识库：`[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)`
|
||
- 决策记录：`[ADR-001](../决策记录/ADR-001-事件系统设计.md)`
|
||
- 问题追踪：`[问题-001](../../问题追踪/待讨论/问题-001-右键菜单实现方式.md)`
|
||
- 设计文档：`[设计文档/架构设计/事件系统设计.md](../../设计文档/架构设计/事件系统设计.md)`
|
||
|
||
### 4.2 引用原则
|
||
- **准确性**：引用路径要准确
|
||
- **明确性**：引用要说明引用内容
|
||
- **完整性**：引用要包含路径和说明
|
||
|
||
---
|
||
|
||
## 五、内容要求
|
||
|
||
### 5.1 精简准确
|
||
- 内容要精简，避免冗余
|
||
- 描述要准确，避免歧义
|
||
- 避免AI幻觉，确保内容真实
|
||
|
||
### 5.2 结构清晰
|
||
- 使用清晰的标题层级
|
||
- 使用列表和表格组织内容
|
||
- 使用代码块展示代码
|
||
|
||
### 5.3 可维护性
|
||
- 文档要易于更新
|
||
- 使用模板保持一致性
|
||
- 定期检查和更新
|
||
|
||
---
|
||
|
||
## 六、检查清单
|
||
|
||
### 文档检查
|
||
- [ ] 符合文档分类
|
||
- [ ] 使用了正确的模板
|
||
- [ ] 引用了相关的知识库
|
||
- [ ] 关联了相关的决策记录
|
||
- [ ] 列出了待讨论问题
|
||
- [ ] 内容精简准确
|
||
- [ ] 结构清晰
|
||
|