把「大概能跑」變成「每次都能跑」：本機復現流程

**具體場景**：你寫了一個自動化腳本，在自己的機器上跑通了，傳給同事，他回一句：「我這裡報錯了。」或者更糟——三個月後你自己再跑，等著修環境。這種「在我這裡能跑」的尷尬，根源不是程式碼寫得差，而是**你沒有把復現流程當成交付物的一部分來寫**。

這是什麼技能

本機復現流程（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

「在我這裡能跑」是最低標準，「按我的步驟在乾淨環境能跑」才是交付標準。這個區別，就是你和「靠譜」之間的距離。