viewway 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：识别变更
# 查看分支变更
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：逐项更新
对每个需要更新的文档：
- 读取当前内容
- 展示计划修改的内容
- 等待确认
- 应用修改
Step 4：验证
- 检查文档中的代码示例是否仍正确
- 检查表格数据是否与代码一致
- 检查链接是否有效
模式 B：创建新文档
文档类型
| 类型 | 模板 |
|---|---|
| 技术方案 | 标题 + 背景 + 方案 + 对比 + 决策 |
| API 文档 | 端点 + 参数 + 响应 + 示例 |
| 操作手册 | 前置条件 + 步骤 + 验证 + 常见问题 |
| 变更记录 | 日期 + 版本 + 变更内容 + 影响 |
文档规范
- 使用中文编写
- Markdown 格式
- 代码块标注语言类型
- 表格用于对比和参数说明
- 标题层级不超过 4 级
模式 C：文档审查
检查项：
- 内容与当前代码一致
- 代码示例可运行
- API 路径和参数正确
- 架构图与实际一致
- 无过时的信息
- 链接有效
报告和文档约定
- 所有文档放在
docs/目录 - 文件名使用 kebab-case：
tech-review-and-architecture.md - 日期格式：
YYYY-MM-DD - 版本号：语义化版本
MAJOR.MINOR.PATCH