文档编写、整理与优化专家（doc-organizer）

一、目标与边界

1.1 目标

•编写：根据模板快速生成规范的技术文档
•整理：诊断并解决重复内容、目录混乱、边界不清问题
•优化：建立可扩展、可维护的文档信息架构

1.2 核心原则

•单一信息源（SSOT）：同一事实只写一处，其他位置引用
•引用代替复制：避免多处维护同一内容
•按业务领域组织：不按技术栈拆散同一模块
•扁平化：目录深度建议 ≤ 3 层

1.3 边界约束

约束	说明
数据库定义	集中在 `02-系统架构/03-数据库设计.md`，模块文档只引用
测试用例	集中在模块目录的 `测试用例.md`，不散落在实现文档
运维排障	初期不强制规划，需要时再增设
API 契约	集中在模块目录的 `API接口.md`，为唯一权威来源

二、场景识别与工作流程选择

2.1 场景分类

根据用户任务自动识别场景，选择对应工作流程：

code

┌─────────────────────────────────────────────────────────────┐
│                     用户任务识别                             │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
   │  编写类任务   │   │  整理类任务   │   │  优化类任务   │
   └──────────────┘   └──────────────┘   └──────────────┘
          │                   │                   │
          ▼                   ▼                   ▼
   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
   │ • 编写新文档  │   │ • 文档整理    │   │ • 结构优化   │
   │ • 补全文档    │   │ • 文档去重    │   │ • 目录重构   │
   │ • 修复文档    │   │ • 内容迁移    │   │ • 规范统一   │
   │ • 评审文档    │   │ • 版本清理    │   │ • 信息架构   │
   └──────────────┘   └──────────────┘   └──────────────┘
          │                   │                   │
          ▼                   ▼                   ▼
   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
   │  轻量流程 A   │   │  中量流程 B   │   │  重量流程 C   │
   └──────────────┘   └──────────────┘   └──────────────┘

2.2 流程 A：轻量流程（编写/补全/修复单个文档）

触发词：编写文档、补全文档、修复文档、评审文档、写需求规格、写API文档

步骤：

•识别文档类型 → 选择对应模板
•了解上下文 → 阅读相关文档（需求规格、API接口等）
•生成/修复内容 → 按模板结构编写
•快速检查 → SSOT 合规性、引用正确性

产出物：

•符合模板的文档内容
•相关文档的引用链接

2.3 流程 B：中量流程（整理/去重/迁移）

触发词：文档整理、文档去重、内容迁移、合并文档

步骤：

•扫描目标范围 → 统计文件数量、类型、重复情况
•识别问题 → 重复内容、边界错误、路径错误
•制定迁移计划 → 源位置 → 目标位置 → 操作类型
•执行迁移 → 移动文档、更新引用、删除重复
•验证 → 链接检查、内容完整性

产出物：

•问题清单（Markdown 表格）
•迁移计划表
•执行记录

2.4 流程 C：重量流程（目录重构/信息架构）

触发词：目录重构、结构优化、信息架构、文档体系规划

步骤：

•全面分析 → 目录深度、文件分布、重复率、引用关系
•设计目标结构 → 基于 references/directory-structure.md
•制定详细计划 → 分批迁移、风险评估、回滚方案
•分阶段执行 → 先骨架后内容、先核心后边缘
•全面验证 → 完整性、链接、效果评估

产出物：

•量化指标报告
•目标目录结构
•分阶段迁移计划
•验证报告（含效果评估）

三、模板快速选择

3.1 决策树

code

需要写什么类型的文档？
│
├─ 产品/需求相关
│   ├─ 产品概述/背景/目标 → product-design-template.md
│   └─ 模块功能需求/业务规则 → requirements-template.md
│
├─ 架构/设计相关
│   ├─ 系统整体架构/技术栈 → architecture-template.md
│   └─ 数据库设计 → architecture-template.md（数据库章节）
│
├─ API 相关
│   ├─ 全局 API 规范/错误码 → api-interface-template-1.md
│   └─ 模块接口契约 → api-interface-template-2.md
│
├─ 实现设计相关
│   ├─ 后端业务逻辑/缓存/事务 → backend-code-design-template.md
│   └─ 前端组件/状态/交互 → front-code-design-template.md
│
├─ 测试相关
│   └─ 测试用例/验收标准 → test-quality-template.md
│
└─ 其他
    └─ 通用文档 → doc-template.md

3.2 模板速查表

文档类型	模板文件	适用场景
产品设计	`assets/product-design-template.md`	产品概述、UI-UX设计规范
系统架构	`assets/architecture-template.md`	总体架构、技术栈、数据库设计、部署架构
需求规格	`assets/requirements-template.md`	模块功能需求、业务规则、验收口径
全局 API	`assets/api-interface-template-1.md`	全局 API 规范、通用错误码、认证方式
模块 API	`assets/api-interface-template-2.md`	模块级接口契约（路径/参数/响应）
后端实现	`assets/backend-code-design-template.md`	业务逻辑、状态流转、事务、缓存
前端实现	`assets/front-code-design-template.md`	组件设计、状态管理、交互流程
测试用例	`assets/test-quality-template.md`	测试用例、性能测试、验收标准
通用文档	`assets/doc-template.md`	其他类型（最小骨架）

四、单一信息源（SSOT）规则

4.1 SSOT 速查表

内容类型	SSOT 位置（唯一权威）	其他文档如何写	❌ 禁止行为
API 规范	`03-模块设计/.../[模块]/API接口.md`	只放链接	在测试/前端/后端各写一套接口清单
UI-UX 通用规范	`01-产品设计/02-UI-UX设计规范.md`	只引用，写差异点	在每个模块重复写断点/通用交互
模块级交互	`03-模块设计/.../[模块]/需求规格.md`	前端写实现，测试写验证	前端/测试复述交互规范原文
性能/安全目标	`需求规格.md` 验收标准章节	实现写策略，测试写方法	三份文档各定义不同阈值
数据库 ER/表结构	`02-系统架构/03-数据库设计.md`	只列依赖与约束	在模块后端粘贴全量 DDL
日志/配置规范	系统级文档（或模块内临时 SSOT）	只列本模块特有项	把运维排障混入模块实现

4.2 内容边界速查

需求规格.md

✅ 允许	❌ 避免
功能点列表（带编号 `F-XX-001`）	前端组件拆分、状态字段
模块级页面结构与交互规则	后端缓存 Key/TTL、锁实现
权限/数据范围/角色矩阵	复述通用 UI-UX 规范
性能/安全目标与验收标准	具体实现策略

后端实现.md

✅ 允许	❌ 避免
DTO 字段含义与校验规则	粘贴 DB DDL/完整表结构
核心业务规则与流程	测试用例矩阵
事务边界、幂等/并发方案	运维排障手册
缓存规则、安全实现策略	多语言重复代码

前端实现.md

✅ 允许	❌ 避免
组件拆分、职责边界、状态字段	复述需求中的交互规范
表单校验、错误处理、权限指令	后端内部实现细节
API 调用方式（契约必须引用）	技术栈特定代码示例

测试用例.md

✅ 允许	❌ 避免
测试点/步骤/断言	写独立接口清单（只引用）
引用需求章节	重复需求大段描述
引用性能阈值，写采样方法	复述 UI 规范正文

五、参考资源

5.1 参考资料

文件	说明	使用场景
`references/directory-structure.md`	详细目录结构模板、设计原则	目录重构、新项目规划
`references/naming-conventions.md`	文件/目录命名规范、版本管理	命名规范统一
`references/analysis-checklist.md`	分析与验收检查清单	全面审计、验收

5.2 快速检查清单（轻量版）

编写/修复单个文档时，快速检查以下项目：

• 文档类型与模板匹配
• SSOT 内容没有重复（API/交互/性能阈值只写一处）
• 引用链接正确（相关文档路径正确）
• 章节选择合理（简单模块省略可选章节）
• 编号规范统一（F-XX-001、T-XX-001）

5.3 辅助脚本

脚本	功能	使用方法
`scripts/analyze_structure.py`	分析目录结构、统计文件	`python analyze_structure.py <目录路径>`
`scripts/check_links.py`	检查内部链接有效性	`python check_links.py <目录路径>`
`scripts/find_duplicates.py`	检测重复内容和图片	`python find_duplicates.py <目录路径>`

doc-organizer

文档编写、整理与优化专家（doc-organizer）

一、目标与边界

1.1 目标

1.2 核心原则

1.3 边界约束

二、场景识别与工作流程选择

2.1 场景分类

2.2 流程 A：轻量流程（编写/补全/修复单个文档）

2.3 流程 B：中量流程（整理/去重/迁移）

2.4 流程 C：重量流程（目录重构/信息架构）

三、模板快速选择

3.1 决策树

3.2 模板速查表

四、单一信息源（SSOT）规则

4.1 SSOT 速查表

4.2 内容边界速查

需求规格.md

后端实现.md

前端实现.md

测试用例.md

五、参考资源

5.1 参考资料

5.2 快速检查清单（轻量版）

5.3 辅助脚本

六、技能边界

6.1 适用范围

6.2 不适用范围