從資料集到分析報告

資料分析的目標不是“分析本身”，而是交付能被別人使用的 artifact：管理層圖表、產品實驗讀數、模型評估、運營 dashboard 或研究備忘錄。

適合什麼任務

flowchart LR
    Raw["raw files"] --> Inventory["inventory"]
    Inventory --> Tidy["tidy / clean"]
    Tidy --> Join["join QA"]
    Join --> Explore["visualize / model"]
    Explore --> Report["report artifact"]
    Report --> Review["review / rerun"]

Codex 適合把資料工作做成可複查流程：

• 清點 CSV、TSV、Excel、JSON、Parquet 等輸入。
• 解釋每份資料的含義、主鍵候選、缺失值和異常。
• 編寫可重跑的清洗指令碼。
• 比較多種 join 策略並報告 match rate。
• 做 exploratory analysis、baseline model 和圖表。
• 生成 Markdown、notebook、.docx、PDF 或靜態報告站點。

不適合讓 Codex 直接“給結論”。沒有 inventory 和 join QA 的結論不能發表。

起始提示詞

我正在这个 workspace 里做 data analysis project。

目标：
- 判断靠近 highway 的 houses 是否有更低的 property valuations。

请先做，不要直接下结论：
- 阅读 AGENTS.md，解释推荐的 Python environment
- 加载 [dataset path] 下的 dataset(s)
- 描述每个文件包含什么、可能的 join keys、明显 data quality issues
- 提出可复现 workflow，覆盖 import、tidy、visualization、modeling、report output

约束：
- 优先使用 scripts 和 saved artifacts，不依赖一次性 notebook state
- 不要编造 missing values 或 merge keys
- 如果需要 skills 或 worktree splits，请说明原因

输出：
- setup plan
- data inventory
- analysis plan
- first commands or files to create

這個 prompt 先要求 Codex 解釋環境、盤點資料和設計 workflow，而不是直接畫圖。資料分析裡，跳過 inventory 和 join strategy 往往是後面結果不可信的根源。

環境先定好

開始新資料專案時，先讓 Codex 讀專案規則並確認環境：

• canonical Python environment。
• package manager。
• raw、processed、analysis、output 目錄。
• notebook 和 script 的關係。
• artifact 命名和復跑方式。

小型 AGENTS.md 就夠：

## 数据分析默认规则

- 使用 `uv run` 或项目现有 Python environment。
- source data 放在 `data/raw/`，cleaned data 写入 `data/processed/`。
- exploratory notebooks 放在 `analysis/`，final artifacts 放在 `output/`。
- 永远不要覆盖 raw files。
- 优先使用 scripts 或已提交 notebooks，不依赖未命名 scratch cells。
- 合并 datasets 前，先报告 candidate keys、null rates 和 join coverage。

如果 repo 還沒有定義 Python 環境，先建立可復現 setup 並說明執行方式。對資料分析來說，這一步比直接畫圖更重要。

先做資料盤點

第一輪只問 inventory，不問結論。讓 Codex 回答：

• 這裡有哪些 file formats。
• 每份 dataset 似乎代表什麼。
• 哪些 columns 可能是 target、identifier、date、location 或 measure。
• 明顯資料質量問題在哪裡。
• 哪些欄位不能直接用於 join。
• 哪些列需要抽樣或隱私處理。

盤點輸出應該儲存到專案裡，例如 analysis/inventory.md 或 output/data-inventory.md。不要只把結論留線上程裡。

Tidy 和 Merge

真實資料最容易在 merge 出錯。primary key 不清楚時，naive merge 可能丟資料，也可能製造重複。

在真正 merge 前，讓 Codex 先 profile：

• 檢查 candidate keys 的 uniqueness。
• 測量 null rates 和 formatting differences。
• 歸一化 casing、whitespace、address formatting 等明確問題。
• 跑 trial joins 並報告 match rates。
• 寫出 safest merge strategy，再生成 final merged file。

如果需要派生 key，例如 normalized address、parcel identifier 或 location join，讓 Codex 先解釋 tradeoffs 和 edge cases。

探索和建模

Exploratory data analysis 適合隔離。一個 worktree 試 address cleanup 或 feature engineering，另一個 worktree 做 charts 或 alternate model direction。這樣每個 diff 更容易 review，也避免一個長執行緒混合互斥想法。

git worktree add ../analysis-highway-eda -b analysis/highway-eda
git worktree add ../analysis-model-comparison -b analysis/highway-modeling

建模時先用可解釋 baseline。要求 Codex 明確說明：

• target variable 和 feature definitions。
• controls 選擇及原因。
• leakage risks 和 exclusions。
• split、evaluation 或 uncertainty estimate 的選擇。
• 結果的自然語言解釋。

第一版模型弱也有價值。它能告訴你問題出在 model、features、join quality，還是問題本身定義不清。

交付結果

按 audience 選擇 artifact：

• 技術協作者：Markdown memo。
• 運營團隊：spreadsheet 或 CSV。
• 格式和批註重要：.docx brief。
• 最終分享：PDF appendix 或 deliverable。
• 需要 URL：lightweight dashboard 或 static report site。

交付物必須包含 caveats。比如 join quality 不完美、sampling bias、model assumptions fragile，都應該寫進報告，而不是藏在工作過程裡。

可沉澱的 Skills

穩定後，把重複步驟做成 repo-local skills：

• refresh-data
• merge-and-qa
• publish-weekly-report

長期看，這比每次把同一段 procedural prompt 貼進執行緒更可靠。

驗收清單

• raw data 沒有被覆蓋。
• inventory、清洗指令碼、merged output 和報告都能重新生成。
• join strategy 有 match rate 和異常說明。
• 模型結論包含 controls、leakage risks 和不確定性。
• artifact 面向目標受眾，而不是隻給模型自己看。
• 報告明確寫出 caveats 和不能下結論的地方。