# Update Docs

> 文档更新。当用户说 "更新文档"、"文档需要同步"、"添加文档" 时激活。 支持代码变更驱动的文档更新、新文档脚手架、文档审查。

- Skill: `viewway/update-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add viewway/update-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viewway/update-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: viewway (https://skillmd.com/u/viewway)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/viewway/update-docs

---


# MiniHES 文档更新

## 何时使用

- 代码变更后需要更新文档
- 新功能需要编写文档
- 审查文档完整性
- 用户说 "更新文档"、"文档同步"、"写文档"

## 文档目录

```
docs/
├── planning/              # 项目规划
│   ├── development-plan.md        # 开发排期计划
│   ├── project-workflow.md        # 项目开发流程
│   └── phase-overview.md          # 阶段概览
├── tasks/                 # 需求文档
│   └── prd-cloud-metering-system.md
├── design/                # 设计文档
│   └── tech-review-and-architecture.md
├── api/                   # API 文档（按模块）
├── guides/                # 开发指南
│   └── testing-strategy.md
└── reports/               # 审查报告、复盘
```

**规则**：禁止在 docs/ 根目录直接放文件，必须进子目录。

## 工作流

### 模式 A：代码变更 → 文档更新

#### Step 1：识别变更

```bash
# 查看分支变更
git diff main...HEAD --stat
```

#### Step 2：映射到文档

| 变更位置 | 可能影响的文档 |
|---------|--------------|
| `app/models/` | 架构文档（数据模型部分） |
| `app/api/v1/endpoints/` | API 文档、PRD（功能描述） |
| `app/core/config.py` | 部署文档、环境配置 |
| `app/services/` | 架构文档（业务逻辑部分） |
| `app/adapters/` | 通信适配文档 |
| `app/dlms/` | 协议栈文档 |
| 前端页面/路由 | PRD（功能描述） |

#### Step 3：逐项更新

对每个需要更新的文档：
1. 读取当前内容
2. 展示计划修改的内容
3. 等待确认
4. 应用修改

#### Step 4：验证

- 检查文档中的代码示例是否仍正确
- 检查表格数据是否与代码一致
- 检查链接是否有效

### 模式 B：创建新文档

#### 文档类型

| 类型 | 模板 |
|------|------|
| 技术方案 | 标题 + 背景 + 方案 + 对比 + 决策 |
| API 文档 | 端点 + 参数 + 响应 + 示例 |
| 操作手册 | 前置条件 + 步骤 + 验证 + 常见问题 |
| 变更记录 | 日期 + 版本 + 变更内容 + 影响 |

#### 文档规范

- 使用中文编写
- Markdown 格式
- 代码块标注语言类型
- 表格用于对比和参数说明
- 标题层级不超过 4 级

### 模式 C：文档审查

检查项：
- [ ] 内容与当前代码一致
- [ ] 代码示例可运行
- [ ] API 路径和参数正确
- [ ] 架构图与实际一致
- [ ] 无过时的信息
- [ ] 链接有效

## 报告和文档约定

- 所有文档放在 `docs/` 目录
- 文件名使用 kebab-case：`tech-review-and-architecture.md`
- 日期格式：`YYYY-MM-DD`
- 版本号：语义化版本 `MAJOR.MINOR.PATCH`