reproduce

name	reproduce
description	当用户希望你在一个代码仓库中完成可复现的构建、实验、对比评测和报告沉淀时使用此 skill。它适用于需要搭建本地环境、运行一个或多个 MVP 实验、记录实验设置与结果、解释性能差异，并输出可复现文档与环境脚本的场景。

Reproduce

当任务目标不是单纯“跑通”，而是“可复现地跑通并沉淀成实验报告”时，使用此 skill。

适用的典型场景包括：

• git clone 一个外部仓库后，重新搭建环境并复现实验
• 先跑最小可行实验，再扩展到完整实验
• 产出可以被后续实验直接复用的结果文档

默认产物

除非用户明确要求否则，默认产出：

• 如有pyhon环境配置，放到仓库内本地环境，例如 venv
• 一个明确的输出目录
• 仓库根目录下的结果文档，优先命名为 RESULT.md
• RESULT.md 中的完整复现命令
• 实验脚本
• 必要时的实验数据汇总文件
• 不适合提交到 GitHub 的临时和中间产物应加入 .gitignore

开始前检查

在真正执行实验前，优先检查以下内容：

• README
• 构建配置
• 测试与 benchmark 入口
• 官方给出的运行方式

报告必须覆盖的内容

结果文档至少要包含：

• 硬件平台与软件版本
• 优化对象
• 基线选择
• 评估指标与评估方法
• 实验设计（想探究什么问题）
• 实验结果
• 结果分析

如果进行了多个实验，结果部分要拆成清晰的小节。编号样式不强制，但必须让读者一眼看出“实验 A”和“实验 B”是分开的。

推荐做法：

• 每个实验一个独立小节
• 每个小节都包含结果、正确性、分析。分析部分解释“为什么会出现这样的差异”。

执行流程

1. 先摸清仓库事实。 优先看 README、构建文件、测试、benchmark 入口、参考实现，不要先凭经验下结论。
2. 先把环境做成“本地可复现”。 优先使用仓库内环境，例如 venv，避免依赖用户 shell 的隐式状态。
3. 处理环境或工具链不一致问题。 如果实验依赖编译器、GPU、特殊 runtime、动态库或额外环境变量，不要只记录报错，要尽量把可运行环境整理出来。
4. 先跑通 MVP，再决定是否跑完整实验。 不要一上来就投入长时间完整实验。先证明环境、命令和最小实验链路是通的。
5. 先做正确性，再做性能。 明确区分“能不能跑对”和“跑得多快”。
6. 如果有首次编译、缓存填充或初始化成本，要和稳态性能分开写。
7. 最后补齐复现材料。

输出目录约定

• 明确指定输出目录，不要把所有产物散落在仓库各处。
• 输出目录中可包含：
  • 日志
  • benchmark 原始结果
  • 汇总表
  • 图表
  • 中间分析脚本
• 结果文档中要写清楚这些文件分别位于哪里。

基线选择原则

• 优先选择语义最接近的基线，而不是“看起来差不多”的实现。
• 如果仓库自带 reference implementation，优先用它。
• 如果没有官方 reference，就用最接近语义的框架原生实现。
• 在报告里必须明确写清楚你比较的到底是什么：
  • 稳态执行 vs 稳态执行
  • 首次调用端到端 vs 直接执行
  • 融合实现 vs 多算子实现
  • 专用 kernel vs 通用路径

复现部分必须包含什么

结果文档里的复现部分至少包含：

• 进入仓库目录
• 激活本地环境
• 导出所需环境变量
• 验证环境是否正确
• 重跑相关 benchmark 或测试
• 重跑报告里实际使用的最小实验命令
• 从 git clone 开始如何复现

如果适用，补上：

• 完整实验命令
• 输出目录说明
• 数据汇总或绘图脚本使用方式

报告风格

• 报告要具体、可执行，不要写成空泛总结。
• 要写清楚 shape、dtype、关键参数、基线定义。
• 正确性和性能分开写。
• 环境问题如果影响复现，必须写出来。
• 如果 benchmark 来自官方测试，要说明。
• 如果 benchmark 来自你临时写的最小脚本，而不是完整官方套件，也要说明。
• 结果文档应能直接被后续实验参考，而不是只服务当前一次执行。

Git 与产物管理

• 如果生成了不适合提交到 GitHub 的临时或中间产物，应加入 .gitignore。
• 常见需要忽略的内容包括：
  • benchmark 原始日志
  • 大型中间数据
  • 缓存
  • 临时导出的二进制文件
  • 本地绘图结果
• 但结果文档、实验脚本、必要的小型汇总文件通常应保留。

常见误区

• 不要省略环境准备细节，尤其是在依赖额外工具链、编译器、动态库或环境变量时。
• 不要在 MVP 未跑通时就直接进入完整实验。