模块写作规范
模块写作规范
供讲师/维护者参照：每个模块（D1-D23）统一由三个文件组成，遵循本规范写作，保证全套文档风格一致。 写作时始终锚定公司真实栈与真实业务，杜绝空泛。
1. 每模块三个文件
| 文件 | 定位 | 篇幅建议 |
|---|---|---|
课程.md | 讲师讲义：教学目标、内容分段、示例、常见误区、讲解节奏 | 120-250 行 |
课件.md | 讲义式课件（可直接转 PPT/PDF）：按幻灯片分段 | 60-150 行 |
作业.md | 作业题 + 步骤 + 验收标准 + 提交方式 | 40-100 行 |
2. 课程.md 结构模板
# Dx 模块名
## 教学目标（学完能做什么）
- 用可验证的动词描述，如"能说出/能写出/能配置/能排查"
## 前置要求
- 依赖哪些前置模块的知识
## 本模块在业务中的位置
- 一段话把本模块挂到公司业务链路上（上游/中游/下游/基础设施）
## 内容分段
### 1. 小节标题
- 要点1（解释）
- 示例/命令（真实可用，标注运行环境）
- 常见误区（学员最容易踩的坑）
### 2. ...
## 讲解节奏建议（90分钟授课）
- 09:00-09:15 引入：为什么学这个 / 在业务里的位置
- ...
## 常见误区汇总
- 表格：误区 | 正确理解3. 课件.md 结构模板
# Dx 模块名 — 课件
> 使用方法：可直接转为 PPT/PDF。每行/每组为一张幻灯片内容。
## 1. 封面
- 标题 / 培训阶段 / 讲师 / 日期
## 2. 目录
- 列出本模块 4-6 个小节
## 3. 每小节幻灯片
### 小节名
- 幻灯1：标题 + 要点（3-5 条）
- 幻灯2：图示/示例命令
- 幻灯3：演示（讲师现场操作项）
- 幻灯4：小结 + 过渡4. 作业.md 结构模板
# Dx 模块作业
## 目标
- 一句话：检验哪个教学目标
## 场景
- 在哪个环境做（测试机/本地/测试集群），贴出真实地址或命令前缀
## 任务
1. 第 1 步（具体可执行，含命令示例）
2. 第 2 步 ...
## 验收标准（讲师核验用）
- [ ] 可勾选项，每项可客观判定
## 提交方式
- 进 docs/training/学员/ 或公司仓库指定目录，按 D6 的 Git 规范提交 PR
- 提交信息中文
## 参考
- 指向本模块 课程.md 小节 / 学习网站.md 条目5. 写作红线
- 贴合公司栈：命令、路径、服务名以 CLAUDE.md / 真实 repo 为准（如
kuse prod、registry.akria.net、sub2api、services/）。 - 业务挂勾：每个模块至少一次明确点出它在"上游→中游→下游"链路里的位置。
- 新人安全：所有集群操作一律标注"只读"或"测试环境"，严禁让新人碰生产写操作。
- 中文：全套文档中文；命令/代码可英文但注释和讲解中文。
- 可验证：示例必须能在公司环境跑通或给出明确替代；验收标准客观可判。
- 不盲信 AI：涉及 Claude Code 的内容反复强调"生成→看懂→验证→提交"。
- 可伸缩：每个模块标注"精讲/标准/略讲"建议，供主人按时间裁剪。