biostat-principles

# 生物统计行为六原则 本文件是 **所有执行类 skill 的上游约束**。Karpathy 的 4 条通用 LLM 编码原则在这里被本地化为生物统计/流行病学语境，并额外追加 2 条本领域硬要求。 > **适用边界**: 这些原则偏"谨慎优先"。对极小任务（1-2 行代码修改、显而易见的笔误修正、无歧义的单文件重命名），可走 **§8 trivial 豁免通道** 跳过前置确认。 --- ## 原则 1 · 先问清口径（Think Before Coding） **不假设、不藏困惑、不替用户决定。** 开工前必须完成以下自检，**任何一项答不出就停下来问用户**： - [ ] **研究问题**：PICOS / PECO 能不能一句话说清？暴露、结局、对象、比较器、时间窗是什么？ - [ ] **数据来源**：用哪个数据集、哪张表、哪段时间？原始数据在哪个路径？ - [ ] **纳排标准**：谁入组、谁排除？排除顺序会不会影响样本量？ - [ ] **终点定义**：主要终点是什么？复合终点怎么组合？事件如何判定？ - [ ] **分组口径**：分类变量怎么切？连续变量切不切？切点依据是什么？ - [ ] **分析方法**：主分析用什么模型？为什么是这个不是那个？ - [ ] **敏感性分析**：哪些口径需要替代方案验证？ **当多个口径并存**：不要自己选一个悄悄往下做。**列出所有候选，标出各自适用场景，让用户选**。 **当用户说的不清楚**：不要脑补。**直接指出"这里有歧义，我需要你澄清 X"**，然后停。 --- ## 原则 2 · 最小实现（Simplicity First） **只解决被提出的问题。** - 不要加未被要求的变量、模型、图表 - 不要为"万一以后要用"抽象成函数 / 类 - 不要为"看起来更专业"叠 3 套敏感性分析，除非口径讨论时就列入了 - 不要为不可能发生的分支写防御性代码（比如 `if (!is.data.frame(dat))`，数据就是 data.frame） - **200 行能写完的分析，不要写成 500 行多文件** **自检问**: 一个高年资生物统计师看到这段代码，会不会说"过度工程"？会的话删。 --- ## 原则 3 · 只改必要（Surgical Changes） **改动必须能一一对应到用户请求。** 修改已有脚本时： - 不要顺手改别的变量名、注释、格式 - 不要"顺便"重构看不顺眼的旧代码 - 风格跟随原脚本，即使你觉得 base R 不如 tidyverse —— **不改就是不改** - 发现无关问题 → **写在汇报里提醒用户**，不要自己动手 - 只删除因你这次改动变成孤儿的 import / 变量；**其他"看起来没用"的代码不要碰** **测试**: `git diff` 的每一行，都能回答"这一行为什么必须改"吗？不能就撤销。 --- ## 原则 4 · 可验证目标（Goal-Driven Execution） **把"做 X"翻译成"怎样算 X 做成了"。** | 用户说 | 翻译成可验证目标 | |--------|----------------| | "做个基线表" | 表格列覆盖分组对比 + P 值 + 连续变量 mean±SD / median [IQR]，行覆盖所有预设变量，样本量和主分析一致 | | "跑个 Cox 回归" | HR + 95%CI + P 值 + PH 假设检验 + C-index，样本量与基线表一致 | | "画个 KM 图" | 分层曲线 + 风险表 + log-rank P + 中位随访/中位生存，配色 ggsci | | "改下这个 bug" | 先写一个能复现 bug 的最小脚本，改完跑通它 | **多步任务**，开头先写计划： ``` 1. [步骤] → 验证：[怎么算做完] 2. [步骤] → 验证：[怎么算做完] 3. [步骤] → 验证：[怎么算做完] ``` **强验证标准 = 可自动闭环**；弱验证（"跑起来就行"）= 需要用户反复确认。 --- ## 原则 5 · 可追溯（Traceability）【本领域追加】 **每一个数字都必须能回到它的源头。** - 论文正文写的 P 值 / HR / 样本量，必须能在 `03_tables/` 某张表里找到 - `03_tables/` 里的数字，必须能在 `02_code/NN_xxx.R` 跑出来的对象里找到 - `02_code/` 跑出来的对象，必须能追回 `01_data/rawdata/` 的原始文件 - 中间派生数据必须记录来源脚本和运行时间 **强制更新链**（方法或结果一变，下面这些必须同步）： 1. `02_code/` 被修改的脚本 2. `03_tables/` / `04_figures/` 里对应的输出 3. `07_paper/results.yaml`（结果机器单源 → 派生 `0_result_summaries.md`；下游 `val()` 取数禁手敲） 4. `DECISIONS.md`（如果是方法变动） 5. `SESSION_LOG.md`（无条件） **任何一环缺失 → 任务未完成**。 --- ## 原则 6 · 可复现（Reproducibility）【本领域追加】 **别人拿到你的文件夹，不需要再问你任何问题就能跑出同样结果。** 具体要求： - 所有路径写相对路径，以 **项目根目录** 或 **结果包根目录** 为工作目录 - R 脚本顶部显式 `library()` 所有依赖，不依赖 `.Rprofile` 魔法 - 随机数有 `set.seed()` - 重要分析有 `sessionInfo()` 或 `renv.lock` 记录版本 - `05_reports/` 的结果包必须 **自包含**：数据、脚本、中间结果、图表都在包内 - 脚本之间不靠当前 R 环境变量传值，只靠 `06_results/` 下的落盘文件传值 - **写完脚本必须跑一遍**：用 `Rscript 02_code/NN_xxx.R` 验证无报错、预期输出到位 **复现自检**：关掉 RStudio、重开空白 R session、cd 到项目根、`Rscript 02_code/01_xxx.R` —— 能跑通吗？不能跑通 = 任务未完成。 --- ## 7 · 探索 / 试新方法工作流（"先 backup 验证，确有用再合并"） 用户要"试试新方法 / 优化模型 / 上某个前沿技术"时，**绝不直接改主流程脚本**。固定四步： 1. **隔离试验**：在 `09_backup/<YYYY-MM-DD>_<主题>/` 下新建独立实验脚本（如 `exp_xxx.py`），**复用**主流程的数据集、特征构造、CV 划分、bootstrap、口径常量（`importlib` 动态加载编号脚本或 import 共享模块），**只改要试的那一个变量**（分类器 / 特征集 / CV 方案…）。其余全部与主流程严格对齐，否则对比不公平、结论无效。 2. **公平验证**：试验必须在与主流程**完全相同的分组 CV + 相同选特征 + 相同评价指标**下跑；先用试验复现主流程锁定点估计（对得上才证明口径没漂），再看新方法的差异。每个实验脚本顶部写清"唯一差异是什么"。 3. **判定**：结果写进该 backup 文件夹的 `FINDINGS.md`（数字对比表 + 结论 + 是否合并的建议）。**只有确有稳健提升才合并**（"稳健" = 重复 CV 稳定带 / bootstrap CI 上明显占优，不是单点抽签碰巧高 0.01）。无用 / 持平 → 不合并，结论照样记档（避免以后重复试）。 4. **合并门禁**：合并 = 改主流程脚本；**任何动到主分析方法（分组 / 终点 / 纳排 / 模型 / CV / 选特征口径）的合并必须先问用户**（原则 1）。合并后同步 `DECISIONS.md`（方法变）/ `07_paper/results.yaml`（结果变，→派生 `0_result_summaries.md`）/ `SESSION_LOG.md`（操作）。试验若动了环境（pin 了包版本）而最终不合并 → 还原或在 SESSION_LOG 注明影响。 - 探索脚本永不留 `02_code/`，不进编号流水线。 - 探索同样适用报错红线：实跑 + 全量扫 error/warning，不因"试着玩"跳过。 --- ## 8 · Trivial 豁免通道 以下情形可跳过"先问口径"，直接执行： - 单行 / 几行代码的错别字、拼写、变量名修正 - 显而易见的 bug（报错信息指明了原因） - 用户明确指定 "不要问直接做" / "按默认就行" - 只涉及格式化、缩进、注释调整，不改逻辑 - 读取类任务（"给我看 XX 文件") **即使走豁免通道，完成后仍需简述改了什么**，方便用户回溯。 --- ## 9 · 冲突与失败处理 **遇到原则冲突时的仲裁顺序**（高优先级覆盖低优先级）： 1. CLAUDE.md 的 CRITICAL 条款（硬禁止） 2. 用户当轮明确指示 3. 本文件原则 1（口径） → 原则 5（可追溯） → 原则 6（可复现） 4. 本文件原则 2-4（简洁 / 微创 / 可验证） 5. 项目内 DECISIONS.md 的历史决策 6. 各执行类 skill 的具体规则 **失败处理规则**： - 代码跑错 → **不要靠 `tryCatch` 掩盖** → 读报错 → 定位根因 → 修 - 结果不符合预期 → **不要改代码迎合预期** → 先检查数据、口径、假设 - 卡住 > 2 次尝试 → **停下来汇报给用户**，不要反复瞎试 --- ## 10 · 开工前检查清单（强制） 每次启动分析/写作/审查任务，先在回复里明写这 4 件事： ``` 【口径】本次任务的 PICOS/PECO、纳排、终点、主要方法是 ... 【输入】读取 [文件路径]，依赖 [上游脚本/结果] 【输出】落地到 [目标路径]，产物是 [文件/表/图] 【验证】做完了怎么算做完：[可量化标准] ``` **这 4 条填不齐 → 暴露了口径不清 → 先问用户，不要开工**。 对 trivial 任务可压缩成一行，但不能省略。 --- ## 11 · 与其他 skill 的关系 - `r-biostats`：执行层。本文件是"怎么想"，r-biostats 是"怎么做" - `academic-publishing`：本文件原则 5（可追溯）是论文数字一致性的底层约束 - `consulting-delivery`：本文件原则 6（可复现）是咨询交付包的底层约束 - `epi-project-audit`：审查时逐条对照本文件 6 条原则 - `humanizer-zh`：交付文档前对照其规则去 AI 味 **所有执行 skill 冲突时，本文件优先级更高**（除非 CLAUDE.md 明文覆盖）。