从数据集到分析报告

数据分析的目标不是“分析本身”，而是交付能被别人使用的 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 和不能下结论的地方。