6.0 KiB

Raw Permalink Blame History

ADR 001: 文档体系重构

状态: 已实施
日期: 2026-01-18
决策者: AI Agent + 用户
影响范围: 全项目文档管理

背景

原有文档分类体系存在以下问题：

分类模糊：
- "方案"和"修复"界限不清（修复也需要方案设计）
- "示例"定位模糊（是教程还是 API 文档？）
- "计划"文档生命周期管理缺失
缺少关键文档类型：
- 无架构决策记录（ADR）
- 无变更日志（Changelog）
- 缺少"为什么"的记录
目录结构扁平：
- 所有文档混在一起
- 无法按模块（client/admin/server）区分
- 不利于大规模项目管理
文档过度创建：
- 每次执行都创建文档
- 临时计划文档未归档
- 文档冗余严重

决策

采用 RFC + ADR + Guides 三层文档体系，配合模块化目录结构。

新目录结构

docs/
├── client/              # 前端文档
│   ├── rfcs/           # 技术提案（RFC）
│   ├── adrs/           # 架构决策记录（ADR）
│   ├── guides/         # 使用指南
│   └── changelogs/     # 变更日志
├── admin/              # 管理后台文档
│   ├── rfcs/
│   ├── adrs/
│   ├── guides/
│   └── changelogs/
├── server/             # 后端文档
│   ├── rfcs/
│   ├── adrs/
│   ├── guides/
│   └── changelogs/
├── requirements/       # 全局需求文档
├── architecture/       # 跨模块架构文档
└── .archive/           # 归档目录
    ├── client/
    ├── admin/
    └── server/

文档类型定义

类型	用途	何时创建	编号规则
RFC	技术方案设计	新功能、重构、重大 Bug 修复	新功能 001-099，修复 101-199
ADR	架构决策记录	技术选型、框架选择、架构模式	001, 002, 003...
Guides	使用指南	API 文档、部署流程、最佳实践	主题命名
Changelogs	版本变更	每次发布	版本号

文件命名规范

rfcs/[编号]-[标题].md
例：001-google-oauth-implementation.md
    101-fix-dialog-footer.md

adrs/[编号]-[决策标题].md
例：001-选择-fastapi-框架.md

guides/[主题]-[子主题].md
例：user-service-testing.md

理由

为什么选择 RFC/ADR？

业界标准：RFC 和 ADR 是经过验证的工程实践
可追溯性：ADR 记录每个重大决策的上下文和权衡
知识传承：新成员可以快速了解历史决策
避免重复讨论：决策一旦记录，不会反复争论

为什么模块化？

清晰的边界：前后端文档分离，职责明确
便于协作：团队成员只需关注自己的模块
可扩展性：未来增加新模块（如 mobile）无需重构

为什么归档计划文档？

生命周期管理：计划文档是临时的，执行后应归档
减少噪音：活跃文档目录保持简洁
历史可查：归档文档仍可追溯

迁移映射

原有文档 → 新位置

原路径	新路径	说明
`docs/方案/`	`docs/{module}/rfcs/`	按模块分类
`docs/修复/`	`docs/{module}/rfcs/`	合并到 RFC，编号 101+
`docs/示例/`	`docs/{module}/guides/`	重命名为 Guides
`docs/计划/`	`docs/.archive/{module}/`	归档
`docs/需求/`	`docs/requirements/`	保持不变

迁移统计

RFC 文档: 23 个方案 + 19 个修复 = 42 个
Guides 文档: 3 个示例 + 2 个 Demo = 5 个
归档文档: 22 个计划文档
需求文档: 保持原有结构

影响

正面影响

✅ 标准化：符合业界最佳实践
✅ 可维护性：清晰的文档分类和生命周期
✅ 可追溯性：ADR 记录决策上下文
✅ 团队协作：模块化便于分工
✅ AI Agent 友好：结构化文档便于学习和推理

负面影响

⚠️ 学习成本：团队需要学习 RFC/ADR 规范
⚠️ 迁移成本：需要迁移现有文档（已完成）

风险缓解

提供详细的文档模板和示例
在 master-workflow.md 中明确文档创建规则
保留归档文档，确保历史可追溯

文档创建规则

必须创建（✅）

新功能开发
重大重构
架构决策
重要 Bug 修复

可选创建（⚠️）

简单代码调整
样式修改
配置微调

不需创建（❌）

依赖升级（无 Breaking Changes）
文案更新
注释修改

后续优化

文档模板：为 RFC/ADR/Guides 创建标准模板
自动化：编写脚本自动生成文档编号
索引生成：自动生成文档索引和目录
搜索优化：集成文档搜索工具

参考资料

总结

通过采用 RFC + ADR + Guides 的三层文档体系，配合模块化目录结构，我们建立了一个标准化、可维护、可追溯的文档管理系统。

这个系统不仅解决了当前的文档混乱问题，还为未来的团队协作和知识传承打下了坚实的基础。

这是一个长期、专业的解决方案。

6.0 KiB Raw Permalink Blame History