research-dev-standards

name

research-dev-standards

description

Enforces minimum-viable experimental design, evidence-based reasoning, test-driven development, tmux-first long-running sessions, Docker-first reproducible experiment environments, small incremental changes, and pre-completion review. Use whenever a research idea is being turned into an experiment, including feasibility checks, exploratory or pilot experiments, experiment design, baselines, ablations, resource budgeting, research/training code, GPU/server environments, experiment execution, or experiment documentation; also trigger when the user mentions 想法验证, 探索性实验, 预实验, 实验设计, 最小可行性, 最小可行实验, 科研开发规范, Docker first, tmux first, Docker, or tmux.

科研开发与实验设计规范（Lab Codex）

在协助科研与开发时，默认遵循以下规范；与用户明确指令冲突时，以用户指令为准。

一、基础原则

基于证据

• 分析、结论、方案须建立在实际代码、运行输出、实验指标或数据之上。
• 在缺少可核验证据时，不臆测、不过度自信；应说明假设、建议如何验证（读代码、跑测试、小规模实验）。

测试驱动开发

• 先有可执行的验证手段（单元测试、脚本断言、或约定的可视化/数值检查），再扩展实现。
• 功能到位后，用可视化与数据核对效果，再合并或宣称完成。

顺序执行

• 按约定步骤推进，不擅自跳过某一步。
• 若某步受阻：先说明阻塞原因与可选方案，与用户沟通后再继续；仅在用户明确授权时可临时跳过。

小步迭代

• 避免单次提交中堆叠大量未验证的模块、损失项或配置分叉。
• 优先小范围改动 → 验证 → 再下一处。

探索性实验：先过最小可行性门

• 当用户提出任何新研究想法、方法改动或实验设想时，先设计最小可行实验（Minimum Viable Experiment, MVE），再决定是否实现完整系统或启动大规模训练。
• 在开始任何实验之前，首先回答：这个最小实验要验证什么？成功的标准是什么？ 若不能给出清晰、可测量的答案，停止执行并继续收敛实验问题。
• 把“最小”理解为：以最低资源成本获得足以改变下一步决策的可信证据；不要把它误解为代码最少、样例最少或做一个无法代表真实问题的玩具演示。
• 优先验证整个方向中风险最高、最可能使项目失效的核心假设。若实验同时混入多个新机制，先拆成能单独归因的实验。
• 未明确核心假设、判定阈值、资源上限和结果分支时，不进入高成本执行阶段。

设计实验前，先给出一张最小可行实验卡：

1. 第一问题：这个最小实验要验证什么？成功的标准是什么？ 分别写出一句可证伪的验证目标和一个预先确定、可测量的成功阈值；不得用“效果不错”“看起来可行”等主观表述代替。
2. 最高风险假设：指出哪个前提一旦不成立，后续系统即失去继续投入的价值。
3. 最小实验：只保留检验该假设所必需的数据、模块、训练步骤和输出；说明删掉了哪些非必要部分。
4. 对照与基线：至少提供一个最弱但有效的 baseline、control 或 sanity check，使结果能够归因，而不只是证明代码能运行。
5. 其余判据：在第一问题已经定义成功标准的基础上，再预先写明反驳和无法判定的可测量条件；判据尽量接近二元，但必须保留“证据不足”分支。
6. 资源上限：预先限定时间、GPU 小时、样本量、分辨率、训练步数和允许尝试的配置数。默认先问：“如果只有一天，怎样获得最有判别力的结果？”
7. 最低复现证据：保留代码版本、可复制命令、配置、数据切片、随机种子、环境、日志、原始输出和产物路径；可以降低系统完整度，不得降低证据完整度。
8. 决策分支：实验前写清结果为支持、反驳或无法判定时分别采取的下一步，以及停止继续投入的条件。

执行最小化时遵循以下顺序：

• 先用极少样本完成数据流、维度、损失、指标和可视化的 smoke test；涉及学习时优先做单 batch 过拟合检查。
• 在不破坏核心假设的前提下，优先复用预训练模型、冻结 backbone、缓存特征、降低分辨率或序列长度、缩小数据子集，并考虑 LoRA / Adapter 等参数高效微调。
• 只改变一个关键机制，固定其余变量；不要用同时加入多个模块的结果声称某一机制有效。
• 最小实验通过预设门槛后，才允许扩大数据、模型、训练时长或系统复杂度，并且每轮只扩大一个主要维度。

根据结果作出明确处理：

• 支持：把结论限制在当前数据、指标和资源边界内；下一轮只增加一层复杂度，并设置新的门槛。
• 反驳：先区分原理失败、实现失败和测量失败，再决定修正、转向或终止；不得把一次未跑通直接等同于科学假设被推翻。
• 无法判定：优先提高实验的判别力、检查方差与测量敏感性；不得默认通过扩大算力掩盖设计问题。

研究循环

• 每个重要实验或分析都应写成一个可校正循环：假设 / 设置 / 预测 / 结果 / 更新后的判断 / 下一步最小动作。
• 在运行前写下预测，训练对模型、数据、baseline、损失项和指标的品味；不要只在看到结果后解释。
• 优先缩短发现错误的时间：单命令运行、单命令画图、可复现 config、小数据切片、单 batch 过拟合检查。
• 看指标前后都要检查原始输出：可视化、失败样本、日志、几何结果、视频、渲染图或数据样例。
• 对失败样本做聚类：先攻击最大的失败堆，再决定是否扩大实验规模。
• 任何新增方法结论都要经受 baseline 调参、最小 ablation、数据/评价边界检查。

实验环境优先级：tmux first + Docker first

• 默认路线：tmux first 保证长任务不中断，Docker first / Docker Compose 保证环境可复现。
• 需要在服务器上跑实验、训练、下载数据、编译或长时间配置环境时，先进入 tmux 会话，再启动命令；不要把长任务裸跑在普通 SSH shell 里。
• 宿主机只保持最小稳定层：SSH、tmux、NVIDIA Driver、Docker、Docker Compose、NVIDIA Container Toolkit、存储挂载。
• 项目依赖默认进入容器：CUDA runtime、Python、PyTorch、系统库、编译依赖、项目包版本。
• 配新服务器或新项目环境时，先检查：
  • 项目是否已有 Dockerfile / docker-compose.yml / .devcontainer；
  • 服务器是否通过 nvidia-smi、docker --version、docker compose version；
  • docker run --rm --gpus all ... nvidia-smi 是否能看到 GPU；
  • 代码、数据、cache、checkpoints、outputs 是否挂载到稳定目录。
• 只有 Docker 不可用、权限不足或临时救急时，才用 conda / pip-on-host / system package 作为 fallback，并在结果中说明原因。
• 不静默接受 Anaconda Terms of Service，不随意修改全局 conda channels，不把项目依赖散装到宿主机。
• 环境完成的最低标准：容器内跑通项目最小验证命令，例如 nvidia-smi、核心 Python import、单 batch overfit、dry run 或 smoke test。

大文件下载与断线恢复协议

下载模型权重、数据集、预训练资产或其他大文件时，默认把下载视为可恢复、可验证的实验基础设施，而不是一次性 shell 命令：

• 服务器下载必须先进入独立的 tmux 会话；SSH/VPN 断开后只重新连接并恢复会话，不从头启动下载。
• 下载工具必须支持断点续传、自动重试、连接/读取超时和退避等待；VPN 不稳定时默认降低并发，避免用高并发掩盖网络问题。
• 下载到临时文件（例如 .part），完整下载并通过校验后再原子改名为最终文件；训练或实验程序不得读取未验证的临时文件。
• 下载前检查稳定挂载点、剩余磁盘空间和解压空间；数据、模型、cache、checkpoint、日志和 outputs 不得只存在于 /tmp、容器临时层或 SSH 会话目录。
• 为每个下载记录 manifest：资源名称、来源 URL、仓库 revision/tag/commit、配置或 split、预期大小、SHA256、目标路径、下载时间和工具信息。不得用未固定的 latest 作为实验依赖。
• 下载完成后必须验证 SHA256；若上游未提供哈希，至少验证文件大小、压缩包完整性、目录结构和随机读取结果，并明确记录降级验证。
• 验证通过后再做最小可用性测试：模型至少完成配置/tokenizer/权重索引读取或一次最小推理；数据集至少完成样本计数、随机读取和一个最小 batch。
• 校验失败、空间不足或下载中断时，不得把文件标记为可用；保留错误日志和恢复状态，修复后从断点继续并重新校验。
• 下载来源应使用官方仓库或用户指定来源；切换镜像、版本、数据配置或文件格式时，必须记录原因并更新 manifest。

完成前审查

• 在宣称功能完成前，做一次针对性审查，重点包括：
  • 关键张量/数组的维度变换是否与数据管线一致；
  • 输入输出形状与 API 契约；
  • 分支与边界下的逻辑是否正确。

---

二、文档维护（仓库根目录相对路径）

路线图：RoadMap.md

• 在讨论与实现功能过程中同步更新。
• 记录：当前分支相关功能、已知问题、待办与优先级（简明、可执行）。

实验记录：Notion（不再维护 docs/Experiment.md / 根目录 Experiment.md）

• 实验记录的权威落点是 Notion 实验页；不要新建或继续更新仓库内 Experiment.md，除非用户明确要求临时例外。

• 写作结构与验收以 experiment-report-writing 为准：章节标题用简短英文序号（1. Settings、2. Preprocess、3. Quantity、4. Quality、5. Next、6. Pause、7. Appendix），正文默认中文；结论 callout 用灰色背景；1. Settings 只写方法改动 + 压缩 实验metadata（对齐 Var. Geometry Prior 风格），不堆负责人/机器/长假设/评测流程；平台写入走 research-doc-workflow → notion-doc-workflow。

• 每次重要实验都要在运行前创建 Notion 条目/页面，预先写下验证目标、成功标准、设置和预测；实验结束后再补充结果与判断。不得只在看到结果后回填实验目的或修改成功标准。

• 每条记录在标题之后的第一个块必须是 结论 callout，并严格回答：

  > [!结论]
  > **第一问题：这个最小实验要验证什么？成功的标准是什么？**
  > - 验证目标：<一句可证伪的陈述>
  > - 成功标准：<预先确定的指标、阈值或明确的可观察条件>
  

• 在第一问题 callout 之前不得先写命令、模型结构、超参数或结果。该 callout 必须在运行前冻结；看到结果后不得回改验证目标或成功标准，目标发生变化时应创建新的实验条目。若两个答案无法写清楚，将实验保持为“待设计”，不要启动训练或批量运行。

• 后续依次记录：状态、最高风险假设、最小实验、对照与基线、反驳/无法判定条件、资源上限、运行前预测、完整或可复制命令、Docker 镜像/Compose 文件/容器入口、关键超参与环境说明、主要结果（指标/现象）、失败样本/原始输出观察、更新后的判断、下一步最小动作、产物路径（检查点、日志、图表、视频等）。失败或已暂停时还必须有暂停记录。

Q&A 归档

• 对用户问题在基于代码与数据给出可靠解答后，将问题摘要 + 结论要点 + 必要时引用路径/命令写入归档。
• 默认归档文件：若不存在则创建 docs/Q&A.md（若项目已另有约定文件，则写入约定处并在此 skill 中保持一致）。

---

执行清单（代理自检）

开始复杂任务前可快速对照：

• 实验记录是否在运行前创建，并在标题后的第一个 结论 callout 回答“验证什么、成功标准是什么”？
• 结论是否有代码/运行/实验依据？
• 是否有测试或可重复验证步骤？
• 是否按步骤执行，未擅自跳步？
• 改动是否小步、可回滚？
• 新想法是否先写出最小可行实验卡，而不是直接搭建完整系统？
• 是否锁定最高风险假设，并设置可测量判据、资源上限与停止条件？
• 是否具备 baseline / control / sanity check，能够区分原理、实现和测量失败？
• 实验/分析是否写下 假设 / 设置 / 预测 / 结果 / 更新后的判断 / 下一步最小动作？
• 长任务是否先进入 tmux 会话，而不是裸跑在 SSH shell？
• 实验环境是否优先走 Docker/Compose，而不是散装到宿主机？
• 是否验证了容器内 GPU、核心 import、smoke test 或单 batch 运行？
• 大文件下载是否在独立 tmux 会话中运行并支持断点续传与自动重试？
• 是否使用 .part 临时文件，并在校验通过后才改名为最终文件？
• 是否记录了固定版本、来源、大小、SHA256、目标路径和下载日志？
• 下载后的模型或数据集是否通过了最小读取/推理/batch 验证？
• 是否检查了原始输出和失败样本，而不只看平均指标？
• 是否有单命令运行、画图、config 或小数据验证来缩短发现错误的时间？
• 完成前是否核对维度与形状与核心逻辑？
• 是否更新了 RoadMap.md / Notion 实验记录 / Q&A 归档（如适用）？

附加资源

• 以 .tools/skills/research-dev-standards/SKILL.md 为 Lab Codex 的权威副本；~/.codex/skills/research-dev-standards 仅作为兼容 symlink。
• 若研究仓库内存在重复的根目录 skills.md，将其改为指向本 skill 的简短说明，避免双源漂移。