CSV 到洞察：用 AI CLI 建構資料分析管線

試算表打開了。然後呢？

你盯著一份 CSV 檔案。也許是上一季的銷售資料。也許是 production incident 的伺服器 log。也許是你 PM 丟到 Slack 上說「你能看一下這個嗎？」的問卷結果。

你知道答案就在數字裡面的某個地方。但要找到它，你得先打開 Jupyter、建一個 notebook、import pandas、寫載入的 code、處理編碼問題、處理缺失值、寫分析的 code、產生圖表、解讀結果。對資料科學家來說，這是 10 分鐘的例行公事。對其他人 -- 產品經理、後端工程師、維運團隊 -- 這是需要 Python 知識的 45 分鐘繞路。

真正的問題不是分析本身。是你在開始問問題之前要付的那筆設定稅。

AI CLI agent 完全消除了這個門檻。把 CSV 檔案 pipe 進 Claude Code，你就能拿到結構化分析、模式識別、異常偵測和圖表建議。全部在 terminal 裡完成。不需要 notebook。不需要 import pandas。不需要設定 matplotlib。Agent 讀取原始資料，用 extended thinking（一種讓模型在回應之前花更多時間處理複雜邏輯的模式）推理，然後產出一份你可以立刻採取行動的報告。

快速上手：單行指令分析

從 CSV 到洞察最快的路徑是一行 pipe 指令。想像成你請一個同事看一眼你的試算表，告訴你他看到什麼 -- 差別在於這個同事會讀完每一列。

假設你有一個檔案叫 sales_q1.csv：

date,region,product,units_sold,revenue,returns
2026-01-03,North,Widget-A,142,14200,3
2026-01-03,South,Widget-A,89,8900,12
2026-01-03,North,Widget-B,67,13400,1
2026-01-03,South,Widget-B,34,6800,8
2026-01-10,North,Widget-A,156,15600,2
2026-01-10,South,Widget-A,45,4500,18
2026-01-10,North,Widget-B,78,15600,0
2026-01-10,South,Widget-B,29,5800,11
2026-01-17,North,Widget-A,161,16100,4
2026-01-17,South,Widget-A,38,3800,22
2026-01-17,North,Widget-B,82,16400,1
2026-01-17,South,Widget-B,25,5000,15
2026-01-24,North,Widget-A,149,14900,5
2026-01-24,South,Widget-A,31,3100,25
2026-01-24,North,Widget-B,91,18200,2
2026-01-24,South,Widget-B,22,4400,19

執行：

cat sales_q1.csv | claude -p "Analyze this CSV data. Identify trends, anomalies, and actionable insights. Output as structured markdown."

-p flag 送出單次 prompt，不進互動模式。Claude Code 讀取 pipe 進來的 CSV，啟動 extended thinking 推理資料內容，輸出一份涵蓋欄位類型、摘要統計、趨勢識別和異常的 markdown 分析。

典型輸出包含：

• 欄位剖析 -- 資料類型、null 數量、每欄唯一值數量
• 摘要統計 -- 平均值、中位數、最小值、最大值（針對數值欄位）
• 趨勢識別 -- 「South 區 Widget-A 銷量逐週下滑：89 到 31 單位」
• 異常標記 -- 「South 區退貨率在所有產品上是 North 區的 5-8 倍」
• 可執行建議 -- 「調查 South 區的出貨流程或產品品質；退貨率趨勢正在加速」

這一行 pipe 指令就取代了快速一次性分析的 Jupyter notebook。

儲存輸出：cat | claude | tee 模式

分析結果消失在 scrollback 裡，等於沒做過。用 tee 在 terminal 顯示的同時把輸出存檔：

cat sales_q1.csv | claude -p "Analyze this CSV. Identify trends, anomalies, and recommendations. Format as markdown with headers." | tee analysis_report.md

現在你的磁碟上有 analysis_report.md，terminal 也有完整輸出。在另一個面板開啟 markdown 預覽，agent 還在跑的時候就能看到格式化的表格和標題。

這就是分割 terminal 配置發揮價值的地方。左面板：agent 處理資料、串流輸出。右面板：analysis_report.md 的即時 markdown 預覽隨著檔案增長而更新。你看著格式化的報告即時成形，就像邊看別人寫信邊讀內容。不需要切換視窗。

Structured Output：JSON 模式的機器可讀結果

當你的分析結果要餵給其他系統（儀表板、Slack 通知、下游腳本）時，你需要 structured output，不是散文。想像成填表格和寫信的差別。表格是可預測的，機器讀得懂。用 Claude Code 的 JSON 輸出模式：

cat sales_q1.csv | claude -p "Analyze this CSV data. Return a JSON object with these keys:
- summary: object with row_count, column_count, date_range
- columns: array of {name, type, null_count, unique_count}
- statistics: array of {column, mean, median, min, max, std_dev} for numeric columns
- trends: array of {description, direction, magnitude, confidence}
- anomalies: array of {description, severity, affected_rows}
- recommendations: array of strings
Output ONLY valid JSON, no markdown fencing." --output-format json

--output-format json flag 限制 Claude Code 只輸出合法 JSON。結果可以直接 pipe 進 jq 做後續處理：

cat sales_q1.csv | claude -p "..." --output-format json | jq '.anomalies[] | select(.severity == "high")'

這會只擷取高嚴重度的異常。串接通知：

cat sales_q1.csv | claude -p "..." --output-format json \
  | jq -r '.anomalies[] | select(.severity == "high") | .description' \
  | while read -r line; do echo "ALERT: $line"; done

完整管線腳本：多階段分析

單行指令適合快速檢查。但有時候你需要更深入的分析 -- 不是那種拿一張試算表問別人「你覺得呢？」的程度，而是「先做 profiling，再分析模式，然後根據你找到的東西給我建議」。

這就是多階段 pipeline 做的事。每個階段專注在一個工作上，把發現傳給下一階段。就像接力賽，每個跑者帶著前一個跑者的發現往前跑。

#!/bin/bash
# data-pipeline.sh — 三階段 CSV 分析管線
set -euo pipefail

CSV_FILE="${1:?Usage: ./data-pipeline.sh <file.csv>}"
BASENAME=$(basename "$CSV_FILE" .csv)
OUTPUT_DIR="./analysis_${BASENAME}_$(date +%Y%m%d)"
mkdir -p "$OUTPUT_DIR"

echo "=== Stage 1: Data Profiling ==="
cat "$CSV_FILE" | claude -p "Profile this CSV dataset. For each column: data type, null count, unique values, min/max for numerics, sample values. Output as JSON." \
  --output-format json \
  | tee "$OUTPUT_DIR/01_profile.json"

echo ""
echo "=== Stage 2: Deep Analysis ==="
cat "$CSV_FILE" | claude -p "You are a data analyst. Here is a CSV dataset.

Perform a thorough analysis:
1. Identify all statistically significant trends (week-over-week, region comparisons, product comparisons)
2. Flag anomalies with severity ratings (low/medium/high)
3. Calculate correlations between numeric columns
4. Segment the data by region and product, compare performance

Context from profiling stage:
$(cat "$OUTPUT_DIR/01_profile.json")

Output as structured markdown with clear headers." \
  | tee "$OUTPUT_DIR/02_analysis.md"

echo ""
echo "=== Stage 3: Recommendations ==="
cat "$CSV_FILE" | claude -p "Based on this data and the analysis below, generate actionable business recommendations.

Previous analysis:
$(cat "$OUTPUT_DIR/02_analysis.md")

For each recommendation:
- What to do
- Why (cite specific data points)
- Expected impact
- Priority (P0/P1/P2)

Output as structured markdown." \
  | tee "$OUTPUT_DIR/03_recommendations.md"

echo ""
echo "=== Pipeline complete. Results in $OUTPUT_DIR/ ==="

執行方式：

chmod +x data-pipeline.sh
./data-pipeline.sh sales_q1.csv

輸出目錄包含三個檔案：JSON profiling 結果、markdown 分析、markdown 建議報告。每個階段把輸出餵進下一個階段的 prompt 作為 context，所以建議會引用分析中的具體數據。

為什麼分三個階段而不是一次做完？ 拆開讓每個 prompt 專注在單一任務上。Profiling prompt 產生乾淨的 metadata。分析 prompt 用那些 metadata 跳過資料類型猜測，專注在模式上。建議 prompt 讀取分析結果後產生決策而非描述。每個階段也可以獨立檢視和重跑。Stage 2 漏掉什麼的話，只需要重跑那個階段，不用重做 profiling。

Extended Thinking：複雜資料推理

有些資料集的模式藏在表面之下。季節性、滯後指標、辛普森悖論 -- 那種快速掃一眼會得到錯誤答案，只有仔細推理才能找到正確答案的情況。

Extended thinking 就像請人坐下來花一小時看資料，而不是掃五分鐘。模型在產生回應之前分配更多推理 token，一步一步地推演邏輯。

cat sales_q1.csv | claude -p "Use extended thinking. This CSV contains sales data. I suspect there is a confounding variable driving the South region's poor performance. Analyze the data carefully:
1. Is the decline in South units real, or an artifact of product mix changes?
2. Are returns correlated with units sold, or is something else driving them?
3. What hypotheses explain the North-South divergence?
Think step by step before concluding." --thinking extended

Extended thinking 特別適合以下場景：

• 統計驗證 -- 「這個趨勢在統計上顯著，還是小樣本的雜訊？」
• 干擾變數識別 -- 「X 和 Y 的相關性可能是 Z 驅動的」
• 假說生成 -- 「這個異常有三種可能的解釋，依可能性排序」

--thinking extended flag 會消耗更多 token，但產出的分析是資料科學家會認可為嚴謹的，而非表面的。

CLAUDE.md 設定：重複分析的自動化

如果你定期分析類似的資料集 -- 每週銷售報告、每日伺服器指標、每月使用者回饋 -- 你面對的問題和圖書館面對常客一樣。你可以每次都問訪客需要什麼。或者你可以記住他們的偏好。

CLAUDE.md 就是那份記憶。在專案目錄設定它，讓每次分析 session 從正確的 context 開始：

# Data Analysis Project

## Context
This directory contains weekly CSV exports from our sales system.
File naming convention: sales_YYYY_WNN.csv (e.g., sales_2026_W12.csv)

## Analysis Standards
- Always check for null values and report them before analysis
- Revenue figures are in USD cents, not dollars — divide by 100 for display
- Return rate = returns / units_sold * 100, flag anything above 5% as anomalous
- Week-over-week comparisons should use the previous 4 weeks as baseline
- North and South regions have different seasonal patterns — do not combine them for trend analysis

## Output Format
- Start with a one-paragraph executive summary
- Follow with data quality notes (nulls, outliers, encoding issues)
- Main analysis with tables where appropriate
- End with numbered recommendations, each citing specific data points
- Save output as markdown to ./reports/

## Known Data Issues
- The "region" column sometimes contains "N" instead of "North" — treat as equivalent
- Rows with revenue=0 but units_sold>0 are data entry errors — exclude from analysis
- Q4 data has a known seasonal spike — do not flag Q4 increases as anomalies

有了這份 CLAUDE.md，在這個目錄下每次跑 claude 都會自動載入這些規則。Agent 知道要把 revenue 除以 100、退貨率超過 5% 要標記異常、revenue 為零的列要排除 -- 不需要你每次重複這些指示。就像一間記得你上次借了哪些書的圖書館。

Piping 模式：串接分析步驟

Unix 的 piping 哲學直接適用於 AI CLI 分析。資料流過一連串的轉換，每一步做好一件事。以下是實用的模式：

模式 1：先篩選再分析

# 只分析 South 區
grep -E "^date|,South," sales_q1.csv | claude -p "Analyze this regional data. What is driving the decline?"

模式 2：比較兩份資料集

paste <(cat q1_sales.csv | claude -p "Summarize this Q1 data as JSON" --output-format json) \
      <(cat q2_sales.csv | claude -p "Summarize this Q2 data as JSON" --output-format json) \
  | claude -p "Compare these two quarterly summaries. What changed?"

模式 3：分析然後行動

cat server_logs.csv | claude -p "Find any anomalies in these server logs. Output JSON with fields: is_anomaly (bool), description, severity." --output-format json \
  | jq 'select(.is_anomaly == true and .severity == "critical")' \
  | claude -p "Draft an incident report for these critical anomalies. Include timeline and recommended response."

模式 4：從原始資料驗證聲明

cat survey_results.csv | claude -p "Our PM claims that 'satisfaction scores improved 15% in Q1.' Verify this claim against the raw data. Show your math. State whether the claim is supported, unsupported, or misleading."

最後這個模式特別強大。與其信任簡報上的摘要，你把原始資料餵給 agent，請它驗證特定的聲明。Agent 會展示計算過程，讓你輕鬆看出聲明在哪裡對資料做了過度解讀。這是「我聽說銷量上升了」和「讓我看看實際數字」之間的差距。

實戰範例：使用者回饋分析

CSV 分析不限於數字。CSV 欄位中的文字資料（使用者回饋、客服工單、bug 回報）同樣適用 pipeline 方法。

cat feedback_march.csv | claude -p "This CSV has columns: user_id, date, rating (1-5), category, comment.

Perform a complete feedback analysis:
1. Rating distribution and trend over the month
2. Sentiment analysis of the comment column — group into positive, neutral, negative
3. Topic clustering — what are the top 5 themes in the comments?
4. Correlation between rating and category
5. Identify the 3 most actionable pieces of feedback (specific, fixable, high-impact)

Format as a structured report with tables."

Agent 同時讀取數值評分和自由文字評論，交叉比對，產出結合量化和質化分析的報告。傳統做法需要 pandas 處理數字、NLP 套件處理文字。AI CLI agent 在一次 pass 內處理兩者 -- 對語言模型來說，讀數字和讀文字不是不同的任務。

分割 Terminal Workflow

用 AI CLI agent 做資料分析，最有效的配置是兩個 terminal 面板並排。想像成你的實驗筆記本攤在實驗旁邊。

左面板：Agent 工作區。 在這裡執行分析指令。Agent 讀取 CSV、處理資料、串流輸出。跑完整 pipeline 腳本時，你看到每個階段依序完成。

右面板：報告預覽。 開啟輸出檔案的即時 markdown 預覽。當 agent 透過 tee 寫入 analysis_report.md，預覽即時更新。你看到格式化的表格、標題和項目符號在 agent 產生時即時出現。

這個配置讓你在分析過程中就能發現問題。如果 agent 誤解了一個欄位（例如把類別變數當作數值處理），你在格式化輸出中馬上看到，可以立刻中斷並修正。沒有並排視圖的話，你要等整個分析完成才會注意到 -- 到那時候每個後續結論都建立在錯誤的基礎上。

三階段 pipeline 的 workflow 是這樣的：

1. 左面板執行 ./data-pipeline.sh sales_q1.csv
2. 右面板預覽 analysis/02_analysis.md
3. 你在報告串流出來的同時閱讀格式化分析
4. 如果 Stage 2 遺漏了什麼，在 Stage 3 開始前於左面板追加一個 prompt
5. Stage 3 的建議在幾秒內出現在右面板預覽

Termdock 讓這個配置變得簡單：拖拉分割 terminal，把 markdown 檔案拖進右面板預覽，依需要調整面板大小。Agent 輸出和格式化報告在整個分析 session 中同時可見。

什麼時候該用（什麼時候不該）

AI CLI 資料分析適合：

• 50,000 行以內的快速一次性分析
• 載入資料庫前的資料品質檢查
• 從原始資料驗證聲明和統計數字
• 文字分析（回饋、工單、log）結合數值資料
• 產生初步分析讓資料科學家進一步精煉
• 團隊中不是每個人都會 Python 或 R 的情況

繼續用 Jupyter/pandas 的情況：

• 資料集超過 100,000 行（token 限制會成為真正的問題）
• 需要可重現、版本控制的分析 notebook
• 分析需要自訂統計模型或 ML pipeline
• 需要互動式視覺化（Plotly、D3）
• 法規要求可稽核的分析程式碼

最佳甜蜜點是資料小到能放進 context，但複雜到用試算表手動分析要花好幾個小時。對大多數商業資料（銷售報表、使用者指標、問卷結果、A/B 測試結果）來說，這涵蓋了大部分的臨時分析需求。

重點整理

用 AI CLI agent 做 CSV 到洞察的分析，替大多數臨時分析任務消除了 Jupyter 的前置門檻。核心模式：

1. 單行指令 -- cat data.csv | claude -p "Analyze this" 快速檢查
2. 儲存輸出 -- pipe 過 tee 把報告存成 markdown
3. Structured output -- 結果要餵給其他系統時用 --output-format json
4. 多階段 pipeline -- 把 profiling、分析、建議拆成獨立的 prompt
5. Extended thinking -- 資料有隱微模式時用 --thinking extended
6. CLAUDE.md -- 把領域知識編碼進去，讓重複分析 session 從正確的 context 開始

你的資料已經在 terminal 裡了。分析也應該在這裡發生。