把"大概能跑"变成"每次都能跑"：本地复现流程

**具体场景**：你写了一个自动化脚本，在自己的机器上跑通了，发给同事，他回一句："我这里报错了。"或者更糟——三个月后你自己再跑，等着修环境。这种"在我这里能跑"的尴尬，根因不是代码写得差，而是**你没有把复现流程当成交付物的一部分来写**。

这是什么技能

本地复现流程（Local Reproduction Protocol）指：在交付任何脚本、配置、工作流之前，用一段固定步骤描述"一个陌生人在干净环境上如何从零复现你的结果"，并且自己按这套步骤走一遍。它不是文档，是**可执行的验证协议**——能跑通它，才算真的跑通。

什么时候用

- 交付给别人执行的脚本或工作流（内部工具、CI 任务、数据管道）

- 你依赖第三方 API / 数据库 / 容器，但对方环境和你不完全一致

- 你自己要维护的工具，超过 30 天没重新跑过

- 任何"我跑过就是证明"要变成"他能跑才是证明"的场合

什么时候别用

- 一次性数据分析、当天就结束——写复现文档比分析本身还慢，直接录屏或截图

- 对方和你环境完全一致（同一台机器、同一个容器）——复现是多余的

- 需求还在剧烈变动、代码今天刚改第三版——流程写下来就是废纸

怎么做（5 步）

1. **假设读者是"刚入职的陌生人"**：不要用"运行那个脚本"这种模糊表述，写完整的命令，包括工作目录、参数、环境变量。

2. **列出所有隐式依赖**：Python 版本、Node 版本、数据库里必须存在的表、API 密钥从哪个文件读、时区设置。这些是"在我这里能跑"的头号杀手。

3. **写一条最少路径**：不是把所有功能都跑一遍，而是只跑核心功能的最短路径。目标是"5 分钟内能判断环境对不对"，不是"验证所有边界情况"。

4. **自己按这套流程从零跑一遍**：在全新终端、全新目录（或干净容器）里执行。任何一步卡住，就是你交付物的 bug，不是用户的 bug。

5. **把流程放进交付物里**：README 的 "Quick Start" 段，或者项目根目录的 `REPRODUCE.md`。别只放在脑子里或聊天记录里。

Gotchas

- **坑 1——"差不多就行"**：步骤写"安装依赖"不算数，要写 `pip install -r requirements.txt`，且 requirements.txt 是锁定的（用 `pip freeze` 生成或 `poetry lock`）。

- **坑 2——环境漂移**：三个月后你的机器和你写流程时的机器已经不一样了。每次交付前务必在当前机器上新鲜跑一遍，不要相信"上次跑过"。

- **坑 3——把复现当测试**：复现流程验证的是"环境能不能跑"，不是"代码逻辑对不对"。两者都要做，但混在一起会漏。

- **坑 4——只写成功路径**：至少要写一条"如果第一步就失败，最可能的原因是 XXX"，这能帮别人（和三个月后的你）省下大量排查时间。

最小启动版

今天就能用的模板，放进项目根目录 `REPRODUCE.md`：

# 复现步骤（2026-09-02）

## 环境要求
- OS: macOS 14+ / Linux (glibc 2.31+)
- Python: 3.12.x（不是 3.11，见坑 2）
- 需要 .env 文件（模板见 .env.example）

## 最少路径（约 3 分钟）
1. python -m venv .venv && source .venv/bin/activate
2. pip install -r requirements.lock
3. cp .env.example .env  # 填入 REAL_DB_HOST
4. python main.py --quick-check
   预期输出："OK: 3/3 checks passed"

## 如果第 4 步失败
- `ModuleNotFoundError`：检查是否用了第 1 步的 venv
- `Connection refused`：.env 里 DB_HOST 是不是 127.0.0.1

"在我这里能跑"是最低标准，"按我的步骤在干净环境能跑"才是交付标准。这个区别，就是你和"靠谱"之间的距离。