# 文档编写规范

**状态**：已确定  
**最后更新**：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 可维护性
- 文档要易于更新
- 使用模板保持一致性
- 定期检查和更新

---

## 六、检查清单

### 文档检查
- [ ] 符合文档分类
- [ ] 使用了正确的模板
- [ ] 引用了相关的知识库
- [ ] 关联了相关的决策记录
- [ ] 列出了待讨论问题
- [ ] 内容精简准确
- [ ] 结构清晰