mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-01 06:33:27 +08:00
87 lines
2.8 KiB
Markdown
87 lines
2.8 KiB
Markdown
# 更新文档
|
||
|
||
将文档与代码库同步，从单一事实来源文件生成。
|
||
|
||
## 步骤 1：识别单一事实来源
|
||
|
||
| 来源 | 生成内容 |
|
||
|--------|-----------|
|
||
| `package.json` 脚本 | 可用命令参考 |
|
||
| `.env.example` | 环境变量文档 |
|
||
| `openapi.yaml` / 路由文件 | API 端点参考 |
|
||
| 源代码导出 | 公共 API 文档 |
|
||
| `Dockerfile` / `docker-compose.yml` | 基础设施设置文档 |
|
||
|
||
## 步骤 2：生成脚本参考
|
||
|
||
1. 读取 `package.json` (或 `Makefile`, `Cargo.toml`, `pyproject.toml`)
|
||
2. 提取所有脚本/命令及其描述
|
||
3. 生成参考表格：
|
||
|
||
```markdown
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `npm run dev` | 启动带热重载的开发服务器 |
|
||
| `npm run build` | 执行带类型检查的生产构建 |
|
||
| `npm test` | 运行带覆盖率测试的测试套件 |
|
||
```
|
||
|
||
## 步骤 3：生成环境文档
|
||
|
||
1. 读取 `.env.example` (或 `.env.template`, `.env.sample`)
|
||
2. 提取所有变量及其用途
|
||
3. 按必需项与可选项分类
|
||
4. 记录预期格式和有效值
|
||
|
||
```markdown
|
||
| 变量 | 必需 | 描述 | 示例 |
|
||
|----------|----------|-------------|---------|
|
||
| `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 -->` 标记
|
||
* **不主动创建文档**：仅在命令明确要求时才创建新的文档文件
|