fmode-app/rules/11-文档体系.md

文档体系规范

定位:docs/ 目录层级、文档元数据头与新鲜度保障纪律(文档永远最新)。

负面清单(Do Not)

• [禁止] 新增文档后不更新 docs/README.md 导航索引(文档孤岛)
• [禁止] 文档缺少版本/日期/状态字段
• [禁止] 使用外部工具生成的图片代替 mermaid 图(图片无法随文档维护)
• [禁止] 文档与代码不一致继续开发而不报告
• [禁止] 直接手改生产文档的"最后更新日期"或版本号(必须随实际变更走)

文档目录层级(强制检查单)

以下目录结构为最低要求,新增/修改文档时必须落入对应位置;MVP 项目可精简内容,但带 🔴 的项不可省略:

docs/
├── README.md             # 文档导航索引(新增/修改文档必须同步更新) 🔴
├── 00-tracking/          # 全程追踪(黄金规则 10)
│   ├── 操作追踪.md        # 综合日志 🔴
│   └── YYYY-MM-DD.md     # 当日文档(重大修改)
├── 01-requirements/      # 需求文档
│   ├── prd/              # PRD-YYYYMMDD-功能名.md 🔴
│   ├── personas/         # 用户画像
│   ├── raci/             # RACI 权责表
│   └── stories/          # 访谈记录:访谈-YYYYMMDD-主题.md
├── 02-design/            # 设计文档
│   ├── architecture/     # 架构图/泳道图(mermaid)
│   ├── decisions/        # ADR-NNN-标题.md 🔴
│   └── database/         # ER 图/表结构/范式文档
├── 03-interface/api/     # API 文档(路由/参数/错误码/示例)
├── 04-quality/           # 质量保障
│   ├── testing/          # 测试策略/用例
│   ├── review/           # 评审报告
│   └── traceability-matrix.md  # 四向追溯矩阵 🔴
├── 05-operations/        # 部署/监控/备份
├── 06-standards/         # 技术栈/代码规范/踩坑记录
├── 07-records/           # 修改留痕:YYYY-MM-DD-功能名.md
└── 08-enterprise/        # 规范库专用(角色定位/迁移清单/培训/服务约定)

缺失关键文档(🔴 项)不得进入下一阶段。 项目初始化时,AI 应首先创建 docs/README.md 与 docs/04-quality/traceability-matrix.md 空壳,后续随开发逐行填充。

必须规则

1. [必须] 文档元数据头:每篇文档(PRD/画像/方案/表结构/API)头部固定字段——版本号、最后更新日期(YYYY-MM-DD)、状态(草稿/评审/生效/废弃)、本次变更原因。
2. [必须] 文档先行:先改文档再改代码;需求变更沿变更传播链逐层更新:用户画像/PRD → 技术方案 → 数据库/ER 图 → API 文档 → 测试用例 → 修改留痕,缺一不可。
3. [必须] DoD:功能"完成"必须包含"所有关联文档已同步更新",未满足不算完成(见 02-开发流程与文档同步.md)。
4. [必须] 单一事实源:数据库结构以 docs/schema/ 的 PlantUML 范式 + FmodeSchema 建表脚本为准,表结构文档是同步视图;AI 改脚本后必须同步文档,发现不一致先向用户提出。
5. [必须] 任务前后双查:任务开始前检查涉及文档与代码一致性;结束前核对文档同步情况。
6. [必须] 需求变更流程:变更不得静默改 PRD——记录变更请求(日期/内容/原因/影响评估),更新 PRD 版本号(v1.1→v1.2),再沿链传播。
7. [必须] 索引强制更新:docs/README.md 导航索引在新增/修改文档时同步。
8. [必须] AI 改产品文档需确认:AI 可直接更新技术文档;修改 PRD/用户画像等产品文档前,向用户展示变更摘要并经确认。
9. [必须] 图规范:架构图/泳道图/ER 图/时序图统一用 mermaid(erDiagram/flowchart/sequenceDiagram)写在 markdown 中,禁止用外部工具导出的静态图片。
10. [必须] 编号规则:PRD PRD-YYYYMMDD-功能名;ADR ADR-001-标题;修改记录 YYYY-MM-DD-功能名;当日文档 YYYY-MM-DD;日期统一 YYYY-MM-DD。
11. [必须] 废弃文档处理:废弃文档标记「状态: 废弃」并注明废弃日期与原因,禁止直接删除不留痕迹(避免历史不可追溯)。

建议规则

• [建议] 踩坑沉淀:踩坑经验写入 docs/06-standards/lessons-learned.md(用模板),定期反哺本规则文件。