tutorial-authoring

# 项目教程创作与重写 以“读者能理解、代码能复现、论断能核验、页面能正常打开”为完成标准。篇幅、代码比例和图片数量由教学目标决定，不使用固定行数、70/30 比例或“每篇至少一张示意图”代替质量判断。 ## 开工 1. 读取仓库 `CLAUDE.md`、目标文章、同栏目相邻文章和对应 `section-*` skill。 2. 完整读取 [quality-standard.md](references/quality-standard.md) 与 [comparison-and-visuals.md](references/comparison-and-visuals.md)。根据文章类型再读取 [article-archetypes.md](references/article-archetypes.md)。 3. 新建文章前检查编号、文件名、主题重复和 `_quarto.yml` 位置；重写时保留稳定 URL，除非用户明确要求改名。 4. 把用户给出的文章、帖子或宣传文案视为线索，不视为事实单源。版本、函数、统计方法和当前功能必须回到官方文档、论文或实际环境核验。 ## 写作合同 在编辑前锁定：目标读者、读完能完成的任务、必要前置知识、核心概念、最易误解之处、代码环境、需要的图件和验收页面。按 `comparison-and-visuals.md` 判断是否存在会妨碍当前任务的相邻方法或工具；只有确有混淆风险时才建立 2–4 个候选的辨析清单。若选错方法会使后续代码或解释跑偏，在正文前段先完成定位，再进入公式、参数或核心函数。缺少会改变方法、终点或工具选择的信息时先问；其余使用保守假设继续。 文章围绕学习问题组织，不机械套统一目录。完整教程通常应让读者依次知道：为什么需要、适用与不适用、关键原理、最小可运行例子、真实工作流、如何诊断、怎样解释、常见错误和进一步学习。 ## 证据与代码 - 统计与流行病学方法先遵循 `biostat-principles`；需要方法、报告规范或最新功能时使用 `evidence-research`。 - R 包教程核对官方仓库或 CRAN/Bioconductor 元数据、当前版本、函数签名、返回对象和许可证。不要复述宣传数字而不核验。 - 所有声称可运行的代码必须实跑。模拟数据应具有与教程问题一致的生成机制，不能把暴露、事件或删失独立拼接后解释为方法效果。 - 示例输出只用于教学，不写成研究发现。随机过程设置种子，但不要求全站固定同一个种子。 - 外部依赖缺失时按项目规则处理；不得在教程构建中静默安装系统依赖，也不得为通过渲染换用不同方法。 ## 图件 先按 `comparison-and-visuals.md` 判断应使用段落、表格、流程图、概念图、统计图还是真实截图，再为每个候选图位写一句“删除这张图会失去什么理解”。没有独立贡献就不生成；表格和图不能逐字重复。 - 统计关系、模型诊断和模拟结果：用真实代码输出，遵循 `publication-figures`。 - 软件界面、终端、Typst/PDF 页面和文档结果：运行或渲染真实产物后截图。 - 流程、机制和概念框架：遵循 `research-visuals`；不要把手写 SVG 当作默认捷径。 - 每张图提供准确替代文本，正文解释读图重点和方法边界。封面与文内图都不是强制数量指标。 ## 验证 1. 运行 `python .claude/skills/tutorial-authoring/scripts/audit_tutorial.py <文章...>`。 2. 抽取并实跑所有可执行代码；检查完整输出中的 `error|warning|traceback|failed|nan`，逐项修复或解释。 3. 对 Typst、命令行或包接口运行实际示例；不把语法看起来合理当作验证。 4. 只渲染目标文章、受影响 section 和 `index.qmd`，禁止以教程修改为由全站渲染。 5. 更新 `_quarto.yml` 后运行 `doc/generate_sections.R`，不要手工维护生成的 section 内容。 6. 检查易混淆项是否在首次使用前得到定位，并检查桌面与移动端可读性：标题层级、表格宽度、代码换行、图中文字、替代文本和链接。 7. 用 `academic-humanizer` 终审正文，删除宣传腔、助手口吻、空泛总结和超出证据的断言。 ## 完成条件 目标文章可渲染；示例代码和真实截图可复现；图件有信息贡献；版本、函数和引文有源；导航与 section 已同步；没有新增未解释 warning；只提交本任务文件且保留用户既有改动。