---
title: "從資料集到分析報告"
description: "說明如何讓 Codex 把資料分析產出成可複查、可重跑、可交付的報告 artifact。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

> [!IMPORTANT]
> 資料任務最危險的不是畫錯圖，而是沒盤點資料、沒驗證 join、沒記錄 caveat，卻把結果包裝成結論。

<Cards>
  <Card title="Datasets and reports" href="https://developers.openai.com/codex/use-cases/datasets-and-reports">
    檢視官方資料分析與報告場景。
  </Card>
  <Card title="Skills" href="/zh-Hant/docs/codex/official/03-extensions/09-skills-reuse">
    把重複的清洗、匯出和報告步驟沉澱成 skill。
  </Card>
  <Card title="Worktrees" href="/zh-Hant/docs/codex/official/01-products/43-worktrees">
    用 worktree 隔離假設、merge 策略和視覺化分支。
  </Card>
</Cards>

## 適合什麼任務

```mermaid
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 的結論不能發表。

## 起始提示詞

```text
我正在这个 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` 就夠：

```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，也避免一個長執行緒混合互斥想法。

```bash
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 和不能下結論的地方。
