绝尘
a5d30684ed
- 拆分 FileSystem.vue 为模块化组件架构 - 新增 Markdown Mermaid 图表渲染支持 - 新增 180+ 编程语言代码高亮 - 修复编辑/预览模式切换渲染问题 - 优化亮色/暗色模式主题适配 - 新增 TypeScript 类型定义
7.2 KiB
7.2 KiB
文档结构说明
创建日期：2026-01-28
目的：说明文档结构如何支持现代化AI人机协同模式
🎯 设计目标
核心原则
- 详细与抽象分离：设计文档描述"做什么"和"为什么"，实现细节在代码中
- 问题与知识分离：待讨论问题单独管理，已确定知识进入知识库
- 确定性先行：优先明确约束和规则，再讨论具体实现
- 全程可控：每个步骤都有明确的检查点和验证标准
- 异步有序：通过文档结构支持异步协作，减少同步沟通成本
📁 文档结构
GO-DESK-2.数据库客户端/
├── README.md # 模块总览和快速导航
├── 任务规划.md # 紧凑版任务规划（引用详细文档）
├── 文档结构说明.md # 本文件
│
├── 决策记录/ # 架构决策记录（ADR）
│ ├── README.md # ADR说明和模板
│ └── ADR-*.md # 具体决策记录
│
├── 知识库/ # 已确定的知识
│ ├── README.md # 知识库说明
│ ├── 规范/ # 约束和规则
│ │ ├── 编码规范.md
│ │ ├── 架构规范.md
│ │ ├── 文档编写规范.md
│ │ └── AI协作检查清单.md
│ ├── 参考/ # 技术参考
│ │ └── 技术栈.md
│ └── 最佳实践/ # 已验证的最佳实践
│
├── 问题追踪/ # 待解决问题
│ ├── README.md # 问题追踪说明
│ ├── 待讨论/ # 需要讨论的问题
│ ├── 待实现/ # 已确定但未实现的功能
│ └── 技术债务/ # 技术债务
│
├── 设计文档/ # 功能设计和架构设计
│ ├── README.md # 设计文档说明
│ ├── 需求设计/ # 功能需求
│ ├── 架构设计/ # 系统架构
│ └── 功能设计/ # 具体功能设计
│
├── 核对报告/ # 各种检查报告
│ └── *.md # 检查报告文档
│
└── 测试用例/ # 测试用例和测试检查
└── README.md # 测试用例说明
🔄 协作流程
对于开发者
开始新功能
遇到问题
- 查找问题：在 问题追踪/ 中查找是否已有相关问题
- 创建问题：如果没有，创建新问题（待讨论/待实现/技术债务）
- 讨论问题：在问题文档中记录讨论过程
- 记录决策：如果做出决策，创建ADR记录
做决策
- 创建ADR：在 决策记录/ 中创建决策记录
- 记录选项：列出考虑的选项和理由
- 记录后果：记录决策的正面和负面影响
- 更新文档：更新相关的设计文档和问题追踪
实现功能
对于AI助手
开始任务
- 读取约束：必须优先读取 知识库/规范/ 中的约束
- 编码规范.md - 代码编写约束
- 架构规范.md - 架构约束
- AI协作检查清单.md - 协作检查清单
- 检查决策：在 决策记录/ 中查找相关决策
- 检查问题：在 问题追踪/ 中查找待解决问题
- 参考设计：在 设计文档/ 中查找设计文档
执行任务
- 遵循约束：严格按照知识库中的约束执行
- 记录决策：如果做出新决策，创建ADR
- 更新问题：如果解决问题，更新问题状态
- 引用规范：在代码和文档中引用相关规范
完成任务
🎯 关键特性
1. 确定性先行
2. 抽象与实现分离
- 设计文档：只描述"做什么"和"为什么"，不描述"怎么做"
- 实现细节：在代码中体现，不在设计文档中详细描述
- 知识库：存储已确定的知识，不存储实现细节
3. 问题与知识分离
4. 全程可控
- 检查清单：AI协作检查清单 确保每个步骤都有检查点
- 约束明确：所有约束都在知识库中明确记录
- 状态追踪：问题状态明确，可追溯
5. 异步有序
- 文档结构：通过清晰的文档结构支持异步协作
- 引用关系：通过引用关系建立文档间的关联
- 状态管理：通过状态管理追踪问题进展
📊 文档统计
- 总文档数：39个
- 决策记录：2个
- 知识库规范：4个
- 问题追踪：2个
- 设计文档：7个
- 核对报告：14个
🔗 快速链接
- README.md - 模块总览
- 任务规划.md - 任务规划
- 知识库/规范/AI协作检查清单.md - AI协作检查清单
- 知识库/规范/编码规范.md - 编码规范
- 知识库/规范/架构规范.md - 架构规范