# Research Dev Standards > 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. - Skill: `jasperpwang/research-dev-standards` (Agent Skill) - Install (CLI): `npx skillmds@latest add jasperpwang/research-dev-standards` - Raw SKILL.md: https://api.skillmd.com/api/skills/jasperpwang/research-dev-standards/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: jasperpwang (https://skillmd.com/u/jasperpwang) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jasperpwang/research-dev-standards --- # 科研开发与实验设计规范（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，并严格回答： ```markdown > [!结论] > **第一问题：这个最小实验要验证什么？成功的标准是什么？** > - 验证目标：<一句可证伪的陈述> > - 成功标准：<预先确定的指标、阈值或明确的可观察条件> ``` - 在第一问题 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 的简短说明，避免双源漂移。