Claude Codeでpandasのデータ処理を書く実践手順

pandasとClaude Codeを組み合わせる前提

pandasはCSVやExcel、SQLなど複数の形式からデータを読み込み、表形式(DataFrame)として整形・集計・結合するPythonライブラリです。導入はpip install pandasまたはconda install -c conda-forge pandasで完了します。

データの読み込みはread_csv・read_excel・read_sqlのようにread_で始まる関数に統一されています。書き出しもto_csv・to_excelのようにto_で始まるメソッドで揃っています。Claude Codeにスクリプトを書かせるときも、入力元がCSVかExcelかSQLかを最初に伝えておくと、選ぶ関数名がぶれずに済みます。

Claude Codeはファイルの読み書きとBashコマンドの実行を1つのセッションでこなせるため、「集計スクリプトを書かせる → 実行させる → 出力を確認させる → 直させる」という一連の流れを対話の中で回せます。このとき鍵になるのは、Bashコマンドをどこまで自動承認するかという権限設定と、実行結果を毎回どう検証させるかという2点です。この記事ではこの2点に絞って手順を扱います。

環境がまだない場合は、仮想環境を切ってpandasを入れるところから始めます。

python -m venv .venv
source .venv/bin/activate
pip install pandas
python -c "import pandas; print(pandas.__version__)"

ステップ1: Bashの実行権限を先に決める

pandasスクリプトを書かせるたびにpython analyze.pyの実行を承認していると、検証ループのたびに手が止まります。Claude Codeの権限ルールはBash(コマンド)の形式で書き、末尾にスペース区切りの*を置くと、その後に続く引数を問わず一致します。

{
  "permissions": {
    "allow": [
      "Bash(python *)",
      "Bash(pytest *)"
    ]
  }
}

このルールを.claude/settings.json(チーム共有)または.claude/settings.local.json(自分だけ)に書いておくと、pythonから始まるコマンドはすべて確認なしで実行されます。プロンプト上で「Yes, and don't ask again」を選んだときも、Claude Codeは同じ形式のルールを自動でローカル設定ファイルに書き足します。

特定のスクリプトだけに絞りたい場合は、ワイルドカードを使わずにBash(python scripts/aggregate.py)のように完全一致で書きます。実行のたびに引数が変わるなら、末尾のワイルドカードで対応します。

allowルールと合わせて、破壊的な操作を拒否するdenyルールも書いておくと安全です。Claude Codeは&&・||・;・|などの区切りでコマンドを分解し、区切られたサブコマンドごとにdeny・askルールを評価します。そのためBash(rm *)をdenyに入れておけば、python clean.py && rm -rf tmp/のように別コマンドと連結されたrmも個別に検知されます。

{
  "permissions": {
    "allow": ["Bash(python *)", "Bash(pytest *)"],
    "deny": ["Bash(rm *)"]
  }
}

denyルールはallowルールより優先され、より広い範囲を指定したdenyは、それに含まれる狭いallowを上書きします。集計・結合スクリプトの実行を自動化する場合でも、ファイルを消すコマンド系統は別枠でdenyに残しておく組み方が安全です。

ステップ2: 集計スクリプトを生成させる

pandasの集計は、複数行をグループごとにまとめて計算する「split-apply-combine」という考え方に沿っています。列でグループ化し、各グループに関数を適用し、結果を1つの表に戻す流れです。Claude Codeにはこの流れをそのまま伝えると、groupby()とagg()を組み合わせたスクリプトを書きます。

import pandas as pd
 
df = pd.read_csv("sales.csv")
summary = df.groupby("region").agg(
    total_amount=("amount", "sum"),
    order_count=("order_id", "count"),
)
summary.to_csv("summary_by_region.csv")

書かせたあとは、許可済みのBash(python *)ルールに沿ってそのまま実行させ、出力されたCSVの行数や合計値が入力データと矛盾していないかを確認させます。列名の誤りや欠損値の扱いはこの時点で見つかることが多く、対話の中でスクリプトを直しながら次のステップに進みます。

行×列で数値を突き合わせたい場合は、groupby().agg()の代わりにpivot_table()を使うようClaude Codeに指示します。pandasは集計を伴うピボットテーブルを1つの関数呼び出しで作れるため、groupbyより少ないコード量で同じ集計結果を縦横の表として得られます。どちらを使うかは、結果を後続処理でそのまま使うか(groupby)、人が見て比較する表として出したいか(pivot_table)で決めると指示がぶれません。

ステップ3: 結合スクリプトで複数テーブルを合わせる

複数の表を1つにまとめる処理は、pandasではmerge()やconcat()によるデータベースに近いjoin操作として提供されています。列方向(横に並べる)と行方向(縦に積む)のどちらで結合するかを最初に決めておくと、生成させる指示がぶれません。

import pandas as pd
 
orders = pd.read_csv("orders.csv")
customers = pd.read_csv("customers.csv")
 
merged = orders.merge(customers, on="customer_id", how="left")
merged.to_csv("orders_with_customers.csv", index=False)

結合キーの型が食い違っていたり、片方のテーブルにキーの重複があったりすると、結合後の行数が想定より増減します。Claude Codeに結合前後の行数をprint()で比較させておくと、この種のずれをその場で検出できます。

ステップ4: 検証ループを自動化する

対話セッションでの確認に慣れたら、同じスクリプトを繰り返し検証する部分は非対話モードに寄せられます。claude -pに--allowedToolsを渡すと、指定したツールだけを自動承認したまま1回のプロンプトで完結させられます。

claude -p "scripts/aggregate.pyを実行し、出力のNaN行数が0であることを確認して" \
  --allowedTools "Bash,Read"

Claude Codeは実行が成功すると終了コード0、失敗すると非0のコードを返すため、シェルスクリプトやCIのジョブはこの終了コードで次の処理を分岐できます。CI環境と手元の設定を完全に揃えたい場合は--bareを付けると、プロジェクトのhookやMCPサーバー、CLAUDE.mdを読み込まずに実行できます。ただし--bareを付けるとスキルやフックも動かなくなるため、後述のPostToolUse hookのような自動チェックは効きません。

検証ループを対話セッションで回す場合、Claude Codeはpythonスクリプトを実行したBashツールの標準出力・標準エラー出力をそのまま読み取ります。スクリプト側にassert文で行数や欠損値の条件を書いておくと、条件を満たさないときはトレースバックがそのままエラー出力に出ます。Claude Codeはそれを読んで原因の列を特定し、スクリプトを直してから再実行する、という一往復を自分で繰り返せます。人が毎回出力を目視するより、assertで機械的に検知できる条件を増やすほど、この往復の回数は減り、検証ループにかかる時間も短くなります。

出力ファイルを上書きする前に内容を人が確認したい場合は、claude --permission-mode planでプランモードに切り替えます。ステータスバーに⏸ plan mode onと表示されている間、Claude Codeはファイルを読むだけで編集は行わず、承認したプランに沿って初めて書き込みます。

実行方法は目的によって使い分けます。1つのスクリプトでも、設計中は対話セッション、固まったら自動承認、CIに載せる段階では非対話モードと、開発が進むにつれて上から下へ移っていくのが自然な流れです。

実行のたびに承認を挟まず、出力の異常だけを自動で拾いたい場合は、ファイル書き込み後に走るPostToolUse hookでCSVの行数チェックスクリプトを差し込む構成も組めます。承認の判定をコマンドの外から細かく制御したい場合は、Agent SDKのcanUseToolでBash呼び出しごとに許可・拒否を返すコールバックを書く方法もあります。

よくあるつまずき

Bash(python *)が対話的なpythonも許可してしまう

末尾の*はスペースの後に続く任意の文字列に一致するため、Bash(python *)はpython analyze.pyだけでなく引数なしのpython起動にも一致します。対話的なインタプリタの起動まで許可したくない場合は、実行するスクリプトのパスまで含めた完全一致のルールを個別に用意します。

出力ファイルへのリダイレクトは別扱いになる

python analyze.py > result.csvのようにシェルのリダイレクトで出力先を切り替えると、Bashの許可ルールはコマンドの実行を許可するだけで、リダイレクト先のパスは別途チェックされます。ホームディレクトリ配下やglob文字を含むパスへの書き込みは、許可ルールがあっても確認を求められることがあります。

--bareの有無でCIと手元の挙動が変わる

--bareを付けない非対話実行は、対話セッションと同じくプロジェクトの.claude/settings.jsonやMCPサーバーを読み込みます。CIで毎回同じ結果を得たいなら--bareで環境依存を切り離し、逆にPostToolUse hookによる自動チェックを効かせたいなら--bareを外す、と目的で使い分けます。

Excelを読み込むと依存パッケージ不足で落ちる

pd.read_excel()はpandas本体だけでは動かず、openpyxlのような追加パッケージを別途インストールする必要があります。CSVで検証が通っていたスクリプトを入力元だけExcelに変えるとImportErrorで止まることがあるため、入力形式を変えた回はこの種のエラーも検証ループの想定に含めておきます。

結合後の行数チェックを省略する

merge()は指定したキーが重複していると、その分だけ行が増えます。結合前後の行数をprintで比較する工程を省くと、想定より多い(または少ない)行数のまま次の集計に進んでしまい、誤りに気づくのが遅れます。

データソースがCSVではなくデータベースの場合、MCPサーバー経由で読み取り専用の接続を用意してからpandasに読み込ませる構成もあります。この場合に製品ごとで設定がどう違うかはデータベースMCPサーバーの読み取り専用設定の比較にまとめています。

まとめ

Claude Codeでpandasの集計・結合スクリプトを書かせる流れは、Bashの許可ルールで実行の摩擦を減らし、対話セッション・プランモード・非対話モードを目的に応じて使い分けることで安定します。集計はgroupbyによるsplit-apply-combine、結合はmerge・concatという基本操作を軸にスクリプトを生成させ、実行結果の行数や欠損値を都度確認させる検証ループを組めば、出力の誤りは早い段階で見つけられます。