# Reproduce

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

- Skill: `xlinsist/reproduce` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xlinsist/reproduce`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xlinsist/reproduce/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xlinsist (https://skillmd.com/u/xlinsist)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xlinsist/reproduce

---


# 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、动态库或额外环境变量，不要只记录报错，要尽量把可运行环境整理出来。
5. 先跑通 MVP，再决定是否跑完整实验。
   不要一上来就投入长时间完整实验。先证明环境、命令和最小实验链路是通的。
6. 先做正确性，再做性能。
   明确区分“能不能跑对”和“跑得多快”。
7. 如果有首次编译、缓存填充或初始化成本，要和稳态性能分开写。
8. 最后补齐复现材料。

## 输出目录约定

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

## 基线选择原则

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

## 复现部分必须包含什么

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

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

如果适用，补上：

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

## 报告风格

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

## Git 与产物管理

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

## 常见误区

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