experiment-hygiene - SKILL.md Agent Skill

name: experiment-hygiene description: 实验前的纪律检查清单。在运行 AI agent 实验、基准测试、仿真优化前自动提醒关键纪律：commit 代码、冻结修改、记录 baseline、版本对应。触发词："跑实验"、"benchmark"、"开始测试"、"run experiment"。

实验卫生检查（Experiment Hygiene Checklist）

核心原则

每个实验必须对应一个确定的代码版本。 边跑边改会让结果无法复现，出了问题也无法回溯。

触发时机

当用户表达以下意图时自动触发：

"跑实验"、"开始实验"、"run experiment"
"benchmark"、"基准测试"、"开始测试"
"跑 case"、"测试模型"
"开始优化"、"调参"

检查清单

在执行任何实验操作之前，必须逐项确认：

1. 代码状态检查

git status

必须满足：

工作区干净（no changes not staged for commit）
没有未跟踪的关键文件（scripts/、skills/、config/ 下的文件）
当前分支正确（不是 main/master）

如果工作区不干净：

提醒用户：
"工作区有未提交的改动。建议先 commit 再跑实验，否则实验对应的代码版本不确定。"

等待用户决定：
- 立即 commit 当前改动
- 继续（接受风险）
- 暂停实验，先整理代码

2. 分支检查

git branch --show-current
git log --oneline -1

必须满足：

在专用实验分支上（如 feature/xxx-experiment、experiment/xxx）
不在 main/master/develop 上直接跑实验

如果分支不对：

提醒用户：
"当前在 {branch} 分支。建议创建专用实验分支：
  git checkout -b experiment/{name}-{date}
  
这样实验结果和代码改动都隔离在这个分支上。"

3. Baseline 确认

必须满足（至少一项）：

已有 baseline 结果文件（baseline_results.json 或类似）
计划在本次实验中先跑 baseline
用户明确说明"不需要 baseline"

如果没有 baseline：

提醒用户：
"没有发现 baseline 结果。建议：
1. 先用默认参数/当前配置跑一次 baseline
2. 记录 baseline 指标（纯度、成本、产率、迭代次数等）
3. 后续优化结果才有对比基准

是否现在跑 baseline？"

4. 结果记录计划

必须明确：

结果输出目录已确定（如 workspace/results/experiment-{date}/）
日志/JSON 输出格式已定义
知道要记录哪些指标

如果结果计划不明确：

提醒用户：
"实验结果会输出到哪里？建议：
1. 创建专用结果目录
2. 定义输出格式（JSON、TSV、日志文件）
3. 明确要记录的指标

我可以帮你设置结果记录结构。"

5. 时间预期

必须明确：

单次实验预计耗时
总实验轮次/迭代次数
是否使用后台执行（background=true）

如果时间预期不明确：

提醒用户：
"预计这次实验要跑多久？
- 如果 > 5 分钟，建议用 background=true 后台执行
- 如果 > 30 分钟，建议分批或检查参数是否合理
- 如果不确定，先跑 1 轮估算总时间"

执行流程

用户："跑实验"
  ↓
Agent：触发检查清单
  ↓
逐项检查（git status、分支、baseline、结果计划、时间预期）
  ↓
[全部通过] → 开始实验
[有未通过项] → 提醒用户 → 等待决定
  ↓
实验开始
  ↓
实验过程中：
  - 不修改 scripts/、skills/、config/ 下的文件
  - 只修改结果目录下的文件
  - 如需改代码，先停止实验 → commit → 重新跑

实验中的纪律

禁止操作

实验运行期间不要：

❌ 修改 scripts/ 下的仿真脚本
❌ 修改 skills/ 下的 skill 定义
❌ 修改 config.yaml、settings.json 等配置
❌ 修改 aspen_com_api.py 等核心 API
❌ 在终端里手动改参数（应该通过脚本统一改）

允许操作

实验运行期间可以：

✅ 读取结果文件（read_file results.json）
✅ 查看日志（tail -f experiment.log）
✅ 在新分支上规划下一次实验
✅ 写实验报告/文档

如果必须改代码

1. 停止当前实验（kill 进程或等它跑完）
2. git commit 当前实验结果
3. 改代码
4. git commit 代码改动
5. 重新跑实验（从 baseline 开始）

实验后检查

实验跑完后：

1. 结果验证

结果文件存在且非空
指标在合理范围内（不是 NaN、不是极端值）
与 baseline 对比有意义（有改进或发现瓶颈）

2. 版本记录

git log --oneline -1
git diff HEAD

记录实验对应的 commit hash
确认实验期间没有未提交的代码改动

3. 结果提交

git add workspace/results/experiment-{date}/
git commit -m "experiment: {描述} | baseline={X} | best={Y}"

结果文件已 commit
commit message 包含关键指标

快速参考

实验前：
  git status              # 工作区干净？
  git branch              # 在实验分支？
  ls baseline_results.*   # 有 baseline？
  
实验中：
  不改 scripts/skills/config
  只改 results/
  
实验后：
  git add results/
  git commit -m "experiment: ..."
  git log --oneline -1    # 记录 commit hash

反例：为什么需要这个清单

场景 1：边跑边改

用户："跑 case 1 试试"
Agent：开始跑实验（耗时 10 分钟）

[2 分钟后]
用户："哎，把回流比上限调高一点"
Agent：改了 scripts/optimize.py

[5 分钟后]
用户："再加个成本计算"
Agent：改了 aspen_com_api.py

[10 分钟后]
实验跑完，结果出来了。

问题：
- 这个结果对应哪个版本的代码？
- 前 2 分钟用的是旧代码，后 8 分钟用的是新代码
- 出了问题无法复现
- 无法判断是哪个改动起了作用

场景 2：忘记 commit

用户："跑实验"
Agent：跑了 20 轮优化，结果很好

用户："这个结果对应的代码是哪个版本？"
Agent：git status 显示有 15 个文件未提交

问题：
- 不知道这 15 个改动是实验前就有还是实验中改的
- 无法确定"最佳结果"对应的确切代码状态
- 想回滚到某个中间状态也做不到

场景 3：没有 baseline

用户："优化这个 case，目标是纯度 > 99%"
Agent：跑了 10 轮，达到 99.5%

用户："改进多少？"
Agent："不知道，没跑 baseline"

问题：
- 可能 baseline 就是 99%（改进 0.5%）
- 也可能 baseline 是 80%（改进 19.5%）
- 无法判断优化是否有效
- 无法对比不同模型/策略的效果

自动化建议

可以在 .claude/settings.json 中设置 hook，在检测到实验相关操作时自动触发检查：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "terminal.*python.*experiment|terminal.*python.*benchmark|terminal.*python.*optimize",
        "command": "echo '⚠️ 实验前请确认：git status 干净、在实验分支、有 baseline、结果计划明确'"
      }
    ]
  }
}

或者更简单：每次说"跑实验"时，Agent 自动执行 git status 并检查结果目录是否存在。