绝尘
a5d30684ed
- 拆分 FileSystem.vue 为模块化组件架构 - 新增 Markdown Mermaid 图表渲染支持 - 新增 180+ 编程语言代码高亮 - 修复编辑/预览模式切换渲染问题 - 优化亮色/暗色模式主题适配 - 新增 TypeScript 类型定义
3.8 KiB
3.8 KiB
文档编写规范
状态：已确定
最后更新：2026-01-28
一、核心原则
1.1 抽象与实现分离
- 设计文档：描述"做什么"和"为什么"，不描述"怎么做"
- 实现细节：在代码中体现，不在设计文档中详细描述
1.2 问题与知识分离
1.3 确定性先行
- 约束优先：先明确约束和规则，再讨论具体实现
- 决策记录：所有重要决策都要记录在 决策记录/
二、文档分类
2.1 知识库文档
位置：知识库/
特点：
- 已确定、已验证的内容
- 可被其他文档引用
- 需要定期维护
分类：
规范/- 约束和规则参考/- 技术参考最佳实践/- 已验证的最佳实践
2.2 设计文档
位置：设计文档/
特点：
- 描述"做什么"和"为什么"
- 引用知识库中的规范
- 关联相关的决策记录
分类：
需求设计/- 功能需求架构设计/- 系统架构功能设计/- 具体功能设计
2.3 决策记录（ADR）
位置：决策记录/
特点：
- 记录所有重要决策
- 包含决策背景、选项、理由
- 格式标准化
2.4 问题追踪
位置：问题追踪/
特点：
- 管理待解决问题
- 状态明确（待讨论/进行中/已解决）
- 可追溯
三、文档模板
3.1 设计文档模板
# {功能名称}设计
**状态**：{设计中|已完成|已废弃}
**创建日期**：YYYY-MM-DD
**最后更新**：YYYY-MM-DD
## 一、设计目标
功能要解决什么问题？
## 二、设计约束
引用：[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)
## 三、设计方案
### 3.1 方案概述
### 3.2 详细设计
## 四、相关决策
- [ADR-{序号}](../../决策记录/ADR-{序号}.md)
## 五、待讨论问题
- [问题追踪/待讨论/{问题}.md](../../问题追踪/待讨论/{问题}.md)
## 六、实现计划
1. 步骤1
2. 步骤2
3.2 ADR模板
# 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 可维护性
- 文档要易于更新
- 使用模板保持一致性
- 定期检查和更新
六、检查清单
文档检查
- 符合文档分类
- 使用了正确的模板
- 引用了相关的知识库
- 关联了相关的决策记录
- 列出了待讨论问题
- 内容精简准确
- 结构清晰