affaan-m--everything-claude-code/docs/zh-CN/commands/update-docs.md

更新文档

将文档与代码库同步，从单一事实来源文件生成。

步骤 1：识别单一事实来源

来源	生成内容
package.json 脚本	可用命令参考
.env.example	环境变量文档
openapi.yaml / 路由文件	API 端点参考
源代码导出	公共 API 文档
Dockerfile / docker-compose.yml	基础设施设置文档

步骤 2：生成脚本参考

1. 读取 package.json (或 Makefile, Cargo.toml, pyproject.toml)
2. 提取所有脚本/命令及其描述
3. 生成参考表格：

| Command | Description |
|---------|-------------|
| `npm run dev` | 启动带热重载的开发服务器 |
| `npm run build` | 执行带类型检查的生产构建 |
| `npm test` | 运行带覆盖率测试的测试套件 |

步骤 3：生成环境文档

1. 读取 .env.example (或 .env.template, .env.sample)
2. 提取所有变量及其用途
3. 按必需项与可选项分类
4. 记录预期格式和有效值

| 变量 | 必需 | 描述 | 示例 |
|----------|----------|-------------|---------|
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | 否 | 日志详细程度（默认：info） | `debug`, `info`, `warn`, `error` |

步骤 4：更新贡献指南

生成或更新 docs/CONTRIBUTING.md，包含：

• 开发环境设置（先决条件、安装步骤）
• 可用脚本及其用途
• 测试流程（如何运行、如何编写新测试）
• 代码风格强制（linter、formatter、预提交钩子）
• PR 提交清单

步骤 5：更新运行手册

生成或更新 docs/RUNBOOK.md，包含：

• 部署流程（逐步说明）
• 健康检查端点和监控
• 常见问题及其修复方法
• 回滚流程
• 告警和升级路径

步骤 6：检查文档时效性

1. 查找 90 天以上未修改的文档文件
2. 与最近的源代码变更进行交叉引用
3. 标记可能过时的文档以供人工审核

步骤 7：显示摘要

文档更新
──────────────────────────────
已更新：docs/CONTRIBUTING.md（脚本表格）
已更新：docs/ENV.md（新增3个变量）
已标记：docs/DEPLOY.md（142天未更新）
已跳过：docs/API.md（未检测到变更）
──────────────────────────────

规则

• 单一事实来源：始终从代码生成，切勿手动编辑生成的部分
• 保留手动编写部分：仅更新生成的部分；保持手写内容不变
• 标记生成的内容：在生成的部分周围使用 <!-- AUTO-GENERATED --> 标记
• 不主动创建文档：仅在命令明确要求时才创建新的文档文件