dev-doc-structure - SKILL.md Agent Skill

name: dev-doc-structure description: | 文档体系管理专家。在以下情况下使用：

【新建文档体系】

用户说"建立文档结构"、"创建文档体系"、"初始化文档"
项目中没有 docs/ 目录或文档很少

【标准化现有文档】

用户说"优化文档结构"、"文档重复"、"文档太乱"
README.md 超过 250 行
发现文档内容重复

【文档更新指导】

完成功能开发后，提醒更新相关文档
API/数据库/配置变更时，检查文档更新触发条件
用户问"应该更新哪些文档"

【文档诊断】 - 用户说"检查文档"、"文档有什么问题" - 发现文档结构不规范、内容重复、缺失关键文档

Development Documentation Structure

建立专业、结构化的开发文档系统，采用场景化预设模板，快速搭建文档体系。

核心原则

场景化预设：根据项目类型提供预设文档结构
零学习成本：用户只需选择场景，无需理解复杂层级
开箱即用：预设结构覆盖 90% 的常见需求
渐进式扩展：从简单到复杂，按需深入

工作流程

步骤 0：检测项目状态（新增）

在开始创建文档前，先检测项目现状：

扫描现有文档
- 列出所有 .md 文件
- 识别标准文档和非标准文档
诊断问题
- 内容重复（README.md 和 environment-setup.md）
- 长度超标（README.md > 250 行）
- 缺失文档（缺少 docs/README.md）
- 非标准文档（临时文档、归档文档）

生成诊断报告

## 文档诊断报告

### 问题
- ⚠️ README.md 过长（500 行，建议 < 250 行）
- ⚠️ 内容重复：README.md 和 environment-setup.md（重复率 35%）
- ⚠️ 缺失文档：docs/README.md
- ℹ️ 非标准文档：temp_readme.md, old_api_doc.md

### 建议
1. 简化 README.md，移动详细内容到 environment-setup.md
2. 创建 docs/README.md 作为文档导航
3. 处理非标准文档（移到 archive/ 或删除）

询问用户：
- 新建文档体系？
- 标准化现有文档？
- 处理非标准文档？

步骤 0.5：处理非标准文档（新增）

扫描到不在标准体系内的文档时：

识别文档类型

文档类型	特征	处理方式
临时文档	TODO.md, NOTES.md, scratch.md	询问：是否移到 docs/temp/
归档文档	旧版本、过时内容	询问：是否移到 docs/archive/
项目特定文档	业务文档、需求文档	询问：是否移到 docs/business/
工具配置文档	CI/CD、Docker、K8s	保留在根目录或工具目录
贡献指南	CONTRIBUTING.md, CODE_OF_CONDUCT.md	保留在根目录
许可证	LICENSE.md	保留在根目录

处理流程

列出非标准文档

发现以下文档不在标准体系内：
- temp_readme.md (临时文档)
- old_api_doc.md (归档文档)
- 设备管控开发需求简述.md (业务文档)

询问处理方式

建议处理方式：
1. temp_readme.md → 移到 docs/temp/ 或删除
2. old_api_doc.md → 移到 docs/archive/
3. 设备管控开发需求简述.md → 移到 docs/business/

是否执行？(Y/n)

创建必要目录
- docs/temp/ - 临时文档
- docs/archive/ - 归档文档
- docs/business/ - 业务文档
更新 .gitignore
```
# 临时文档不提交
docs/temp/
```

步骤 1：场景选择

询问用户项目架构类型：

请选择项目架构类型：

A. 前后端分离应用
   - Web 前后端分离（React + Spring Boot、Vue + Express 等）
   - 桌面应用（Electron、Tauri 等）
   - 移动应用（React Native + API 后端）

B. 非前后端分离应用
   - CLI 工具
   - 库/包/SDK
   - 其他单体应用

请输入字母（A 或 B）：

根据选择进入下一步：

如果选择 A（前后端分离）：

您选择了：前后端分离应用

请选择当前项目包含的内容：

1. 只有前端（React、Vue、Electron 前端等）
2. 只有后端（API 服务、后端服务等）
3. 前后端都有

请输入数字（1-3）：

如果选择 3（前后端都有），继续询问：

您选择了：前后端都有

请选择文档组织方式：

1. 集中式文档（推荐：小型项目）
   - 在根目录统一创建 docs/
   - 前后端文档集中管理
   - 适合：紧密耦合、小团队

2. 分散式文档（推荐：大型项目）
   - 前端和后端各自创建独立的 docs/
   - 前后端文档独立管理
   - 适合：独立开发、大团队

请输入数字（1 或 2）：

如果选择 B（非前后端分离）：

您选择了：非前后端分离应用

请选择项目类型：

1. CLI 工具（命令行工具、脚本、构建工具等）
2. 库/包/SDK（npm 包、Python 库、Java 库等）
3. 其他单体应用（传统 Web 应用、游戏、数据处理等）

请输入数字（1-3）：

步骤 2：展示预设结构并确认

根据用户选择，展示对应的预设文档结构。

示例（场景 A1：只有前端）：

您选择了：前后端分离应用 → 只有前端

将创建以下文档结构：

project/
├── README.md                    # 项目概览、快速启动
├── CHANGELOG.md                 # 版本历史
└── docs/
    ├── devlog.md               # 开发日志
    ├── architecture.md         # 架构设计
    ├── components.md           # 组件文档
    ├── api-integration.md      # 后端 API 对接
    ├── config.md               # 配置说明
    └── deployment.md           # 构建和部署

核心文档：7 个
适用场景：React、Vue、Angular、Electron 前端等

这个结构是否满足您的需求？
1. 是，直接创建
2. 否，我需要调整

其他场景的展示格式类似，详见 references/scenarios.md。

步骤 3：执行创建或进入自定义模式

如果用户选择"1. 是，直接创建"：

创建文档结构：
- 使用 references/content-templates.md 中的模板
- 创建所有预设文档
- 填充基础内容
创建 .claude/rules/ 入口文档：
- project-setup.md - 项目导航入口
- documentation-update.md - 文档更新规则

生成验证报告：

## 文档结构创建完成

### 场景
- 类型：[场景名称]
- 核心文档：X 个

### 已创建文档
- ✅ README.md
- ✅ CHANGELOG.md
- ✅ docs/devlog.md
- ✅ docs/architecture.md
- ...

### 入口文档
- ✅ .claude/rules/project-setup.md
- ✅ .claude/rules/documentation-update.md

### 下一步
1. 查看 README.md 了解项目结构
2. 查看 .claude/rules/project-setup.md 了解文档导航
3. 开始开发，完成功能后更新 docs/devlog.md

如果用户选择"2. 否，我需要调整"：

进入自定义模式：

进入自定义模式，您可以：

1. 添加文档
   - 输入文档路径（如：docs/security.md）

2. 删除文档
   - 选择要删除的文档编号

3. 添加 modules/ 目录
   - 用于记录各业务模块的详细文档

4. 调整目录结构
   - 修改文档位置

5. 完成自定义，开始创建

请选择操作（1-5）：

关于 modules/ 目录：

当用户选择"添加 modules/ 目录"时，询问：

modules/ 目录将用于记录各业务模块的详细文档。

示例：
- 前端：用户模块、订单模块、支付模块
- 后端：用户服务、订单服务、支付服务
- CLI：build 命令模块、deploy 命令模块

是否创建 modules/ 目录？
1. 是
2. 否

步骤 5：文档维护指导（新增）

创建/标准化完成后，提供维护指导：

## 文档维护指南

### 日常更新
- 完成功能开发 → 更新 devlog.md
- API 变更 → 更新 api.md
- 数据库变更 → 更新 database.md
- 配置变更 → 更新 config.md

### 自动检测
Skill 会在以下情况自动提醒：
- 检测到 API 文件变更
- 检测到数据库迁移文件
- 检测到配置文件变更

### 更新原则
- 单一信息源：每个信息只在一处详细说明
- 及时更新：代码和文档一起提交
- 链接优先：使用链接而非复制内容

### 质量检查
定期检查：
- 文档长度（README.md < 250 行）
- 内容重复（使用链接而非复制）
- 链接有效性

场景预设详细说明

场景 A：前后端分离应用

A1：只有前端

核心文档（7 个）：

README.md - 项目概览、快速启动
CHANGELOG.md - 版本历史
docs/devlog.md - 开发日志
docs/architecture.md - 架构设计
docs/components.md - 组件文档
docs/api-integration.md - 后端 API 对接
docs/config.md - 配置说明
docs/deployment.md - 构建和部署

可选扩展：

docs/modules/ - 功能模块详细文档

适用项目：React、Vue、Angular、Electron 前端等

A2：只有后端

核心文档（7 个）：

README.md - 项目概览、快速启动
CHANGELOG.md - 版本历史
docs/devlog.md - 开发日志
docs/architecture.md - 系统架构
docs/api.md - API 文档
docs/database.md - 数据库设计
docs/config.md - 配置说明
docs/deployment.md - 部署指南

可选扩展：

docs/modules/ - 业务模块详细文档

适用项目：Spring Boot、Express、Django、FastAPI 等

A3-1：前后端都有 - 集中式文档

核心文档（9 个）：

README.md - 项目总览
CHANGELOG.md - 版本历史
docs/devlog.md - 开发日志（前后端统一）
docs/architecture.md - 整体架构
docs/frontend/components.md - 前端组件
docs/frontend/state-management.md - 状态管理
docs/backend/api.md - API 文档
docs/backend/database.md - 数据库设计
docs/config.md - 配置说明
docs/deployment.md - 部署指南
frontend/README.md - 前端简要说明
backend/README.md - 后端简要说明

可选扩展：

docs/modules/ - 业务模块详细文档

适用项目：小型前后端分离项目、紧密耦合

A3-2：前后端都有 - 分散式文档

核心文档（16 个）：

README.md - 项目总览
docs/project-overview.md - 整体架构
frontend/README.md - 前端项目说明
frontend/CHANGELOG.md - 前端版本历史
frontend/docs/devlog.md - 前端开发日志
frontend/docs/architecture.md - 前端架构
frontend/docs/components.md - 组件文档
frontend/docs/api-integration.md - API 对接
frontend/docs/config.md - 前端配置
frontend/docs/deployment.md - 前端部署
backend/README.md - 后端项目说明
backend/CHANGELOG.md - 后端版本历史
backend/docs/devlog.md - 后端开发日志
backend/docs/architecture.md - 后端架构
backend/docs/api.md - API 文档
backend/docs/database.md - 数据库设计
backend/docs/config.md - 后端配置
backend/docs/deployment.md - 后端部署

可选扩展：

frontend/docs/modules/ - 前端功能模块
backend/docs/modules/ - 后端业务模块

适用项目：大型前后端分离项目、独立开发团队

场景 B：非前后端分离应用

B1：CLI 工具

核心文档（5 个）：

README.md - 项目概览、安装
CHANGELOG.md - 版本历史
docs/devlog.md - 开发日志
docs/cli-reference.md - 命令参考
docs/config.md - 配置文件说明
docs/examples.md - 使用示例

可选扩展：

docs/modules/ - 命令模块详细文档

适用项目：命令行工具、构建工具、脚本

B2：库/包/SDK

核心文档（4-5 个）：

README.md - 项目概览、安装
CHANGELOG.md - 版本历史
docs/api.md - API 参考
docs/guide.md - 使用指南
docs/examples.md - 示例代码
docs/migration.md - 迁移指南（可选）

可选扩展：

docs/modules/ - 功能模块详细文档

适用项目：npm 包、Python 库、Java 库

B3：其他单体应用

核心文档（5 个）：

README.md - 项目概览、快速启动
CHANGELOG.md - 版本历史
docs/devlog.md - 开发日志
docs/architecture.md - 系统架构
docs/config.md - 配置说明
docs/deployment.md - 部署指南

可选扩展：

docs/modules/ - 功能模块详细文档

适用项目：传统 Web 应用、游戏、数据处理应用

.claude/rules/ 入口文档

所有场景都创建的文件

1. .claude/rules/project-setup.md

作用：AI 的第一入口点，快速了解项目结构

单项目版本：

# 项目规则与文档导航

## 项目信息

- **项目名称**：[项目名]
- **项目类型**：[前端应用/后端 API/CLI 工具/库包/单体应用]
- **技术栈**：[技术栈列表]
- **文档结构**：场景 [A1/A2/A3-1/A3-2/B1/B2/B3]

## 快速启动

### 环境要求
- [环境要求列表]

### 安装步骤
\`\`\`bash
# 安装依赖
[安装命令]
\`\`\`

### 运行项目
\`\`\`bash
# 启动项目
[运行命令]
\`\`\`

## 文档索引

### 核心文档
- **项目概览**：`README.md`
- **开发日志**：`docs/devlog.md`
- **架构文档**：`docs/architecture.md`
- **配置说明**：`docs/config.md`
- **部署指南**：`docs/deployment.md`

### 场景特定文档
[根据场景列出特定文档]

### 可选文档
- **模块文档**：`docs/modules/`（如果存在）
- **版本历史**：`CHANGELOG.md`

## 文档更新规则

详见：`.claude/rules/documentation-update.md`

Monorepo 版本：

# 项目规则与文档导航

## 项目信息

- **项目名称**：[项目名]
- **项目类型**：Monorepo（前后端分离）
- **文档结构**：场景 [A3-1 集中式 / A3-2 分散式]

## 子项目列表

### 前端项目
- **路径**：`frontend/`
- **类型**：[React/Vue/Angular/Electron]
- **文档入口**：`frontend/README.md`
- **文档目录**：
  - 集中式：`docs/frontend/`
  - 分散式：`frontend/docs/`

### 后端项目
- **路径**：`backend/`
- **类型**：[Spring Boot/Express/Django/FastAPI]
- **文档入口**：`backend/README.md`
- **文档目录**：
  - 集中式：`docs/backend/`
  - 分散式：`backend/docs/`

## 整体架构

详见：
- 集中式：`docs/architecture.md`
- 分散式：`docs/project-overview.md`

## 快速启动

### 前端
\`\`\`bash
cd frontend
[前端启动命令]
\`\`\`

### 后端
\`\`\`bash
cd backend
[后端启动命令]
\`\`\`

## 文档索引

### 根级文档
- **项目总览**：`README.md`
- **整体架构**：
  - 集中式：`docs/architecture.md`
  - 分散式：`docs/project-overview.md`

### 前端文档
[列出前端文档路径]

### 后端文档
[列出后端文档路径]

## 文档更新规则

详见：`.claude/rules/documentation-update.md`

2. .claude/rules/documentation-update.md

作用：定义文档更新触发条件和更新流程

内容：详见 references/update-rules.md

文档更新触发规则（简化版）

10 条核心触发规则

触发条件	需要更新的文档	说明
1. 完成功能开发	devlog.md	记录功能开发过程、问题、解决方案
2. API 变更	api.md（后端） api-integration.md（前端）	新增/修改/删除 API 端点
3. 数据库变更	database.md	表结构、字段、关系变更
4. 配置变更	config.md	环境变量、配置文件、配置项变更
5. 架构调整	architecture.md	系统架构、模块结构、技术选型变更
6. 组件/模块变更	components.md（前端） modules/（可选）	新增/修改组件或模块
7. 部署流程变更	deployment.md	部署步骤、环境配置变更
8. 版本发布	CHANGELOG.md	记录版本变更内容
9. CLI 命令变更	cli-reference.md	新增/修改命令、参数（CLI 项目）
10. 公开 API 变更	api.md	库/包的公开 API 变更

更新工作流程

代码变更完成
    ↓
判断触发条件（1-10）
    ↓
更新对应文档
    ↓
在 devlog.md 中记录（如果是重要变更）

重要说明

场景化预设：根据项目类型提供固定的文档集合，无需用户决策
零学习成本：用户只需选择场景，无需理解复杂的层级和规则
开箱即用：预设结构覆盖 90% 的常见需求
渐进式扩展：需要时可进入自定义模式
modules/ 目录：所有场景都提供作为可选扩展，用于记录各业务模块的详细文档

文档全生命周期维护

文档更新触发条件

触发条件	需要更新的文档	检查方式
完成功能开发	devlog.md	代码提交后自动提醒
API 变更	api.md, api-integration.md	检测到 Controller/Route 变更
数据库变更	database.md	检测到 SQL 文件或 Migration 变更
配置变更	config.md, environment-setup.md	检测到配置文件变更
架构调整	architecture.md	检测到模块结构变更
部署流程变更	deployment.md	检测到 CI/CD 配置变更
版本发布	CHANGELOG.md	用户执行发布命令时

文档更新原则

原则 1：单一信息源（SSOT）

每个信息只在一个文档中详细说明
其他文档通过链接引用
更新时只需修改一处

原则 2：及时更新

代码变更和文档更新在同一次提交
不要积累文档债务

原则 3：向后兼容

更新 API 文档时，标注版本和废弃信息
保留迁移指南

原则 4：验证更新

更新后检查所有链接有效性
确保示例代码可运行

文档更新检查清单

更新前

确认触发条件（API/数据库/配置变更）
确认需要更新的文档
确认是否需要更新多个文档

更新中

更新信息源文档
检查其他文档的链接是否需要更新
更新示例代码

更新后

检查所有链接有效性
检查示例代码可运行
在 devlog.md 中记录（如果是重要变更）
代码和文档一起提交

参考文档

scenarios.md - 所有场景的详细说明和目录结构
content-templates.md - 各文档类型的内容模板
update-rules.md - 完整的文档更新规则